ultra-builder-pro-cli 0.13.0 → 0.14.0

package/mcp-server/lib/prd-parser.test.cjs

@@ -1,171 +1,82 @@
 'use strict';
 
-// Test Double rationale: external LLM API — deterministic fixtures prove
-// parsing logic (prompt assembly, schema validation, id normalization)
-// without egress cost or key dependence. Integration coverage against a
-// real LLM lives behind an env gate and is exercised separately.
-
 const test = require('node:test');
 const assert = require('node:assert/strict');
 
 const { parsePrd, PrdParseError, TASK_LIST_SCHEMA } = require('./prd-parser.cjs');
 
-function fakeClient(jsonFn, { usage = { input_tokens: 100, output_tokens: 50 }, model = 'claude-sonnet-4-6', provider = 'anthropic' } = {}) {
-  return {
-    provider,
-    model,
-    async completeJson({ system, user }) {
-      const json = typeof jsonFn === 'function' ? await jsonFn({ system, user }) : jsonFn;
-      return { json, raw: JSON.stringify(json), usage, model, provider };
-    },
-  };
-}
-
-const HAPPY_TASKS = {
-  tasks: [
-    {
-      id: 'task-1',
-      title: 'Design auth schema',
-      type: 'architecture',
-      priority: 'P1',
-      complexity: 5,
-      deps: [],
-      files_modified: ['src/auth/schema.ts'],
-    },
-    {
-      id: 'task-2',
-      title: 'Implement login endpoint',
-      type: 'feature',
-      priority: 'P1',
-      complexity: 6,
-      deps: ['task-1'],
-      files_modified: ['src/auth/login.ts'],
-    },
-  ],
-};
-
-test('parsePrd: happy path normalizes tasks and returns usage metadata', async () => {
-  const client = fakeClient(HAPPY_TASKS);
-  const result = await parsePrd('Build login', { llmClient: client, tag: 'feat-auth' });
+const HAPPY_TASKS = [
+  {
+    id: 'task-1',
+    title: 'Design auth schema',
+    type: 'architecture',
+    priority: 'P1',
+    complexity: 5,
+    deps: [],
+    files_modified: ['src/auth/schema.ts'],
+  },
+  {
+    id: 'task-2',
+    title: 'Implement login endpoint',
+    type: 'feature',
+    priority: 'P1',
+    complexity: 6,
+    deps: ['task-1'],
+    files_modified: ['src/auth/login.ts'],
+  },
+];
+
+test('parsePrd validates and normalizes host-derived tasks without a provider client', () => {
+  const result = parsePrd(HAPPY_TASKS, { tag: 'feat-auth', changeId: 'auth-change' });
   assert.equal(result.tasks.length, 2);
-  assert.equal(result.tasks[0].id, 'task-1');
   assert.equal(result.tasks[0].tag, 'feat-auth');
+  assert.equal(result.tasks[0].change_id, 'auth-change');
   assert.deepEqual(result.tasks[1].deps, ['task-1']);
-  assert.equal(result.model, 'claude-sonnet-4-6');
-  assert.equal(result.provider, 'anthropic');
-  assert.equal(result.usage.input_tokens, 100);
-});
-
-test('parsePrd: empty text → NO_INPUT', async () => {
-  await assert.rejects(
-    parsePrd('', { llmClient: fakeClient(HAPPY_TASKS) }),
-    (err) => err instanceof PrdParseError && err.code === 'NO_INPUT',
-  );
-  await assert.rejects(
-    parsePrd('   ', { llmClient: fakeClient(HAPPY_TASKS) }),
-    (err) => err instanceof PrdParseError && err.code === 'NO_INPUT',
-  );
+  assert.equal(Object.hasOwn(result, 'model'), false);
+  assert.equal(Object.hasOwn(result, 'provider'), false);
+  assert.equal(Object.hasOwn(result, 'usage'), false);
 });
 
-test('parsePrd: missing llmClient → NO_LLM_CLIENT', async () => {
-  await assert.rejects(
-    parsePrd('Build something', {}),
-    (err) => err instanceof PrdParseError && err.code === 'NO_LLM_CLIENT',
-  );
+test('parsePrd requires at least one host-derived task', () => {
+  for (const value of [undefined, null, [], 'not-an-array']) {
+    assert.throws(
+      () => parsePrd(value),
+      (err) => err instanceof PrdParseError && err.code === 'NO_INPUT',
+    );
+  }
 });
 
-test('parsePrd: llmClient error bubbles up as PARSE_FAILED', async () => {
-  const brokenClient = {
-    provider: 'anthropic',
-    model: 'claude-sonnet-4-6',
-    async completeJson() { throw new Error('upstream LLM 500'); },
-  };
-  await assert.rejects(
-    parsePrd('Build something', { llmClient: brokenClient }),
-    (err) => err instanceof PrdParseError && err.code === 'PARSE_FAILED' && /upstream LLM 500/.test(err.message),
-  );
-});
-
-test('parsePrd: invalid JSON shape rejected — missing required "priority"', async () => {
-  const bad = {
-    tasks: [{
-      id: 'task-1', title: 'Foo', type: 'feature', // priority missing
-      complexity: 3, deps: [], files_modified: [],
-    }],
-  };
-  await assert.rejects(
-    parsePrd('Build Foo', { llmClient: fakeClient(bad) }),
+test('parsePrd rejects an invalid task shape', () => {
+  assert.throws(
+    () => parsePrd([{
+      id: 'task-1', title: 'Missing priority', type: 'feature',
+    }]),
     (err) => err instanceof PrdParseError && err.code === 'PARSE_FAILED' && /priority/.test(err.message),
   );
 });
 
-test('parsePrd: invalid enum value rejected — bad type', async () => {
-  const bad = {
-    tasks: [{
-      id: 'task-1', title: 'Foo', type: 'chore', priority: 'P1',
-    }],
-  };
-  await assert.rejects(
-    parsePrd('Build Foo', { llmClient: fakeClient(bad) }),
-    (err) => err instanceof PrdParseError && err.code === 'PARSE_FAILED',
-  );
-});
-
-test('parsePrd: duplicate task id rejected', async () => {
-  const dup = {
-    tasks: [
+test('parsePrd rejects duplicate task ids', () => {
+  assert.throws(
+    () => parsePrd([
       { id: 'task-1', title: 'First copy', type: 'feature', priority: 'P2' },
       { id: 'task-1', title: 'Second copy', type: 'feature', priority: 'P2' },
-    ],
-  };
-  await assert.rejects(
-    parsePrd('Build dupes', { llmClient: fakeClient(dup) }),
+    ]),
     (err) => err instanceof PrdParseError && err.code === 'PARSE_FAILED' && /duplicate/i.test(err.message),
   );
 });
 
-test('parsePrd: missing optional fields are normalized to defaults', async () => {
-  const minimal = {
-    tasks: [{
-      id: 'task-1', title: 'Minimal task', type: 'feature', priority: 'P3',
-    }],
-  };
-  const result = await parsePrd('anything', { llmClient: fakeClient(minimal) });
+test('parsePrd normalizes optional fields', () => {
+  const result = parsePrd([{
+    id: 'task-1', title: 'Minimal task', type: 'feature', priority: 'P3',
+  }]);
   assert.equal(result.tasks[0].complexity, null);
   assert.deepEqual(result.tasks[0].deps, []);
   assert.deepEqual(result.tasks[0].files_modified, []);
   assert.equal(result.tasks[0].tag, null);
+  assert.equal(result.tasks[0].change_id, null);
 });
 
-test('parsePrd: prompt contains PRD text passed to llmClient', async () => {
-  let captured;
-  const client = {
-    provider: 'anthropic',
-    model: 'claude-sonnet-4-6',
-    async completeJson({ system, user }) {
-      captured = { system, user };
-      return {
-        json: HAPPY_TASKS,
-        raw: '',
-        usage: {},
-        model: 'claude-sonnet-4-6',
-        provider: 'anthropic',
-      };
-    },
-  };
-  await parsePrd('Build the thing with acceptance criteria X', { llmClient: client });
-  assert.match(captured.system, /engineering planner/i);
-  assert.match(captured.user, /Build the thing with acceptance criteria X/);
-});
-
-test('parsePrd: empty tasks array rejected (schema requires minItems:1)', async () => {
-  await assert.rejects(
-    parsePrd('Build nothing', { llmClient: fakeClient({ tasks: [] }) }),
-    (err) => err instanceof PrdParseError && err.code === 'PARSE_FAILED',
-  );
-});
-
-test('TASK_LIST_SCHEMA: exported for downstream consumers', () => {
+test('TASK_LIST_SCHEMA remains available to MCP contract consumers', () => {
   assert.equal(TASK_LIST_SCHEMA.required[0], 'tasks');
   assert.equal(TASK_LIST_SCHEMA.properties.tasks.minItems, 1);
 });

package/mcp-server/lib/project-breadcrumb.cjs

@@ -0,0 +1,139 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const Database = require('better-sqlite3');
+
+const { EXPECTED_VERSION, REQUIRED_TABLES } = require('./state-db.cjs');
+const { readBreadcrumb } = require('./context-spine.cjs');
+
+function blockedBreadcrumb(code, {
+  nextAction,
+  workflow,
+} = {}) {
+  return {
+    change_id: null,
+    task_id: null,
+    role: 'plan',
+    gate: 'alignment',
+    readiness: 'blocked',
+    blockers: [code],
+    warnings: [],
+    next_action: nextAction,
+    recommended_workflow: workflow,
+    context_manifest_path: null,
+    context_manifest_hash: null,
+    git_head: null,
+    baseline: null,
+  };
+}
+
+function migrationBreadcrumb(code) {
+  return blockedBreadcrumb(code, {
+    nextAction: 'Resume project initialization to migrate and re-establish the Ultra baseline.',
+    workflow: 'ultra-init',
+  });
+}
+
+function doctorBreadcrumb(code) {
+  return blockedBreadcrumb(code, {
+    nextAction: 'Run ultra-doctor to inspect and recover the authoritative Ultra state database.',
+    workflow: 'ultra-doctor',
+  });
+}
+
+function latestSchemaVersion(db) {
+  return db.prepare(
+    'SELECT version FROM schema_version ORDER BY applied_at DESC, rowid DESC LIMIT 1',
+  ).get()?.version || null;
+}
+
+function tableNames(db) {
+  return new Set(db.prepare(
+    "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'",
+  ).all().map((row) => row.name));
+}
+
+function readProjectBreadcrumb(rootDir) {
+  const root = path.resolve(rootDir || process.cwd());
+  const ultraDir = path.join(root, '.ultra');
+  if (!fs.existsSync(ultraDir)) return null;
+  const dbPath = path.join(ultraDir, 'state.db');
+  if (!fs.existsSync(dbPath)) {
+    return blockedBreadcrumb('STATE_DB_MISSING', {
+      nextAction: 'Initialize or resume this Ultra project through ultra-init.',
+      workflow: 'ultra-init',
+    });
+  }
+
+  let db;
+  try {
+    db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    db.pragma('query_only = ON');
+    db.pragma('busy_timeout = 1000');
+    const tables = tableNames(db);
+    if (!tables.has('schema_version')) {
+      return migrationBreadcrumb('STATE_SCHEMA_MIGRATION_REQUIRED:unknown');
+    }
+    const version = latestSchemaVersion(db);
+    if (version !== EXPECTED_VERSION) {
+      return migrationBreadcrumb(`STATE_SCHEMA_MIGRATION_REQUIRED:${version || 'unknown'}`);
+    }
+    const missing = REQUIRED_TABLES.filter((name) => !tables.has(name));
+    if (missing.length > 0) {
+      return doctorBreadcrumb(`STATE_SCHEMA_INCOMPLETE:${missing.join(',')}`);
+    }
+    return readBreadcrumb(db, {}, { rootDir: root });
+  } catch (error) {
+    const code = error && typeof error.code === 'string' ? error.code : 'unknown';
+    return doctorBreadcrumb(`STATE_DB_UNREADABLE:${code}`);
+  } finally {
+    if (db) db.close();
+  }
+}
+
+function renderProjectBreadcrumb(rootDir, breadcrumb) {
+  if (!breadcrumb) return '';
+  const root = path.resolve(rootDir || process.cwd());
+  const baseline = breadcrumb.baseline || {};
+  const task = breadcrumb.task_id || 'none';
+  const taskStatus = breadcrumb.task_status || 'none';
+  const lines = breadcrumb.change_id ? [
+    '[Ultra context spine]',
+    `Project: ${root}`,
+    `Baseline: ${baseline.id || 'unknown'} (${baseline.mode || 'unknown'}/${baseline.status || 'unknown'})`,
+    `Change: ${breadcrumb.change_id} (${breadcrumb.change_status || 'active'})`,
+    `Task: ${task} (${taskStatus})`,
+    `Role: ${breadcrumb.role || 'plan'}`,
+    `Gate: ${breadcrumb.gate || 'alignment'}`,
+    `Readiness: ${breadcrumb.readiness || 'blocked'}`,
+  ] : [
+    '[Ultra baseline]',
+    `Project: ${root}`,
+    `Baseline: ${baseline.id || 'missing'} (${baseline.mode || 'unknown'}/${baseline.status || 'missing'})`,
+    `Readiness: ${breadcrumb.readiness || 'blocked'}`,
+  ];
+  if (Array.isArray(breadcrumb.blockers) && breadcrumb.blockers.length > 0) {
+    lines.push(`Blockers: ${breadcrumb.blockers.join(', ')}`);
+  }
+  if (Array.isArray(breadcrumb.warnings) && breadcrumb.warnings.length > 0) {
+    lines.push(`Warnings: ${breadcrumb.warnings.join(', ')}`);
+  }
+  lines.push(
+    `Next: ${breadcrumb.next_action || 'Inspect Ultra status.'}`,
+    `Route: ${breadcrumb.recommended_workflow || 'ultra-doctor'}`,
+  );
+  if (breadcrumb.context_manifest_path) {
+    lines.push(
+      `Context: ${breadcrumb.context_manifest_path} sha256=${breadcrumb.context_manifest_hash || 'unknown'}`,
+    );
+  }
+  lines.push('Authority: .ultra/state.db; JSON/Markdown remain projections or evidence artifacts.');
+  return lines.join('\n');
+}
+
+module.exports = {
+  readProjectBreadcrumb,
+  renderProjectBreadcrumb,
+};

package/mcp-server/lib/project-breadcrumb.test.cjs

@@ -0,0 +1,112 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const Database = require('better-sqlite3');
+
+const { initStateDb, closeStateDb } = require('./state-db.cjs');
+const { createChange } = require('./change-workflow.cjs');
+const { createTask } = require('./state-ops.cjs');
+const { compileRoleContext, readBreadcrumb } = require('./context-spine.cjs');
+const {
+  readProjectBreadcrumb,
+  renderProjectBreadcrumb,
+} = require('./project-breadcrumb.cjs');
+
+function tmpProject(prefix) {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  fs.mkdirSync(path.join(rootDir, '.ultra'), { recursive: true });
+  return rootDir;
+}
+
+test('project reader returns the exact canonical breadcrumb from state.db', () => {
+  const rootDir = tmpProject('ubp-project-breadcrumb-');
+  const state = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  try {
+    state.db.prepare(
+      `INSERT INTO baselines
+       (id, project_name, mode, status, approved_by, approval_note, converged_at)
+       VALUES ('baseline-1', 'fixture', 'greenfield', 'ready', 'test', 'fixture', ?)`,
+    ).run(new Date().toISOString());
+    const { change } = createChange(state.db, {
+      id: 'db-change', title: 'Database change', kind: 'quick',
+      intent: 'Prove every host consumes one breadcrumb.',
+      docs_impact: { status: 'none', rationale: 'test fixture' },
+    }, { rootDir });
+    const task = createTask(state.db, {
+      id: 'db-task', title: 'Use one breadcrumb', type: 'bugfix', priority: 'P0',
+      change_id: change.id,
+    });
+    compileRoleContext(state.db, {
+      input: {
+        task_id: task.id,
+        role: 'implement',
+        gate: 'implementation',
+        execution_contract: {
+          slice_kind: 'tracer_bullet',
+          public_seam: 'all host injections',
+          verification_command: 'npm test',
+        },
+        next_action: 'Run the cross-host breadcrumb regression test.',
+      },
+      change,
+      tasks: [task],
+      rootDir,
+    });
+
+    const expected = readBreadcrumb(state.db, {}, { rootDir });
+    const actual = readProjectBreadcrumb(rootDir);
+    assert.deepEqual(actual, expected);
+    const rendered = renderProjectBreadcrumb(rootDir, actual);
+    assert.match(rendered, /Change: db-change/);
+    assert.match(rendered, /Task: db-task/);
+    assert.ok(rendered.includes(actual.next_action));
+    assert.match(rendered, /Authority: \.ultra\/state\.db/);
+  } finally {
+    closeStateDb(state.db);
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
+test('project reader routes a missing authority to ultra-init', () => {
+  const rootDir = tmpProject('ubp-project-missing-db-');
+  try {
+    const breadcrumb = readProjectBreadcrumb(rootDir);
+    assert.equal(breadcrumb.readiness, 'blocked');
+    assert.deepEqual(breadcrumb.blockers, ['STATE_DB_MISSING']);
+    assert.equal(breadcrumb.recommended_workflow, 'ultra-init');
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
+test('project reader routes an old schema to ultra-init without consulting projections', () => {
+  const rootDir = tmpProject('ubp-project-old-schema-');
+  const db = new Database(path.join(rootDir, '.ultra', 'state.db'));
+  try {
+    db.exec(`
+      CREATE TABLE schema_version (
+        version TEXT PRIMARY KEY,
+        applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+      );
+      INSERT INTO schema_version(version) VALUES ('10.0');
+    `);
+  } finally {
+    db.close();
+  }
+  fs.writeFileSync(path.join(rootDir, '.ultra', 'workflow-state.json'), JSON.stringify({
+    command: 'ultra-dev', task_id: 'projection-task', status: 'active',
+  }));
+  try {
+    const breadcrumb = readProjectBreadcrumb(rootDir);
+    assert.equal(breadcrumb.readiness, 'blocked');
+    assert.ok(breadcrumb.blockers.includes('STATE_SCHEMA_MIGRATION_REQUIRED:10.0'));
+    assert.equal(breadcrumb.recommended_workflow, 'ultra-init');
+    assert.doesNotMatch(JSON.stringify(breadcrumb), /projection-task|ultra-dev/);
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});

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

@@ -1,21 +1,11 @@
 'use strict';
 
-// Phase 8A.3 — Expand a complex task into subtasks via injected llmClient.
-//
-// expandTask(db, { id, sub_count, strategy, llmClient }) reads the parent,
-// asks the LLM for children, and persists them atomically (children rows
-// with parent_id set, parent status → 'expanded'). The status transition
-// automatically emits task_expanded via state-ops' status→event map.
-// Strategy 'manual' is reserved for future CLI interactive flows.
+// Persist host-derived child tasks atomically. Model judgment stays with the
+// current host; this module validates ownership and the database contract.
 
 const Ajv = require('ajv/dist/2020');
 const ops = require('./state-ops.cjs');
 const changes = require('./change-workflow.cjs');
-const {
-  buildExpandSystemPrompt,
-  buildExpandUserPrompt,
-} = require('../../orchestrator/planner/expand-prompt.cjs');
-
 const CHILDREN_SHAPE = Object.freeze({
   type: 'object',
   required: ['children'],
@@ -52,8 +42,8 @@ class TaskExpandError extends Error {
   }
 }
 
-async function expandTask(db, {
-  id, sub_count, strategy = 'llm', llmClient, rootDir = process.cwd(),
+function expandTask(db, {
+  id, children, rootDir = process.cwd(),
 } = {}) {
   if (!id) throw new TaskExpandError('VALIDATION_ERROR', 'id required');
 
@@ -62,35 +52,16 @@ async function expandTask(db, {
   if (parent.status === 'expanded') {
     throw new TaskExpandError('ALREADY_EXPANDED', `task ${id} is already expanded`);
   }
-  if (strategy === 'manual') {
-    throw new TaskExpandError('NOT_IMPLEMENTED', 'strategy "manual" not implemented; use "llm"');
-  }
-  if (strategy !== 'llm') {
-    throw new TaskExpandError('VALIDATION_ERROR', `unknown strategy "${strategy}"`);
-  }
   changes.assertTaskCreationAllowed(db, { change_id: parent.change_id }, { rootDir });
-  if (!llmClient || typeof llmClient.completeJson !== 'function') {
-    throw new TaskExpandError('NO_LLM_CLIENT', 'llmClient.completeJson is required');
-  }
-
-  const system = buildExpandSystemPrompt({ sub_count });
-  const user = buildExpandUserPrompt(parent);
-
-  let reply;
-  try {
-    reply = await llmClient.completeJson({ system, user });
-  } catch (err) {
-    throw new TaskExpandError('LLM_CALL_FAILED', `LLM call failed: ${err.message}`, err);
-  }
-  if (!validateChildren(reply.json)) {
+  if (!validateChildren({ children })) {
     throw new TaskExpandError(
       'INVALID_OUTPUT',
-      `LLM output failed schema: ${ajv.errorsText(validateChildren.errors)}`,
+      `child task graph failed schema: ${ajv.errorsText(validateChildren.errors)}`,
     );
   }
 
   const seen = new Set();
-  const children = reply.json.children.map((c) => {
+  const normalized = children.map((c) => {
     if (seen.has(c.id)) {
       throw new TaskExpandError('INVALID_OUTPUT', `duplicate child id "${c.id}"`);
     }
@@ -111,13 +82,13 @@ async function expandTask(db, {
 
   return ops.tx(db, () => {
     changes.assertTaskCreationAllowed(db, { change_id: parent.change_id }, { rootDir });
-    for (const child of children) {
+    for (const child of normalized) {
       ops.createTask(db, child);
     }
     ops.patchTask(db, parent.id, { status: 'expanded' });
     return {
       parent_id: parent.id,
-      children,
+      children: normalized,
     };
   });
 }