ultra-builder-pro-cli 0.12.1 → 0.14.0

package/mcp-server/lib/task-expander.test.cjs

@@ -1,10 +1,5 @@
 'use strict';
 
-// Integration tests for task-expander — real SQLite (Testcontainers-style
-// in-process) so parent_id column + status transition + task_expanded event
-// are exercised end-to-end. The only Test Double is the LLM client, which
-// we inject with deterministic child fixtures.
-
 const test = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
@@ -13,11 +8,17 @@ const path = require('node:path');
 
 const { initStateDb, closeStateDb } = require('./state-db.cjs');
 const ops = require('./state-ops.cjs');
+const changes = require('./change-workflow.cjs');
 const { expandTask, TaskExpandError } = require('./task-expander.cjs');
 
 function tmpDb() {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-expand-'));
   const { db } = initStateDb(path.join(dir, 'state.db'));
+  db.prepare(
+    `INSERT INTO baselines
+     (id, project_name, mode, status, approved_by, approval_note, converged_at)
+     VALUES ('test-baseline', 'fixture', 'greenfield', 'ready', 'test', 'fixture', ?)`,
+  ).run(new Date().toISOString());
   return { dir, db };
 }
 
@@ -26,23 +27,6 @@ function cleanup({ dir, db }) {
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
-function fakeLlm(childrenJson, { shouldFail = false, usage = {} } = {}) {
-  return {
-    provider: 'anthropic',
-    model: 'claude-sonnet-4-6',
-    async completeJson() {
-      if (shouldFail) throw new Error('upstream LLM 500');
-      return {
-        json: { children: childrenJson },
-        raw: JSON.stringify({ children: childrenJson }),
-        usage,
-        model: 'claude-sonnet-4-6',
-        provider: 'anthropic',
-      };
-    },
-  };
-}
-
 function seedParent(db, overrides = {}) {
   return ops.createTask(db, {
     id: 'parent-1',
@@ -56,198 +40,130 @@ function seedParent(db, overrides = {}) {
 }
 
 const HAPPY_CHILDREN = [
-  { id: 'child-1', title: 'Design auth schema',       type: 'architecture', priority: 'P1', complexity: 4, deps: [],          files_modified: ['src/auth/schema.ts'] },
-  { id: 'child-2', title: 'Implement login endpoint', type: 'feature',      priority: 'P1', complexity: 5, deps: ['child-1'], files_modified: ['src/auth/login.ts']  },
-  { id: 'child-3', title: 'Add signup endpoint',      type: 'feature',      priority: 'P2', complexity: 3, deps: ['child-1'], files_modified: ['src/auth/signup.ts'] },
+  { id: 'child-1', title: 'Design auth schema', type: 'architecture', priority: 'P1', complexity: 4, deps: [], files_modified: ['src/auth/schema.ts'] },
+  { id: 'child-2', title: 'Implement login endpoint', type: 'feature', priority: 'P1', complexity: 5, deps: ['child-1'], files_modified: ['src/auth/login.ts'] },
+  { id: 'child-3', title: 'Add signup endpoint', type: 'feature', priority: 'P2', complexity: 3, deps: ['child-1'], files_modified: ['src/auth/signup.ts'] },
 ];
 
-test('expandTask happy path: creates children, flips parent status, emits task_expanded', async () => {
+test('expandTask atomically persists host-derived children without a provider client', () => {
   const ctx = tmpDb();
   try {
     seedParent(ctx.db);
-    const result = await expandTask(ctx.db, {
-      id: 'parent-1',
-      strategy: 'llm',
-      llmClient: fakeLlm(HAPPY_CHILDREN),
-    });
+    const result = expandTask(ctx.db, { id: 'parent-1', children: HAPPY_CHILDREN });
     assert.equal(result.parent_id, 'parent-1');
     assert.equal(result.children.length, 3);
-
-    const parentAfter = ops.readTask(ctx.db, 'parent-1');
-    assert.equal(parentAfter.status, 'expanded');
-
+    assert.equal(ops.readTask(ctx.db, 'parent-1').status, 'expanded');
     for (const child of HAPPY_CHILDREN) {
       const row = ops.readTask(ctx.db, child.id);
-      assert.ok(row, `child ${child.id} missing`);
       assert.equal(row.parent_id, 'parent-1');
       assert.equal(row.status, 'pending');
     }
-
-    const events = ops.subscribeEventsSince(ctx.db, { since_id: 0, limit: 100 });
-    const expandedEvents = events.events.filter((e) => e.type === 'task_expanded');
-    assert.equal(expandedEvents.length, 1);
-    assert.equal(expandedEvents[0].task_id, 'parent-1');
-    const createdEvents = events.events.filter((e) => e.type === 'task_created');
-    assert.ok(createdEvents.length >= 4, 'parent + 3 children task_created events');
-  } finally {
-    cleanup(ctx);
-  }
+    const events = ops.subscribeEventsSince(ctx.db, { since_id: 0, limit: 100 }).events;
+    assert.equal(events.filter((event) => event.type === 'task_expanded').length, 1);
+  } finally { cleanup(ctx); }
 });
 
-test('expandTask: missing parent → TASK_NOT_FOUND', async () => {
+test('expandTask rejects missing and already expanded parents', () => {
   const ctx = tmpDb();
   try {
-    await assert.rejects(
-      expandTask(ctx.db, {
-        id: 'does-not-exist',
-        llmClient: fakeLlm(HAPPY_CHILDREN),
-      }),
+    assert.throws(
+      () => expandTask(ctx.db, { id: 'missing', children: HAPPY_CHILDREN }),
       (err) => err instanceof TaskExpandError && err.code === 'TASK_NOT_FOUND',
     );
-  } finally {
-    cleanup(ctx);
-  }
-});
-
-test('expandTask: already-expanded parent → ALREADY_EXPANDED', async () => {
-  const ctx = tmpDb();
-  try {
     seedParent(ctx.db);
-    // First expansion succeeds
-    await expandTask(ctx.db, {
-      id: 'parent-1',
-      llmClient: fakeLlm(HAPPY_CHILDREN),
-    });
-    // Second attempt must refuse
-    await assert.rejects(
-      expandTask(ctx.db, {
-        id: 'parent-1',
-        llmClient: fakeLlm(HAPPY_CHILDREN.map((c, i) => ({ ...c, id: `other-${i}` }))),
-      }),
+    expandTask(ctx.db, { id: 'parent-1', children: HAPPY_CHILDREN });
+    assert.throws(
+      () => expandTask(ctx.db, { id: 'parent-1', children: [{ ...HAPPY_CHILDREN[0], id: 'other' }] }),
       (err) => err instanceof TaskExpandError && err.code === 'ALREADY_EXPANDED',
     );
-  } finally {
-    cleanup(ctx);
-  }
-});
-
-test('expandTask: strategy="manual" → NOT_IMPLEMENTED', async () => {
-  const ctx = tmpDb();
-  try {
-    seedParent(ctx.db);
-    await assert.rejects(
-      expandTask(ctx.db, {
-        id: 'parent-1',
-        strategy: 'manual',
-        llmClient: fakeLlm(HAPPY_CHILDREN),
-      }),
-      (err) => err instanceof TaskExpandError && err.code === 'NOT_IMPLEMENTED',
-    );
-  } finally {
-    cleanup(ctx);
-  }
-});
-
-test('expandTask: missing llmClient → NO_LLM_CLIENT', async () => {
-  const ctx = tmpDb();
-  try {
-    seedParent(ctx.db);
-    await assert.rejects(
-      expandTask(ctx.db, { id: 'parent-1' }),
-      (err) => err instanceof TaskExpandError && err.code === 'NO_LLM_CLIENT',
-    );
-  } finally {
-    cleanup(ctx);
-  }
-});
-
-test('expandTask: LLM throws → LLM_CALL_FAILED', async () => {
-  const ctx = tmpDb();
-  try {
-    seedParent(ctx.db);
-    await assert.rejects(
-      expandTask(ctx.db, {
-        id: 'parent-1',
-        llmClient: fakeLlm([], { shouldFail: true }),
-      }),
-      (err) => err instanceof TaskExpandError && err.code === 'LLM_CALL_FAILED',
-    );
-    // parent status must be unchanged
-    assert.equal(ops.readTask(ctx.db, 'parent-1').status, 'pending');
-  } finally {
-    cleanup(ctx);
-  }
+  } finally { cleanup(ctx); }
 });
 
-test('expandTask: invalid child shape → INVALID_OUTPUT, parent untouched', async () => {
+test('expandTask requires valid host-derived children and leaves the parent untouched on failure', () => {
   const ctx = tmpDb();
   try {
     seedParent(ctx.db);
-    const bad = [{ id: 'child-1', title: 'x', type: 'feature', priority: 'P1' }]; // title too short
-    await assert.rejects(
-      expandTask(ctx.db, { id: 'parent-1', llmClient: fakeLlm(bad) }),
-      (err) => err instanceof TaskExpandError && err.code === 'INVALID_OUTPUT',
-    );
-    assert.equal(ops.readTask(ctx.db, 'parent-1').status, 'pending');
-  } finally {
-    cleanup(ctx);
-  }
+    for (const children of [undefined, [], [{
+      id: 'child-1', title: 'x', type: 'feature', priority: 'P1',
+    }]]) {
+      assert.throws(
+        () => expandTask(ctx.db, { id: 'parent-1', children }),
+        (err) => err instanceof TaskExpandError && err.code === 'INVALID_OUTPUT',
+      );
+      assert.equal(ops.readTask(ctx.db, 'parent-1').status, 'pending');
+    }
+  } finally { cleanup(ctx); }
 });
 
-test('expandTask: duplicate child id → INVALID_OUTPUT', async () => {
+test('expandTask rejects duplicate child ids', () => {
   const ctx = tmpDb();
   try {
     seedParent(ctx.db);
-    const dup = [
-      { id: 'same', title: 'First child',  type: 'feature', priority: 'P2' },
-      { id: 'same', title: 'Second child', type: 'feature', priority: 'P2' },
-    ];
-    await assert.rejects(
-      expandTask(ctx.db, { id: 'parent-1', llmClient: fakeLlm(dup) }),
+    assert.throws(
+      () => expandTask(ctx.db, { id: 'parent-1', children: [
+        { id: 'same', title: 'First child', type: 'feature', priority: 'P2' },
+        { id: 'same', title: 'Second child', type: 'feature', priority: 'P2' },
+      ] }),
       (err) => err instanceof TaskExpandError && err.code === 'INVALID_OUTPUT',
     );
-  } finally {
-    cleanup(ctx);
-  }
+  } finally { cleanup(ctx); }
 });
 
-test('expandTask: tx rollback — child id collides with existing task → parent status unchanged, no children inserted', async () => {
+test('expandTask rolls back every child when one id collides', () => {
   const ctx = tmpDb();
   try {
     seedParent(ctx.db);
-    // Pre-create a task with the same id one of the children will try
     ops.createTask(ctx.db, {
-      id: 'child-1',
-      title: 'Pre-existing task',
-      type: 'bugfix',
-      priority: 'P3',
+      id: 'child-1', title: 'Pre-existing task', type: 'bugfix', priority: 'P3',
     });
-    await assert.rejects(
-      expandTask(ctx.db, { id: 'parent-1', llmClient: fakeLlm(HAPPY_CHILDREN) }),
-      /* any error is acceptable — the point is no partial state */
-    );
+    assert.throws(() => expandTask(ctx.db, { id: 'parent-1', children: HAPPY_CHILDREN }));
     assert.equal(ops.readTask(ctx.db, 'parent-1').status, 'pending');
-    // child-2 / child-3 must NOT have been inserted
     assert.equal(ops.readTask(ctx.db, 'child-2'), null);
     assert.equal(ops.readTask(ctx.db, 'child-3'), null);
-  } finally {
-    cleanup(ctx);
-  }
+  } finally { cleanup(ctx); }
 });
 
-test('expandTask: children inherit parent tag', async () => {
+test('expandTask children inherit parent tag and change ownership', () => {
   const ctx = tmpDb();
   try {
-    seedParent(ctx.db, { tag: 'feat-auth' });
-    await expandTask(ctx.db, {
-      id: 'parent-1',
-      llmClient: fakeLlm(HAPPY_CHILDREN),
+    const { change } = changes.createChange(ctx.db, {
+      id: 'expand-change', title: 'Expand one task', kind: 'quick',
+      intent: 'Keep child ownership inside the active change.',
+      docs_impact: { status: 'none', rationale: 'test fixture' },
+    }, { rootDir: ctx.dir });
+    seedParent(ctx.db, { tag: 'feat-auth', change_id: change.id });
+    const result = expandTask(ctx.db, {
+      id: 'parent-1', children: HAPPY_CHILDREN, rootDir: ctx.dir,
     });
-    for (const child of HAPPY_CHILDREN) {
+    for (const child of result.children) {
       const row = ops.readTask(ctx.db, child.id);
       assert.equal(row.tag, 'feat-auth');
+      assert.equal(row.change_id, change.id);
     }
-  } finally {
-    cleanup(ctx);
+  } finally { cleanup(ctx); }
+});
+
+test('expandTask enforces baseline authority before writing children', () => {
+  for (const baseline of ['missing', 'draft', 'migrated']) {
+    const ctx = tmpDb();
+    try {
+      seedParent(ctx.db);
+      if (baseline === 'missing') ctx.db.prepare('DELETE FROM baselines').run();
+      else if (baseline === 'draft') {
+        ctx.db.prepare("UPDATE baselines SET status = 'draft' WHERE id = 'test-baseline'").run();
+      } else {
+        ctx.db.prepare(
+          "UPDATE baselines SET mode = 'migrated', status = 'adopting' WHERE id = 'test-baseline'",
+        ).run();
+      }
+      assert.throws(
+        () => expandTask(ctx.db, {
+          id: 'parent-1', children: HAPPY_CHILDREN, rootDir: ctx.dir,
+        }),
+        (error) => error.code === 'BASELINE_NOT_READY',
+      );
+      assert.equal(ops.readTask(ctx.db, 'child-1'), null);
+      assert.equal(ops.readTask(ctx.db, 'parent-1').status, 'pending');
+    } finally { cleanup(ctx); }
   }
 });

package/mcp-server/server.cjs

@@ -23,7 +23,6 @@ const ops = require('./lib/state-ops.cjs');
 const projector = require('./lib/projector.cjs');
 const telemetry = require('./lib/telemetry.cjs');
 const topo = require('./lib/topo.cjs');
-const llm = require('./lib/llm-client.cjs');
 const parser = require('./lib/prd-parser.cjs');
 const expander = require('./lib/task-expander.cjs');
 const planStore = require('./lib/plan-store.cjs');
@@ -32,6 +31,10 @@ const baselines = require('./lib/baseline-workflow.cjs');
 const changes = require('./lib/change-workflow.cjs');
 const runtimeState = require('./lib/runtime-state.cjs');
 const doctor = require('./lib/doctor.cjs');
+const {
+  readProjectBreadcrumb,
+  renderProjectBreadcrumb,
+} = require('./lib/project-breadcrumb.cjs');
 
 const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
   ? path.resolve(process.env.UBP_RUNTIME_ROOT)
@@ -127,28 +130,15 @@ function mintSessionId() {
   return `sess-${randomUUID().slice(0, 8)}`;
 }
 
-function resolvePrdText(input, ctx) {
-  if (input.prd_text && String(input.prd_text).trim()) return String(input.prd_text);
-  if (input.prd_path) {
-    const abs = path.isAbsolute(input.prd_path)
-      ? input.prd_path
-      : path.join(ctx.rootDir || process.cwd(), input.prd_path);
-    return fs.readFileSync(abs, 'utf8');
-  }
-  return null;
-}
-
-function buildLlmClient(ctx) {
-  if (ctx && ctx.llmClient) return ctx.llmClient;
-  return llm.createLlmClient({});
-}
-
 async function dispatchTool(name, input, db, ctx = {}) {
   switch (name) {
     case 'task.create': {
       const { randomUUID } = require('node:crypto');
       const id = input.id || `task-${randomUUID()}`;
-      const task = ops.createTask(db, { ...input, id });
+      const changeId = ops.resolveTaskCreationChangeId(db, input);
+      const authorizedInput = { ...input, change_id: changeId };
+      changes.assertTaskCreationAllowed(db, authorizedInput, { rootDir: ctx.rootDir || process.cwd() });
+      const task = ops.createTask(db, { ...authorizedInput, id });
       return { id: task.id, status: task.status, created_at: task.created_at };
     }
     case 'task.update': {
@@ -280,39 +270,44 @@ async function dispatchTool(name, input, db, ctx = {}) {
       return { waves: result.waves };
     }
     case 'task.parse_prd': {
-      const prdText = resolvePrdText(input, ctx);
-      if (!prdText || !prdText.trim()) {
-        const err = new Error('one of prd_path or prd_text required');
-        err.code = 'NO_INPUT';
-        throw err;
-      }
-      const client = buildLlmClient(ctx);
-      const parsed = await parser.parsePrd(prdText, { llmClient: client, tag: input.tag });
+      const dryRun = input.dry_run === true;
+      const rootDir = ctx.rootDir || process.cwd();
+      const creationAuthority = { change_id: input.change_id };
+      if (!dryRun) changes.assertTaskCreationAllowed(db, creationAuthority, { rootDir });
+      const parsed = parser.parsePrd(input.tasks, {
+        tag: input.tag,
+        changeId: input.change_id,
+      });
       const shaped = parsed.tasks.map((t) => ({
         id: t.id, title: t.title, type: t.type, priority: t.priority,
         complexity: t.complexity, deps: t.deps, files_modified: t.files_modified,
-        tag: t.tag,
+        tag: t.tag, change_id: t.change_id,
       }));
-      const dryRun = input.dry_run === true;
+      const graph = shaped.map((t) => ({ id: t.id, deps: t.deps || [] }));
+      const topoResult = topo.computeWaves(graph);
+      if (topoResult.cycles.length > 0) {
+        const err = new Error(`parsed task graph has ${topoResult.cycles.length} cycle(s)`);
+        err.code = 'CYCLE_DETECTED';
+        err.details = { cycles: topoResult.cycles };
+        throw err;
+      }
       if (!dryRun) {
         try {
           ops.tx(db, () => {
+            changes.assertTaskCreationAllowed(db, creationAuthority, { rootDir });
             for (const t of shaped) ops.createTask(db, t);
           });
         } catch (err) {
+          if (['BASELINE_NOT_READY', 'CHANGE_NOT_FOUND', 'CHANGE_NOT_MUTABLE'].includes(err.code)) throw err;
           const wrap = new Error(`failed to persist parsed tasks: ${err.message}`);
           wrap.code = 'PARSE_FAILED';
           wrap.cause = err;
           throw wrap;
         }
       }
-      const graph = shaped.map((t) => ({ id: t.id, deps: t.deps || [] }));
-      const topoResult = topo.computeWaves(graph);
       return { tasks: shaped, topo: topoResult.waves };
     }
     case 'task.expand': {
-      // Cheap guards before paying for LLM client construction (which would
-      // throw NO_LLM_CREDENTIALS when env keys are missing).
       const parent = ops.readTask(db, input.id);
       if (!parent) {
         const err = new Error(`no task ${input.id}`);
@@ -324,12 +319,12 @@ async function dispatchTool(name, input, db, ctx = {}) {
         err.code = 'ALREADY_EXPANDED';
         throw err;
       }
-      const client = buildLlmClient(ctx);
-      const result = await expander.expandTask(db, {
+      const rootDir = ctx.rootDir || process.cwd();
+      changes.assertTaskCreationAllowed(db, { change_id: parent.change_id }, { rootDir });
+      const result = expander.expandTask(db, {
         id: input.id,
-        sub_count: input.sub_count,
-        strategy: input.strategy,
-        llmClient: client,
+        children: input.children,
+        rootDir,
       });
       return { parent_id: result.parent_id, children: result.children };
     }
@@ -648,4 +643,6 @@ module.exports = {
   REGISTERED_TOOLS,
   STATELESS_TOOLS,
   MUTATING_TOOLS,
+  readProjectBreadcrumb,
+  renderProjectBreadcrumb,
 };

package/mcp-server/tests/init-project.test.cjs

@@ -8,7 +8,9 @@ const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const Database = require('better-sqlite3');
 
-const { initProject, InitProjectError, DEFAULT_TEMPLATE } = require('../lib/init-project.cjs');
+const {
+  initProject, InitProjectError, DEFAULT_TEMPLATE, classifyRepository,
+} = require('../lib/init-project.cjs');
 const { EXPECTED_VERSION } = require('../lib/state-db.cjs');
 
 function mkTempDir(prefix = 'ubp-init-test-') {
@@ -71,6 +73,85 @@ test('initProject auto-detects existing source as brownfield and starts adoption
   } finally { cleanup(target); }
 });
 
+test('auto classification keeps a documentation-and-manifest-only skeleton greenfield', () => {
+  const target = mkTempDir();
+  try {
+    fs.writeFileSync(path.join(target, 'README.md'), '# New service skeleton\n');
+    fs.writeFileSync(path.join(target, 'package.json'), JSON.stringify({
+      name: 'new-service', private: true, scripts: { test: 'node --test' },
+    }));
+    const profile = classifyRepository(target);
+    assert.equal(profile.mode, 'greenfield');
+    assert.equal(profile.repository_kind, 'single');
+    assert.deepEqual(profile.source_signals, []);
+
+    const result = initProject({ target_dir: target, project_name: 'new-service' });
+    assert.equal(result.mode, 'greenfield');
+    assert.deepEqual(result.repository_profile.verification_commands, ['npm test']);
+  } finally { cleanup(target); }
+});
+
+test('auto classification records bounded monorepo evidence for brownfield adoption', () => {
+  const target = mkTempDir();
+  try {
+    fs.mkdirSync(path.join(target, 'packages', 'api', 'src'), { recursive: true });
+    fs.writeFileSync(path.join(target, 'package.json'), JSON.stringify({
+      name: 'legacy-suite', private: true, workspaces: ['packages/*'],
+      scripts: { build: 'turbo build', test: 'turbo test', lint: 'turbo lint' },
+    }));
+    fs.writeFileSync(path.join(target, 'packages', 'api', 'package.json'), '{"name":"api"}\n');
+    fs.writeFileSync(path.join(target, 'packages', 'api', 'src', 'index.js'), 'module.exports = true;\n');
+    fs.writeFileSync(path.join(target, 'Dockerfile'), 'FROM node:22\n');
+
+    const result = initProject({ target_dir: target, project_name: 'legacy-suite' });
+    assert.equal(result.mode, 'brownfield');
+    assert.equal(result.repository_profile.repository_kind, 'monorepo');
+    assert.deepEqual(result.repository_profile.workspace_roots, ['packages/api']);
+    assert.ok(result.repository_profile.source_signals.includes('packages/api/src/index.js'));
+    assert.ok(result.repository_profile.deployment_signals.includes('Dockerfile'));
+    assert.deepEqual(
+      result.repository_profile.verification_commands,
+      ['npm run build', 'npm test', 'npm run lint'],
+    );
+
+    const db = new Database(result.state_db_path, { readonly: true });
+    try {
+      const row = db.prepare(
+        'SELECT repository_branch, worktree_state, classification_json FROM baselines',
+      ).get();
+      assert.equal(row.repository_branch, null);
+      assert.equal(row.worktree_state, 'unavailable');
+      assert.equal(JSON.parse(row.classification_json).repository_kind, 'monorepo');
+    } finally { db.close(); }
+  } finally { cleanup(target); }
+});
+
+test('brownfield initialization persists an explicitly selected monorepo scope', () => {
+  const target = mkTempDir();
+  try {
+    fs.mkdirSync(path.join(target, 'packages', 'api', 'src'), { recursive: true });
+    fs.mkdirSync(path.join(target, 'packages', 'web', 'src'), { recursive: true });
+    fs.writeFileSync(path.join(target, 'package.json'), JSON.stringify({
+      name: 'legacy-suite', private: true, workspaces: ['packages/*'],
+    }));
+    fs.writeFileSync(path.join(target, 'packages', 'api', 'src', 'index.js'), 'module.exports = true;\n');
+    fs.writeFileSync(path.join(target, 'packages', 'web', 'src', 'index.js'), 'module.exports = true;\n');
+
+    const result = initProject({
+      target_dir: target,
+      project_name: 'legacy-suite',
+      scope: ['packages/api'],
+    });
+
+    const db = new Database(result.state_db_path, { readonly: true });
+    try {
+      const baseline = db.prepare('SELECT scope_json FROM baselines').get();
+      assert.deepEqual(JSON.parse(baseline.scope_json), ['packages/api']);
+      assert.deepEqual(result.baseline.scope, ['packages/api']);
+    } finally { db.close(); }
+  } finally { cleanup(target); }
+});
+
 test('maintenance CLI forwards an explicit initialization mode', () => {
   const target = mkTempDir();
   try {
@@ -110,6 +191,25 @@ test('initProject keeps project metadata in authoritative baseline state and tas
   } finally { cleanup(target); }
 });
 
+test('initProject records the declared project_initialized lifecycle event', () => {
+  const rootDir = mkTempDir();
+  try {
+    const result = initProject({ target_dir: rootDir, project_name: 'events-fixture' });
+    const db = new Database(result.state_db_path, { readonly: true });
+    try {
+      const events = db.prepare('SELECT type, payload_json FROM events ORDER BY id').all();
+      assert.deepEqual(events.map((row) => row.type), ['baseline_started', 'project_initialized']);
+      assert.deepEqual(JSON.parse(events[1].payload_json), {
+        project_name: 'events-fixture', mode: 'greenfield', baseline_id: 'project-baseline',
+      });
+    } finally {
+      db.close();
+    }
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
 test('initProject refuses when .ultra/ already exists and overwrite=false', () => {
   const target = mkTempDir();
   try {
@@ -121,6 +221,67 @@ test('initProject refuses when .ultra/ already exists and overwrite=false', () =
   } finally { cleanup(target); }
 });
 
+test('initProject resume preserves existing artifacts and installs only missing current scaffold files', () => {
+  const target = mkTempDir();
+  try {
+    fs.mkdirSync(path.join(target, '.ultra', 'specs'), { recursive: true });
+    fs.writeFileSync(path.join(target, '.ultra', 'specs', 'product.md'), '# Existing product contract\n');
+
+    const result = initProject({
+      target_dir: target, project_name: 'existing-project', mode: 'brownfield', resume: true,
+    });
+    assert.equal(result.status, 'resumed');
+    assert.equal(
+      fs.readFileSync(path.join(target, '.ultra', 'specs', 'product.md'), 'utf8'),
+      '# Existing product contract\n',
+    );
+    assert.ok(fs.existsSync(path.join(target, '.ultra', 'specs', 'architecture.md')));
+    assert.ok(result.copied_files.includes('specs/architecture.md'));
+    assert.equal(result.copied_files.includes('specs/product.md'), false);
+
+    const second = initProject({
+      target_dir: target, project_name: 'existing-project', resume: true,
+    });
+    assert.equal(second.status, 'resumed');
+    assert.deepEqual(second.copied_files, []);
+    const db = new Database(result.state_db_path, { readonly: true });
+    try {
+      assert.equal(db.prepare('SELECT COUNT(*) AS count FROM baselines').get().count, 1);
+    } finally { db.close(); }
+  } finally { cleanup(target); }
+});
+
+test('initProject resume refuses projection-only tasks until the supported import runs', () => {
+  const target = mkTempDir();
+  try {
+    fs.mkdirSync(path.join(target, '.ultra', 'tasks'), { recursive: true });
+    fs.writeFileSync(path.join(target, '.ultra', 'tasks', 'tasks.json'), JSON.stringify({
+      schema_version: '4.5', source: '.ultra/state.db',
+      tasks: [{ id: 'legacy', title: 'Legacy task', type: 'feature', priority: 'P1', status: 'pending' }],
+    }));
+    assert.throws(
+      () => initProject({ target_dir: target, project_name: 'legacy', resume: true }),
+      (error) => error.code === 'LEGACY_STATE_MIGRATION_REQUIRED'
+        && /--from=4\.5 --to=12\.0/.test(error.message),
+    );
+    assert.equal(fs.existsSync(path.join(target, '.ultra', 'state.db')), false);
+    assert.equal(fs.existsSync(path.join(target, '.ultra', 'specs', 'product.md')), false);
+  } finally { cleanup(target); }
+});
+
+test('initProject rejects conflicting resume and overwrite modes', () => {
+  const target = mkTempDir();
+  try {
+    fs.mkdirSync(path.join(target, '.ultra'));
+    assert.throws(
+      () => initProject({
+        target_dir: target, project_name: 'conflict', resume: true, overwrite: true,
+      }),
+      (error) => error.code === 'VALIDATION_ERROR' && /resume.*overwrite/i.test(error.message),
+    );
+  } finally { cleanup(target); }
+});
+
 test('initProject with overwrite=true backs up existing .ultra/', () => {
   const target = mkTempDir();
   try {