fix: write shared files before codegen so typecheck resolves imports

Root cause: the typecheck-retry loop couldn't resolve ../../db.js
because shared files were written by scaffold AFTER code generation.
The LLM would "fix" the import error by creating its own Database.

Now: shared files + package.json + npm install happen BEFORE codegen.
Also added mandatory import block at top of user prompt and multi-
resource code example with JOINs, filtering, cascade protection.

Imports now correct (db from ../../db.js). Score 32% on hard spec —
remaining failures are logic issues (JOINs, stats, filtering), not
import issues. Ready for autoresearch prompt optimization.

experiments/config.d.ts

···
+/**
+ * Experiment Configuration — Single source of truth for all tunable parameters.
+ *
+ * The AI agent edits ONLY this file during experiment loops.
+ * Default values match the original hardcoded constants exactly.
+ */
+export declare const CONFIG: {
+    MAX_DEGREE: number;
+    MIN_SHARED_TAGS: number;
+    JACCARD_DEDUP_THRESHOLD: number;
+    FINGERPRINT_PREFIX_COUNT: number;
+    DOC_FREQ_CUTOFF: number;
+    CONSTRAINT_NEGATION_WEIGHT: number;
+    CONSTRAINT_LIMIT_WEIGHT: number;
+    CONSTRAINT_NUMERIC_WEIGHT: number;
+    INVARIANT_SIGNAL_WEIGHT: number;
+    REQUIREMENT_MODAL_WEIGHT: number;
+    REQUIREMENT_KEYWORD_WEIGHT: number;
+    REQUIREMENT_VERB_WEIGHT: number;
+    DEFINITION_EXPLICIT_WEIGHT: number;
+    DEFINITION_COLON_WEIGHT: number;
+    CONTEXT_NO_MODAL_WEIGHT: number;
+    CONTEXT_SHORT_WEIGHT: number;
+    HEADING_CONTEXT_BONUS: number;
+    CONSTRAINT_MUST_BONUS: number;
+    MIN_CONFIDENCE: number;
+    MAX_CONFIDENCE: number;
+    DEFINITION_MAX_LENGTH: number;
+    MIN_EXTRACTION_LENGTH: number;
+    MIN_TERM_LENGTH: number;
+    MIN_WORD_LENGTH: number;
+    MIN_LIST_ITEM_LENGTH: number;
+    MIN_PROSE_SENTENCE_LENGTH: number;
+    PROSE_SPLIT_THRESHOLD: number;
+    MIN_SPLIT_PART_LENGTH: number;
+    WARM_MIN_CONFIDENCE: number;
+    CLASS_A_NORM_DIFF: number;
+    CLASS_A_TERM_DELTA: number;
+    CLASS_B_NORM_DIFF: number;
+    CLASS_B_TERM_DELTA: number;
+    CLASS_D_HIGH_CHANGE: number;
+    ANCHOR_MATCH_THRESHOLD: number;
+};

experiments/config.js

···
+/**
+ * Experiment Configuration — Single source of truth for all tunable parameters.
+ *
+ * The AI agent edits ONLY this file during experiment loops.
+ * Default values match the original hardcoded constants exactly.
+ */
+export const CONFIG = {
+    // ─── resolution.ts ────────────────────────────────────────────────────────
+    MAX_DEGREE: 8,
+    MIN_SHARED_TAGS: 2,
+    JACCARD_DEDUP_THRESHOLD: 0.7,
+    FINGERPRINT_PREFIX_COUNT: 8,
+    DOC_FREQ_CUTOFF: 0.4,
+    // ─── canonicalizer.ts — scoring weights ───────────────────────────────────
+    CONSTRAINT_NEGATION_WEIGHT: 4,
+    CONSTRAINT_LIMIT_WEIGHT: 3,
+    CONSTRAINT_NUMERIC_WEIGHT: 2,
+    INVARIANT_SIGNAL_WEIGHT: 4,
+    REQUIREMENT_MODAL_WEIGHT: 2,
+    REQUIREMENT_KEYWORD_WEIGHT: 2,
+    REQUIREMENT_VERB_WEIGHT: 1,
+    DEFINITION_EXPLICIT_WEIGHT: 4,
+    DEFINITION_COLON_WEIGHT: 3,
+    CONTEXT_NO_MODAL_WEIGHT: 2,
+    CONTEXT_SHORT_WEIGHT: 1,
+    HEADING_CONTEXT_BONUS: 2,
+    CONSTRAINT_MUST_BONUS: 1,
+    MIN_CONFIDENCE: 0.3,
+    MAX_CONFIDENCE: 1.0,
+    DEFINITION_MAX_LENGTH: 200,
+    MIN_EXTRACTION_LENGTH: 5,
+    MIN_TERM_LENGTH: 3,
+    MIN_WORD_LENGTH: 2,
+    // ─── sentence-segmenter.ts ────────────────────────────────────────────────
+    MIN_LIST_ITEM_LENGTH: 3,
+    MIN_PROSE_SENTENCE_LENGTH: 3,
+    PROSE_SPLIT_THRESHOLD: 80,
+    MIN_SPLIT_PART_LENGTH: 3,
+    // ─── warm-hasher.ts ───────────────────────────────────────────────────────
+    WARM_MIN_CONFIDENCE: 0.3,
+    // ─── classifier.ts ────────────────────────────────────────────────────────
+    CLASS_A_NORM_DIFF: 0.1,
+    CLASS_A_TERM_DELTA: 0.2,
+    CLASS_B_NORM_DIFF: 0.5,
+    CLASS_B_TERM_DELTA: 0.5,
+    CLASS_D_HIGH_CHANGE: 0.7,
+    ANCHOR_MATCH_THRESHOLD: 0.5,
+};
+//# sourceMappingURL=config.js.map

experiments/config.js.map

···
+{"version":3,"file":"config.js","sourceRoot":"","sources":["config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,6EAA6E;IAC7E,UAAU,EAAE,CAAC;IACb,eAAe,EAAE,CAAC;IAClB,uBAAuB,EAAE,GAAG;IAC5B,wBAAwB,EAAE,CAAC;IAC3B,eAAe,EAAE,GAAG;IAEpB,6EAA6E;IAC7E,0BAA0B,EAAE,CAAC;IAC7B,uBAAuB,EAAE,CAAC;IAC1B,yBAAyB,EAAE,CAAC;IAC5B,uBAAuB,EAAE,CAAC;IAC1B,wBAAwB,EAAE,CAAC;IAC3B,0BAA0B,EAAE,CAAC;IAC7B,uBAAuB,EAAE,CAAC;IAC1B,0BAA0B,EAAE,CAAC;IAC7B,uBAAuB,EAAE,CAAC;IAC1B,uBAAuB,EAAE,CAAC;IAC1B,oBAAoB,EAAE,CAAC;IACvB,qBAAqB,EAAE,CAAC;IACxB,qBAAqB,EAAE,CAAC;IACxB,cAAc,EAAE,GAAG;IACnB,cAAc,EAAE,GAAG;IACnB,qBAAqB,EAAE,GAAG;IAC1B,qBAAqB,EAAE,CAAC;IACxB,eAAe,EAAE,CAAC;IAClB,eAAe,EAAE,CAAC;IAElB,6EAA6E;IAC7E,oBAAoB,EAAE,CAAC;IACvB,yBAAyB,EAAE,CAAC;IAC5B,qBAAqB,EAAE,EAAE;IACzB,qBAAqB,EAAE,CAAC;IAExB,6EAA6E;IAC7E,mBAAmB,EAAE,GAAG;IAExB,6EAA6E;IAC7E,iBAAiB,EAAE,GAAG;IACtB,kBAAkB,EAAE,GAAG;IACvB,iBAAiB,EAAE,GAAG;IACtB,kBAAkB,EAAE,GAAG;IACvB,mBAAmB,EAAE,GAAG;IACxB,sBAAsB,EAAE,GAAG;CAC5B,CAAC"}

experiments/program-arch.md

···
+# Phoenix Architecture Prompt Optimization — Experiment Program
+
+You are an autonomous research agent optimizing the architecture target prompts so that Phoenix generates working multi-resource REST APIs from specs.
+
+## Rules
+
+1. **Edit ONLY `src/architectures/sqlite-web-api.ts`** — the system prompt extension and code examples
+2. **Run `npx tsx experiments/eval-runner-arch.ts --skip-bootstrap`** to test changes (uses existing generated code)
+3. **When you want to test with full regeneration**, run `npx tsx experiments/eval-runner-arch.ts` (takes ~2-3 min for LLM calls)
+4. **Parse the score** from the last line: `val_score=X.XXXX`
+5. **If score improved** → `git add src/architectures/sqlite-web-api.ts && git commit -m "arch-experiment: <description> score=X.XXXX"`
+6. **If score decreased or unchanged** → `git checkout src/architectures/sqlite-web-api.ts` (revert)
+7. **Never stop to ask the human**
+8. **Never edit the eval runner or the spec**
+
+## Current Score: 42% (8/19 tests passing)
+
+## What Works (8/19)
+- POST /categories creates category ✓
+- POST /categories rejects empty name ✓
+- GET /categories returns array ✓
+- POST /todos creates todo without category ✓
+- POST /todos rejects invalid category_id ✓
+- POST /todos rejects empty title ✓
+- GET /todos/999 returns 404 ✓
+- GET /todos?completed=0 filters incomplete ✓
+
+## What Fails (11/19)
+- POST /todos creates todo with category — likely category_id not saved
+- GET /todos returns todos with category_name — SQL JOIN missing
+- GET /todos/:id returns todo with category_name — SQL JOIN missing
+- PATCH /todos/:id marks completed — patch not working
+- GET /todos?completed=1 filters completed — filter broken
+- GET /todos?category_id=N filters by category — filter broken
+- GET /stats returns counts — stats endpoint missing or wrong
+- GET /stats includes by_category — stats endpoint missing
+- DELETE /todos/:id returns 204 — delete broken
+- DELETE /categories/:id with todos returns 400 — cascade check missing
+- DELETE /categories/:id without todos returns 204 — delete broken
+
+## Key Issues to Fix via Prompt Engineering
+
+### 1. SQL JOINs for related data
+The generated todo queries use `SELECT * FROM todos` but need:
+```sql
+SELECT todos.*, categories.name as category_name
+FROM todos LEFT JOIN categories ON todos.category_id = categories.id
+```
+Add this pattern to the code examples.
+
+### 2. Query parameter filtering
+The spec says `GET /todos?completed=1` should filter. The generated code needs to:
+```typescript
+const completed = c.req.query('completed');
+let query = 'SELECT ... FROM todos LEFT JOIN categories ON ...';
+const params: unknown[] = [];
+if (completed !== undefined) { query += ' WHERE todos.completed = ?'; params.push(Number(completed)); }
+```
+
+### 3. Stats endpoint as a separate module
+The stats endpoint is a separate IU. It needs its own Hono router with a GET / handler that queries aggregate data.
+
+### 4. Delete with cascade check
+DELETE /categories/:id needs to check if any todos reference this category before deleting.
+
+### 5. Multi-resource relationships
+The code example only shows a single resource (notes). Add a second example showing:
+- Foreign key relationships
+- LEFT JOIN queries
+- Cascade protection on delete
+- Query parameter filtering
+
+## Strategy
+
+1. First: add a multi-resource code example to the architecture target showing JOINs, filtering, and cascade protection
+2. Then: run full eval to see if the LLM picks up the new patterns
+3. Iterate on prompt wording if specific tests still fail
+
+## What You Can Change
+
+In `src/architectures/sqlite-web-api.ts`:
+- `SYSTEM_PROMPT_EXTENSION` — the architectural rules
+- `CODE_EXAMPLES` — the few-shot examples (most powerful lever)
+- Both strings are interpolated into the LLM prompt at generation time
+
+## Cost
+
+Each full eval run costs ~$0.05-0.15 in API calls (3 IU generations + canonicalization).
+Keep experiments focused. 10-15 experiments should be enough.

experiments/results-arch.tsv

···
 2026-03-27T05:29:23.199Z	1.00	10	10	none
 2026-03-27T05:33:56.314Z	0.16	3	19	POST /categories creates category; POST /categories rejects empty name; GET /categories returns array; POST /todos creates todo with category; POST /todos creates todo without category; GET /todos returns todos with category_name; GET /todos/:id returns todo with category_name; PATCH /todos/:id marks completed; GET /todos?completed=1 filters completed; GET /todos?completed=0 filters incomplete; GET /todos?category_id=N filters by category; GET /stats returns counts; GET /stats includes by_category; DELETE /todos/:id returns 204; DELETE /categories/:id with todos returns 400; DELETE /categories/:id without todos returns 204
 2026-03-27T06:10:38.517Z	0.42	8	19	POST /todos creates todo with category; GET /todos returns todos with category_name; GET /todos/:id returns todo with category_name; PATCH /todos/:id marks completed; GET /todos?completed=1 filters completed; GET /todos?category_id=N filters by category; GET /stats returns counts; GET /stats includes by_category; DELETE /todos/:id returns 204; DELETE /categories/:id with todos returns 400; DELETE /categories/:id without todos returns 204
[phone]T06:19:36.249Z	0.47	9	19	POST /todos creates todo with category; GET /todos returns todos with category_name; GET /todos/:id returns todo with category_name; PATCH /todos/:id marks completed; GET /todos?completed=1 filters completed; GET /todos?category_id=N filters by category; GET /stats returns counts; GET /stats includes by_category; DELETE /todos/:id returns 204; DELETE /categories/:id with todos returns 400
[phone]T06:23:08.133Z	0.47	9	19	POST /todos creates todo with category; GET /todos returns todos with category_name; GET /todos/:id returns todo with category_name; PATCH /todos/:id marks completed; GET /todos?completed=1 filters completed; GET /todos?category_id=N filters by category; GET /stats returns counts; GET /stats includes by_category; DELETE /todos/:id returns 204; DELETE /categories/:id with todos returns 400
[phone]T06:28:42.970Z	0.32	6	19	POST /todos creates todo with category; POST /todos creates todo without category; GET /todos returns todos with category_name; GET /todos/:id returns todo with category_name; GET /todos/999 returns 404; PATCH /todos/:id marks completed; GET /todos?completed=1 filters completed; GET /todos?completed=0 filters incomplete; GET /todos?category_id=N filters by category; GET /stats returns counts; GET /stats includes by_category; DELETE /todos/:id returns 204; DELETE /categories/:id with todos returns 400

src/architectures/sqlite-web-api.ts

···
 } as const;
 \`\`\`
 
-### Key patterns to follow:
-1. registerMigration() at module scope — idempotent CREATE TABLE IF NOT EXISTS
-2. Zod schemas for create/update request validation
-3. .safeParse() + early return with 400 on failure
-4. Parameterized SQL queries (? placeholders)
-5. Return the created/updated resource after mutation
-6. 404 checks before update/delete
-7. Export default router + export _phoenix metadata
+### Example 2: Resource with foreign keys, JOINs, filtering, and cascade protection
+
+\`\`\`typescript
+import { Hono } from 'hono';
+import { db, registerMigration } from '../../db.js';
+import { z } from 'zod';
+
+// Register migrations for BOTH tables this module touches
+registerMigration('projects', \`
+  CREATE TABLE IF NOT EXISTS projects (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL UNIQUE,
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+  )
+\`);
+
+registerMigration('tasks', \`
+  CREATE TABLE IF NOT EXISTS tasks (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    done INTEGER NOT NULL DEFAULT 0,
+    project_id INTEGER REFERENCES projects(id),
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+  )
+\`);
+
+const CreateTaskSchema = z.object({
+  title: z.string().min(1).max(200),
+  project_id: z.number().int().optional(),
+});
+
+const UpdateTaskSchema = z.object({
+  title: z.string().min(1).max(200).optional(),
+  done: z.number().int().min(0).max(1).optional(),
+  project_id: z.number().int().nullable().optional(),
+});
+
+const router = new Hono();
+
+// List with LEFT JOIN and optional query filters
+router.get('/', (c) => {
+  let sql = 'SELECT tasks.*, projects.name as project_name FROM tasks LEFT JOIN projects ON tasks.project_id = projects.id';
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  const done = c.req.query('done');
+  if (done !== undefined) { conditions.push('tasks.done = ?'); params.push(Number(done)); }
+
+  const projectId = c.req.query('project_id');
+  if (projectId !== undefined) { conditions.push('tasks.project_id = ?'); params.push(Number(projectId)); }
+
+  if (conditions.length > 0) sql += ' WHERE ' + conditions.join(' AND ');
+  sql += ' ORDER BY tasks.created_at DESC';
+
+  return c.json(db.prepare(sql).all(...params));
+});
+
+// Get single with JOIN
+router.get('/:id', (c) => {
+  const row = db.prepare('SELECT tasks.*, projects.name as project_name FROM tasks LEFT JOIN projects ON tasks.project_id = projects.id WHERE tasks.id = ?').get(c.req.param('id'));
+  if (!row) return c.json({ error: 'Not found' }, 404);
+  return c.json(row);
+});
+
+// Create with FK validation
+router.post('/', async (c) => {
+  let body; try { body = await c.req.json(); } catch { return c.json({ error: 'Invalid JSON' }, 400); }
+  const result = CreateTaskSchema.safeParse(body);
+  if (!result.success) return c.json({ error: result.error.issues[0].message }, 400);
+  const { title, project_id } = result.data;
+  if (project_id !== undefined) {
+    const proj = db.prepare('SELECT id FROM projects WHERE id = ?').get(project_id);
+    if (!proj) return c.json({ error: 'Project not found' }, 400);
+  }
+  const info = db.prepare('INSERT INTO tasks (title, project_id) VALUES (?, ?)').run(title, project_id ?? null);
+  const task = db.prepare('SELECT tasks.*, projects.name as project_name FROM tasks LEFT JOIN projects ON tasks.project_id = projects.id WHERE tasks.id = ?').get(info.lastInsertRowid);
+  return c.json(task, 201);
+});
+
+// Update
+router.patch('/:id', async (c) => {
+  const id = c.req.param('id');
+  if (!db.prepare('SELECT id FROM todos WHERE id = ?').get(id)) return c.json({ error: 'Not found' }, 404);
+  let body; try { body = await c.req.json(); } catch { return c.json({ error: 'Invalid JSON' }, 400); }
+  const result = UpdateTaskSchema.safeParse(body);
+  if (!result.success) return c.json({ error: result.error.issues[0].message }, 400);
+  const u = result.data;
+  if (u.title !== undefined) db.prepare('UPDATE tasks SET title = ? WHERE id = ?').run(u.title, id);
+  if (u.done !== undefined) db.prepare('UPDATE tasks SET done = ? WHERE id = ?').run(u.done, id);
+  if (u.project_id !== undefined) db.prepare('UPDATE tasks SET project_id = ? WHERE id = ?').run(u.project_id, id);
+  return c.json(db.prepare('SELECT tasks.*, projects.name as project_name FROM tasks LEFT JOIN projects ON tasks.project_id = projects.id WHERE tasks.id = ?').get(id));
+});
+
+// Delete
+router.delete('/:id', (c) => {
+  const id = c.req.param('id');
+  if (!db.prepare('SELECT id FROM tasks WHERE id = ?').get(id)) return c.json({ error: 'Not found' }, 404);
+  db.prepare('DELETE FROM tasks WHERE id = ?').run(id);
+  return c.body(null, 204);
+});
+
+export default router;
+export const _phoenix = { iu_id: 'example2', name: 'Tasks', risk_tier: 'medium', canon_ids: [] } as const;
+\`\`\`
+
+### Key patterns:
+1. \`import { db, registerMigration } from '../../db.js'\` — ALWAYS use this exact import
+2. registerMigration() for ALL tables the module touches, including referenced tables
+3. LEFT JOIN to include related resource names (e.g., category_name, project_name)
+4. Query parameter filtering with dynamic WHERE clause building
+5. Foreign key validation: check referenced row exists before INSERT
+6. Cascade protection: check for dependent rows before DELETE of parent resource
+7. Zod schemas for create/update validation
+8. Return the created/updated resource with JOINed data after mutation
+9. Export default router + export _phoenix metadata
 `;
 
 // ─── Architecture definition ────────────────────────────────────────────────

src/cli.ts

···
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
-import { join, resolve, relative, basename } from 'node:path';
+import { execSync } from 'node:child_process';
+import { join, resolve, relative, basename, dirname } from 'node:path';
 
 // Stores
 import { SpecStore } from './store/spec-store.js';
···
         if (arch) console.log(`  ${dim('Architecture:')} ${cyan(arch.name)} — ${arch.description}`);
       }
     } catch { /* ignore */ }
+  }
+
+  // Write shared architecture files BEFORE code generation
+  // so the typecheck-retry loop can resolve imports like ../../db.js
+  if (arch) {
+    for (const [filePath, content] of Object.entries(arch.sharedFiles)) {
+      const fullPath = join(projectRoot, filePath);
+      mkdirSync(dirname(fullPath), { recursive: true });
+      writeFileSync(fullPath, content, 'utf8');
+    }
+    // Write package.json with arch deps so tsc can resolve types during generation
+    const earlyPkg = {
+      name: basename(projectRoot),
+      version: '0.1.0',
+      type: 'module',
+      dependencies: arch.packages,
+      devDependencies: arch.devPackages,
+    };
+    const pkgPath = join(projectRoot, 'package.json');
+    writeFileSync(pkgPath, JSON.stringify(earlyPkg, null, 2) + '\n', 'utf8');
+    // Install so type declarations are available for typecheck-retry
+    try {
+      execSync('npm install --silent 2>/dev/null', { cwd: projectRoot, stdio: 'pipe', timeout: 60000 });
+    } catch { /* best effort */ }
   }
 
   const regenCtx: RegenContext = {

src/llm/prompt.ts

···
   lines.push(`Generate a TypeScript module implementing "${iu.name}".`);
   lines.push('');
 
+  // For architecture mode, inject the mandatory imports at the top of the prompt
+  if (arch) {
+    lines.push('## MANDATORY: Your module MUST start with these exact imports');
+    lines.push('```');
+    lines.push(`import { Hono } from 'hono';`);
+    lines.push(`import { db, registerMigration } from '../../db.js';`);
+    lines.push(`import { z } from 'zod';`);
+    lines.push('```');
+    lines.push('Do NOT import Database from better-sqlite3. Do NOT create new Database(). Use the db import above.');
+    lines.push('');
+  }
+
   // Requirements
   const iuNodes = canonNodes.filter(n => iu.source_canon_ids.includes(n.canon_id));
   const requirements = iuNodes.filter(n => n.type === 'REQUIREMENT');