ultra-builder-pro-cli 0.5.0

package/orchestrator/parallel-orchestrator.cjs

@@ -0,0 +1,195 @@
+'use strict';
+
+// Phase 8B.2 — Parallel orchestrator.
+//
+// Consumes an execution-plan.json (built by Phase 8A.4a plan-builder) and
+// drives per-wave session spawning. Each wave is either parallel (batch
+// Promise.all on proc exit) or serial (await per task) based on the
+// file-overlap detection already done by plan-builder.
+//
+// Responsibilities:
+//   • load plan (object or path)
+//   • for each wave: evaluate dispatch-rules per task → spawn sessions via
+//     session-runner → wait for exit → flip session status → task status
+//   • emit wave_started / wave_completed / plan_completed events
+//
+// Not responsible for:
+//   • circuit breaker (Phase 5.2 recordTaskFailure owns that path)
+//   • worktree lifecycle beyond what session-runner already does
+//   • merge back (Phase 8B.4 layers on top of closeSession)
+
+const fs = require('node:fs');
+
+const planStore = require('../mcp-server/lib/plan-store.cjs');
+const ops = require('../mcp-server/lib/state-ops.cjs');
+const runner = require('./session-runner.cjs');
+const dispatchRules = require('./dispatch-rules.cjs');
+
+function resolvePlan({ plan, planPath, repoRoot }) {
+  if (plan) return plan;
+  if (planPath) return JSON.parse(fs.readFileSync(planPath, 'utf8'));
+  const loaded = planStore.loadPlanArtifact(repoRoot);
+  if (!loaded) {
+    const err = new Error('runPlan: no plan found (pass plan or planPath, or pre-write artifact)');
+    err.code = 'PLAN_NOT_FOUND';
+    throw err;
+  }
+  return loaded;
+}
+
+function awaitExit(proc) {
+  return new Promise((resolve) => {
+    if (!proc) { resolve({ code: 0, signal: null }); return; }
+    if (proc.exitCode !== null && proc.exitCode !== undefined) {
+      resolve({ code: proc.exitCode, signal: proc.signalCode || null });
+      return;
+    }
+    proc.on('exit', (code, signal) => resolve({ code: code === null ? -1 : code, signal }));
+  });
+}
+
+function finalizeSession(db, handle, code, ctx = {}) {
+  const sessionStatus = code === 0 ? 'completed' : 'crashed';
+  // Task status: success → completed; failure → revert to pending so the
+  // recovery layer (Phase 5.1) / circuit breaker can take over next tick.
+  const taskStatus = code === 0 ? 'completed' : 'pending';
+  try { ops.patchTask(db, handle.task_id, { status: taskStatus }); }
+  catch (err) {
+    process.stderr.write(`parallel-orchestrator: patchTask(${handle.task_id}→${taskStatus}) failed: ${err.message}\n`);
+  }
+  // closeSession flips session row status, removes worktree, and (opt-in)
+  // runs auto-merge. For crashed sessions we skip auto-merge — there's
+  // nothing to merge back from a broken run.
+  let merge;
+  try {
+    const closeResult = runner.closeSession(
+      { db, repoRoot: ctx.repoRoot, sid: handle.sid },
+      {
+        status: sessionStatus,
+        autoMerge: !!ctx.autoMerge && sessionStatus === 'completed',
+        mergeBaseBranch: ctx.mergeBaseBranch || 'main',
+      },
+    );
+    merge = closeResult.merge;
+  } catch (err) {
+    process.stderr.write(`parallel-orchestrator: closeSession(${handle.sid}) failed: ${err.message}\n`);
+  }
+  return { sid: handle.sid, task_id: handle.task_id, code, status: sessionStatus, merge };
+}
+
+async function runTask(db, repoRoot, task, wave, ctx) {
+  const { runtimes, command, commandArgs, commandArgsFor, onError } = ctx;
+  const decision = dispatchRules.evaluate({
+    task,
+    deps_ready: true,      // topo order guarantees all deps are in prior waves
+    available_runtimes: runtimes,
+    breaker_state: 'ok',   // admissionCheck below enforces the real gate
+    wave,
+  });
+  if (decision.action !== 'spawn_agent') {
+    if (onError) onError(new Error(`task ${task.id}: deferred/blocked by rule ${decision.rule_id}`));
+    return { sid: null, task_id: task.id, code: -2, status: decision.action };
+  }
+
+  const args = commandArgsFor ? commandArgsFor(task) : commandArgs;
+  let handle;
+  try {
+    handle = runner.spawnSession({
+      db, repoRoot,
+      task_id: task.id,
+      runtime: decision.runtime,
+      command, args,
+    });
+    handle.task_id = task.id;
+  } catch (err) {
+    if (onError) onError(err);
+    return { sid: null, task_id: task.id, code: -3, status: 'spawn_failed' };
+  }
+
+  // Required transition: pending → in_progress before the child's exit may
+  // flip it to completed. STATUS_TRANSITIONS forbids pending → completed.
+  try { ops.patchTask(db, task.id, { status: 'in_progress' }); }
+  catch (err) {
+    process.stderr.write(`parallel-orchestrator: patchTask(${task.id}→in_progress) failed: ${err.message}\n`);
+  }
+
+  const { code } = await awaitExit(handle.process);
+  return finalizeSession(db, handle, code, { ...ctx, repoRoot });
+}
+
+async function runWave(db, repoRoot, wave, ctx) {
+  ops.appendEvent(db, {
+    type: 'wave_started',
+    payload: { wave_id: wave.id, tasks: wave.tasks, parallel: wave.parallel },
+  });
+
+  const tasks = wave.tasks
+    .map((id) => ops.readTask(db, id))
+    .filter((t) => {
+      if (!t && ctx.onError) ctx.onError(new Error(`task not found in db (skipped)`));
+      return !!t;
+    });
+
+  let results;
+  if (wave.parallel && tasks.length > 1) {
+    results = await Promise.all(tasks.map((task) => runTask(db, repoRoot, task, wave, ctx)));
+  } else {
+    results = [];
+    for (const task of tasks) {
+      results.push(await runTask(db, repoRoot, task, wave, ctx));
+    }
+  }
+
+  ops.appendEvent(db, {
+    type: 'wave_completed',
+    payload: {
+      wave_id: wave.id,
+      completed: results.filter((r) => r.status === 'completed').length,
+      crashed: results.filter((r) => r.status === 'crashed').length,
+      deferred: results.filter((r) => r.status === 'defer' || r.status === 'block').length,
+    },
+  });
+  return results;
+}
+
+async function runPlan({
+  db, repoRoot, plan, planPath,
+  runtimes,
+  command = null, commandArgs = [], commandArgsFor = null,
+  autoMerge = false, mergeBaseBranch = 'main',
+  onError = null,
+}) {
+  if (!db) throw new Error('runPlan: db required');
+  if (!repoRoot) throw new Error('runPlan: repoRoot required');
+  if (!Array.isArray(runtimes) || runtimes.length === 0) {
+    throw new Error('runPlan: runtimes array required');
+  }
+  const resolved = resolvePlan({ plan, planPath, repoRoot });
+
+  const ctx = {
+    runtimes, command, commandArgs, commandArgsFor, onError,
+    autoMerge, mergeBaseBranch,
+  };
+  const allResults = [];
+  for (const wave of resolved.waves) {
+    const results = await runWave(db, repoRoot, wave, ctx);
+    allResults.push(...results);
+  }
+
+  ops.appendEvent(db, {
+    type: 'plan_completed',
+    payload: {
+      waves: resolved.waves.length,
+      completed: allResults.filter((r) => r.status === 'completed').length,
+      crashed: allResults.filter((r) => r.status === 'crashed').length,
+    },
+  });
+
+  return { waves: resolved.waves.length, results: allResults };
+}
+
+module.exports = {
+  runPlan,
+  // exposed for targeted tests
+  _internal: { runWave, runTask, resolvePlan, awaitExit, finalizeSession },
+};

package/orchestrator/planner/expand-prompt.cjs

@@ -0,0 +1,62 @@
+'use strict';
+
+// Phase 8A.3 — Prompt templates for task → subtasks expansion.
+//
+// Parent context (title, type, priority, complexity, files_modified) is
+// serialized into the user prompt so the LLM can produce children aligned
+// with the parent's shape. sub_count defaults to 3 when omitted.
+
+const DEFAULT_SUB_COUNT = 3;
+
+function buildExpandSystemPrompt({ sub_count = DEFAULT_SUB_COUNT } = {}) {
+  return `You are an engineering task decomposer. Break a single complex task into ${sub_count} smaller subtasks that together deliver the parent's scope.
+
+Output STRICT JSON matching this shape — nothing else, no markdown fences, no prose:
+
+{
+  "children": [
+    {
+      "id": "child-1",
+      "title": "Imperative short title (3-80 chars)",
+      "type": "architecture | feature | bugfix",
+      "priority": "P0 | P1 | P2 | P3",
+      "complexity": 1-10,
+      "deps": ["child-2"],
+      "files_modified": ["src/path/to/file.ts"]
+    }
+  ]
+}
+
+Rules:
+- Exactly ${sub_count} children.
+- Each id matches /^[a-zA-Z0-9_\\-]+$/ and is unique in the list.
+- "deps" references siblings in the same list; omit or use [] when none.
+- "files_modified" overlaps with the parent's files_modified where possible.
+- Each child's complexity is < parent's complexity; sum should approximate the parent.
+- Return JSON only.`;
+}
+
+function buildExpandUserPrompt(parent) {
+  const files = Array.isArray(parent.files_modified) ? parent.files_modified : [];
+  const deps = Array.isArray(parent.deps) ? parent.deps : [];
+  return [
+    'Parent task to decompose:',
+    '',
+    `- id: ${parent.id}`,
+    `- title: ${parent.title}`,
+    `- type: ${parent.type}`,
+    `- priority: ${parent.priority}`,
+    parent.complexity != null ? `- complexity: ${parent.complexity}` : null,
+    files.length ? `- files_modified: ${JSON.stringify(files)}` : null,
+    deps.length ? `- existing deps: ${JSON.stringify(deps)}` : null,
+    parent.trace_to ? `- trace_to: ${parent.trace_to}` : null,
+    '',
+    'Return the children list as JSON following the system schema.',
+  ].filter((l) => l !== null).join('\n');
+}
+
+module.exports = {
+  buildExpandSystemPrompt,
+  buildExpandUserPrompt,
+  DEFAULT_SUB_COUNT,
+};

package/orchestrator/planner/expand-prompt.test.cjs

@@ -0,0 +1,52 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  buildExpandSystemPrompt,
+  buildExpandUserPrompt,
+  DEFAULT_SUB_COUNT,
+} = require('./expand-prompt.cjs');
+
+test('buildExpandSystemPrompt: mentions sub_count explicitly', () => {
+  const s = buildExpandSystemPrompt({ sub_count: 4 });
+  assert.match(s, /Exactly 4 children/);
+  assert.match(s, /STRICT JSON/);
+});
+
+test('buildExpandSystemPrompt: falls back to DEFAULT_SUB_COUNT when omitted', () => {
+  const s = buildExpandSystemPrompt({});
+  assert.match(s, new RegExp(`Exactly ${DEFAULT_SUB_COUNT} children`));
+});
+
+test('buildExpandUserPrompt: serializes parent fields into prompt body', () => {
+  const parent = {
+    id: 'parent-1',
+    title: 'Build search feature',
+    type: 'feature',
+    priority: 'P1',
+    complexity: 8,
+    files_modified: ['src/search/index.ts', 'src/search/query.ts'],
+    deps: ['infra-1'],
+    trace_to: 'spec §3.2',
+  };
+  const body = buildExpandUserPrompt(parent);
+  assert.match(body, /parent-1/);
+  assert.match(body, /Build search feature/);
+  assert.match(body, /complexity: 8/);
+  assert.match(body, /src\/search\/index\.ts/);
+  assert.match(body, /infra-1/);
+  assert.match(body, /spec §3\.2/);
+});
+
+test('buildExpandUserPrompt: omits empty optional fields', () => {
+  const parent = {
+    id: 'p', title: 'Tiny task', type: 'feature', priority: 'P3',
+    complexity: null, files_modified: [], deps: [],
+  };
+  const body = buildExpandUserPrompt(parent);
+  assert.doesNotMatch(body, /files_modified/);
+  assert.doesNotMatch(body, /existing deps/);
+  assert.doesNotMatch(body, /complexity:/);
+});

package/orchestrator/planner/plan-builder.cjs

@@ -0,0 +1,116 @@
+'use strict';
+
+// Phase 8A.4a — Execution plan builder (Functional Core, no IO).
+//
+// buildPlan(tasks) → { waves, ownership_forecast, conflict_surface,
+// estimated_cost_usd, estimated_duration_min, cycles }.
+// Composes topo.computeWaves + pricing.computeCost with a file-overlap
+// conflict detector. Downstream 8A.4b writes this object to
+// .ultra/execution-plan.json.
+
+const { computeWaves } = require('../../mcp-server/lib/topo.cjs');
+const { computeCost } = require('../../mcp-server/lib/pricing.cjs');
+
+const DEFAULT_COMPLEXITY = 3;
+const TOKENS_PER_COMPLEXITY = Object.freeze({ input: 5000, output: 2000 });
+const DURATION_MIN_PER_COMPLEXITY = 5;
+
+function buildPlan(tasks, { runtime = 'claude', model = null } = {}) {
+  if (!Array.isArray(tasks)) {
+    throw new TypeError('buildPlan: tasks must be an array');
+  }
+
+  const graph = tasks.map((t) => ({
+    id: t.id,
+    deps: Array.isArray(t.deps) ? t.deps : [],
+  }));
+  const { waves, cycles } = computeWaves(graph);
+
+  const byId = new Map(tasks.map((t) => [t.id, t]));
+
+  const conflict_surface = [];
+  const wavePayload = waves.map((waveTasks, idx) => {
+    const pairs = listWaveConflicts(waveTasks, byId);
+    for (const p of pairs) {
+      conflict_surface.push({
+        files: p.files,
+        tasks: p.tasks,
+        recommend: 'sequentialize',
+      });
+    }
+    const hasConflict = pairs.length > 0;
+    const entry = {
+      id: idx + 1,
+      tasks: waveTasks,
+      parallel: !hasConflict && waveTasks.length > 1,
+    };
+    if (hasConflict) {
+      const sharedFiles = [...new Set(pairs.flatMap((p) => p.files))];
+      entry.reason = `shared files: ${sharedFiles.join(', ')}`;
+    }
+    return entry;
+  });
+
+  const ownership_forecast = {};
+  for (const t of tasks) {
+    ownership_forecast[t.id] = Array.isArray(t.files_modified) ? t.files_modified : [];
+  }
+
+  const estimated_cost_usd = round4(
+    tasks.reduce((sum, t) => {
+      const complexity = Number(t.complexity || DEFAULT_COMPLEXITY);
+      const ti = complexity * TOKENS_PER_COMPLEXITY.input;
+      const to = complexity * TOKENS_PER_COMPLEXITY.output;
+      return sum + (computeCost(runtime, model, ti, to) || 0);
+    }, 0),
+  );
+
+  const estimated_duration_min = wavePayload.reduce((acc, wv) => {
+    const complexities = wv.tasks.map(
+      (id) => Number(byId.get(id)?.complexity || DEFAULT_COMPLEXITY),
+    );
+    if (wv.parallel) {
+      return acc + Math.max(0, ...complexities) * DURATION_MIN_PER_COMPLEXITY;
+    }
+    return acc + complexities.reduce((a, b) => a + b, 0) * DURATION_MIN_PER_COMPLEXITY;
+  }, 0);
+
+  return {
+    waves: wavePayload,
+    ownership_forecast,
+    conflict_surface,
+    estimated_cost_usd,
+    estimated_duration_min,
+    cycles,
+  };
+}
+
+function listWaveConflicts(waveTasks, byId) {
+  const conflicts = [];
+  for (let i = 0; i < waveTasks.length; i++) {
+    for (let j = i + 1; j < waveTasks.length; j++) {
+      const a = waveTasks[i];
+      const b = waveTasks[j];
+      const aFiles = new Set(byId.get(a)?.files_modified || []);
+      const bFiles = new Set(byId.get(b)?.files_modified || []);
+      const overlap = [];
+      for (const f of aFiles) if (bFiles.has(f)) overlap.push(f);
+      if (overlap.length > 0) {
+        conflicts.push({ files: overlap, tasks: [a, b] });
+      }
+    }
+  }
+  return conflicts;
+}
+
+function round4(n) {
+  return Math.round(n * 10000) / 10000;
+}
+
+module.exports = {
+  buildPlan,
+  listWaveConflicts,
+  DEFAULT_COMPLEXITY,
+  TOKENS_PER_COMPLEXITY,
+  DURATION_MIN_PER_COMPLEXITY,
+};

package/orchestrator/planner/plan-builder.test.cjs

@@ -0,0 +1,165 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { buildPlan, listWaveConflicts } = require('./plan-builder.cjs');
+
+function mk(id, deps = [], files = [], complexity = 3) {
+  return { id, deps, files_modified: files, complexity };
+}
+
+test('buildPlan fixture 1: 5 tasks, no file overlap → 2 waves, no conflicts', () => {
+  const tasks = [
+    mk('a', [], ['src/a.ts'], 2),
+    mk('b', ['a'], ['src/b.ts'], 3),
+    mk('c', ['a'], ['src/c.ts'], 4),
+    mk('d', ['b', 'c'], ['src/d.ts'], 5),
+    mk('e', [], ['src/e.ts'], 2),
+  ];
+  const plan = buildPlan(tasks);
+  assert.equal(plan.waves.length, 3);
+  assert.equal(plan.conflict_surface.length, 0);
+  // wave 1 should contain a+e, both parallel-safe
+  assert.deepEqual(new Set(plan.waves[0].tasks), new Set(['a', 'e']));
+  assert.equal(plan.waves[0].parallel, true);
+  assert.deepEqual(plan.cycles, []);
+  assert.ok(plan.estimated_cost_usd > 0);
+  assert.ok(plan.estimated_duration_min > 0);
+});
+
+test('buildPlan fixture 2: same wave, shared file → conflict_surface + parallel=false', () => {
+  const tasks = [
+    mk('a', []),
+    mk('b', ['a'], ['src/utils.ts']),
+    mk('c', ['a'], ['src/utils.ts']),
+  ];
+  const plan = buildPlan(tasks);
+  assert.equal(plan.waves.length, 2);
+  const w2 = plan.waves[1];
+  assert.equal(w2.parallel, false);
+  assert.match(w2.reason, /shared files: src\/utils\.ts/);
+
+  assert.equal(plan.conflict_surface.length, 1);
+  const c = plan.conflict_surface[0];
+  assert.deepEqual(c.files, ['src/utils.ts']);
+  assert.deepEqual(new Set(c.tasks), new Set(['b', 'c']));
+  assert.equal(c.recommend, 'sequentialize');
+});
+
+test('buildPlan fixture 3: cross-wave same file → NOT a conflict', () => {
+  const tasks = [
+    mk('a', [], ['src/shared.ts']),
+    mk('b', ['a'], ['src/shared.ts']),
+  ];
+  const plan = buildPlan(tasks);
+  assert.equal(plan.conflict_surface.length, 0);
+  // wave 1 has only `a`, not parallel; wave 2 has only `b`, not parallel
+  for (const w of plan.waves) {
+    assert.equal(w.parallel, false);
+    assert.ok(!w.reason);
+  }
+});
+
+test('buildPlan fixture 4: empty tasks → empty plan, non-negative numbers', () => {
+  const plan = buildPlan([]);
+  assert.deepEqual(plan.waves, []);
+  assert.deepEqual(plan.conflict_surface, []);
+  assert.deepEqual(plan.ownership_forecast, {});
+  assert.equal(plan.estimated_cost_usd, 0);
+  assert.equal(plan.estimated_duration_min, 0);
+  assert.deepEqual(plan.cycles, []);
+});
+
+test('buildPlan fixture 5: cost + duration math (parallel vs serial waves)', () => {
+  // wave 1 (parallel): a complexity=2, b complexity=4 → max = 4 * 5 = 20 min
+  // wave 2 (1 task, not parallel): c complexity=6 → 6 * 5 = 30 min
+  // total duration = 50 min
+  const tasks = [
+    mk('a', [], ['src/a.ts'], 2),
+    mk('b', [], ['src/b.ts'], 4),
+    mk('c', ['a', 'b'], ['src/c.ts'], 6),
+  ];
+  const plan = buildPlan(tasks);
+  assert.equal(plan.estimated_duration_min, 50);
+  // cost: 3 tasks × sum(complexity)=12 × (5000*3e-6 + 2000*15e-6) per complexity unit
+  //     = 12 × (0.015 + 0.030) = 12 × 0.045 = 0.54 usd
+  assert.ok(Math.abs(plan.estimated_cost_usd - 0.54) < 0.001);
+});
+
+test('buildPlan: serial wave (with conflict) sums complexities instead of max', () => {
+  // both tasks in same wave share a file → wave is serial
+  // wave 1: a(complexity=3), b(complexity=3) → (3+3) * 5 = 30 min
+  const tasks = [
+    mk('a', [], ['src/utils.ts'], 3),
+    mk('b', [], ['src/utils.ts'], 3),
+  ];
+  const plan = buildPlan(tasks);
+  assert.equal(plan.waves[0].parallel, false);
+  assert.equal(plan.estimated_duration_min, 30);
+});
+
+test('buildPlan: ownership_forecast captures per-task files_modified verbatim', () => {
+  const tasks = [
+    mk('a', [], ['src/a.ts', 'src/a.util.ts']),
+    mk('b', [], ['src/b.ts']),
+  ];
+  const plan = buildPlan(tasks);
+  assert.deepEqual(plan.ownership_forecast, {
+    a: ['src/a.ts', 'src/a.util.ts'],
+    b: ['src/b.ts'],
+  });
+});
+
+test('buildPlan: cycle in task graph surfaced in plan.cycles', () => {
+  const tasks = [
+    mk('x', ['y']),
+    mk('y', ['x']),
+  ];
+  const plan = buildPlan(tasks);
+  assert.deepEqual(plan.waves, []);
+  assert.equal(plan.cycles.length, 1);
+  assert.deepEqual(new Set(plan.cycles[0]), new Set(['x', 'y']));
+});
+
+test('buildPlan: missing complexity defaults to DEFAULT_COMPLEXITY for cost calc', () => {
+  const tasks = [{ id: 'a', deps: [], files_modified: [] }];
+  const plan = buildPlan(tasks);
+  // complexity 3 → 15k in, 6k out → cost > 0
+  assert.ok(plan.estimated_cost_usd > 0);
+  assert.equal(plan.estimated_duration_min, 15); // 3 * 5 (single-task wave, not parallel)
+});
+
+test('buildPlan: non-array input → TypeError', () => {
+  assert.throws(() => buildPlan(null), TypeError);
+  assert.throws(() => buildPlan({}), TypeError);
+});
+
+test('listWaveConflicts: no overlap → empty', () => {
+  const byId = new Map([
+    ['a', { id: 'a', files_modified: ['x.ts'] }],
+    ['b', { id: 'b', files_modified: ['y.ts'] }],
+  ]);
+  assert.deepEqual(listWaveConflicts(['a', 'b'], byId), []);
+});
+
+test('listWaveConflicts: pair overlap reported once', () => {
+  const byId = new Map([
+    ['a', { id: 'a', files_modified: ['shared.ts', 'x.ts'] }],
+    ['b', { id: 'b', files_modified: ['shared.ts'] }],
+  ]);
+  const out = listWaveConflicts(['a', 'b'], byId);
+  assert.equal(out.length, 1);
+  assert.deepEqual(out[0].files, ['shared.ts']);
+  assert.deepEqual(out[0].tasks, ['a', 'b']);
+});
+
+test('listWaveConflicts: three-way overlap yields C(3,2)=3 pairs', () => {
+  const byId = new Map([
+    ['a', { id: 'a', files_modified: ['x.ts'] }],
+    ['b', { id: 'b', files_modified: ['x.ts'] }],
+    ['c', { id: 'c', files_modified: ['x.ts'] }],
+  ]);
+  const out = listWaveConflicts(['a', 'b', 'c'], byId);
+  assert.equal(out.length, 3);
+});

package/orchestrator/planner/prd-prompt.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+// Phase 8A.1 — Prompt templates for PRD → task-list parsing.
+//
+// Kept in a dedicated module so downstream evaluation (fixture regression,
+// prompt A/B testing) can diff the template against commits without touching
+// parser logic.
+
+const SYSTEM_PROMPT = `You are an engineering planner. Decompose a product requirement document (PRD) into a topologically ordered task list that a coding agent can execute sequentially or in parallel.
+
+Output STRICT JSON matching this shape — nothing else, no markdown fences, no prose:
+
+{
+  "tasks": [
+    {
+      "id": "task-1",
+      "title": "Imperative short title (3-80 chars)",
+      "type": "architecture | feature | bugfix",
+      "priority": "P0 | P1 | P2 | P3",
+      "complexity": 1-10,
+      "deps": ["task-2"],
+      "files_modified": ["src/path/to/file.ts"]
+    }
+  ]
+}
+
+Rules:
+- Every task id matches /^task-[0-9]+$/ and is unique in the list.
+- "deps" references other ids in the same list; omit or use [] when none.
+- "files_modified" is your best guess of affected paths; use [] when unsure.
+- "complexity" 1 = trivial, 10 = multi-day. Tasks at 7+ will be auto-expanded later.
+- "priority" — P0 blocks other work, P1 critical path, P2 standard, P3 nice-to-have.
+- "type" — architecture for design/scaffolding, feature for new capability, bugfix for correcting existing behaviour.
+- Return JSON only. No surrounding text, no trailing explanation.`;
+
+function buildSystemPrompt() {
+  return SYSTEM_PROMPT;
+}
+
+function buildUserPrompt(prdText) {
+  return `PRD:\n\n${prdText}\n\nReturn the task list as JSON following the system schema.`;
+}
+
+module.exports = { SYSTEM_PROMPT, buildSystemPrompt, buildUserPrompt };

package/orchestrator/planner/prd-prompt.test.cjs

@@ -0,0 +1,30 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  SYSTEM_PROMPT,
+  buildSystemPrompt,
+  buildUserPrompt,
+} = require('./prd-prompt.cjs');
+
+test('buildSystemPrompt returns the module-level template', () => {
+  assert.equal(buildSystemPrompt(), SYSTEM_PROMPT);
+  assert.match(SYSTEM_PROMPT, /engineering planner/i);
+  assert.match(SYSTEM_PROMPT, /STRICT JSON/);
+  assert.match(SYSTEM_PROMPT, /\/\^task-\[0-9\]\+\$\//);
+});
+
+test('buildUserPrompt embeds PRD text verbatim', () => {
+  const prd = 'As a user I want to search products by keyword';
+  const out = buildUserPrompt(prd);
+  assert.ok(out.includes(prd), 'user prompt must contain the PRD text');
+  assert.match(out, /JSON/);
+});
+
+test('buildUserPrompt tolerates long PRD text without truncation', () => {
+  const long = 'line\n'.repeat(500);
+  const out = buildUserPrompt(long);
+  assert.ok(out.includes(long));
+});