@polymorphism-tech/morph-spec 8.1.1 → 8.2.0

package/src/commands/project/worktree.js

@@ -35,7 +35,7 @@
  */
 
 import { execSync, execFileSync } from 'child_process';
-import { existsSync, mkdirSync, symlinkSync, readFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, readdirSync, cpSync } from 'fs';
+import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, readdirSync, cpSync } from 'fs';
 import { join, resolve, dirname, relative } from 'path';
 import chalk from 'chalk';
 
@@ -196,7 +196,7 @@ export function setupInfraLinks(worktreePath, mainCwd, opts = {}) {
   // already speak for it. `lstat` reports a POSIX symlink and a Windows
   // junction alike as a symbolic link, so the exclude lands identically on
   // both platforms — as does the bug it prevents (see excludeInfraLinks).
-  excludeInfraLinks(mainAbs, dirLinks.filter((rel) => {
+  excludeWorktreePaths(mainAbs, dirLinks.filter((rel) => {
     try {
       return lstatSync(join(wtAbs, rel)).isSymbolicLink();
     } catch {
@@ -205,11 +205,13 @@ export function setupInfraLinks(worktreePath, mainCwd, opts = {}) {
   }));
 }
 
-/** Marks the block `excludeInfraLinks` owns in `.git/info/exclude`. */
+/** Marks the block `excludeWorktreePaths` owns in `.git/info/exclude`. */
 const EXCLUDE_MARKER = '# morph-spec: infra links inside worktrees (managed — see setupInfraLinks)';
 
 /**
- * Teach the repo's git to ignore the infra links a worktree carries.
+ * Teach the repo's git to ignore worktree-carried paths morph itself creates —
+ * the infra links from `setupInfraLinks` and the fleet env manifest
+ * (`.morph/worktree.env`). Same mechanism, same reasons, for both.
  *
  * CRITICAL — without this, `worktree finish` is unusable on POSIX and
  * destructive at worst, because git never sees a link as a link: it sees what
@@ -247,9 +249,9 @@ const EXCLUDE_MARKER = '# morph-spec: infra links inside worktrees (managed —
  * not write costs a refused finish, never a wrong one.
  *
  * @param {string} mainCwd - Absolute path to the main project root
- * @param {string[]} rels - worktree-relative link paths to exclude
+ * @param {string[]} rels - worktree-relative paths to exclude
  */
-function excludeInfraLinks(mainCwd, rels) {
+function excludeWorktreePaths(mainCwd, rels) {
   if (!rels.length) return;
   try {
     // `--git-common-dir`, never `join(mainCwd, '.git')`: the primary root may
@@ -416,10 +418,47 @@ export async function runWorktreeSetup(feature, options = {}) {
     // Set up infrastructure junctions (node_modules, .claude, .morph/framework).
     setupInfraLinks(worktreePath, cwd);
 
+    // Fleet env: allocate this feature's deterministic port block and write the
+    // worktree-local manifest (.morph/worktree.env), excluded from git via the
+    // same common-dir mechanism as the infra links (it must be invisible to the
+    // finish clean-checks). Under `.morph/` on purpose: that prefix is already
+    // shieldable at finish (backed up, never a removal blocker). Fail-open — a
+    // worktree without ports is degraded, never broken.
+    let envBlock = null;
+    try {
+      const { allocateEnvBlock, resolveFleetConfig, buildEnvFileContent } =
+        await import('../../lib/worktree/env-allocator.js');
+      const common = execSync('git rev-parse --git-common-dir', { cwd, stdio: 'pipe' }).toString().trim();
+      if (common) {
+        const gitCommonDir = resolve(cwd, common);
+        envBlock = allocateEnvBlock(feature, { gitCommonDir, ...resolveFleetConfig(cwd) });
+        let stack = '';
+        try {
+          const cfg = JSON.parse(readFileSync(join(cwd, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, ''));
+          stack = cfg?.project?.stack || '';
+        } catch { /* fail-open — stackless env still carries PORT */ }
+        mkdirSync(join(worktreePath, '.morph'), { recursive: true });
+        writeFileSync(join(worktreePath, '.morph', 'worktree.env'), buildEnvFileContent(feature, envBlock, stack), 'utf8');
+        excludeWorktreePaths(cwd, [join('.morph', 'worktree.env')]);
+      }
+    } catch { envBlock = null; /* fail-open */ }
+
     // Materialize a local, real state.json in the worktree (self-heal from the
     // committed feature.json files) so hooks work from the very first session.
     const materialized = await materializeState(worktreePath);
 
+    // Fleet handoff: the fresh instance that opens this worktree reads
+    // handoff.md before anything else (SessionStart hook points at it). The doc
+    // is derived and git-invisible (see handoff-generator). Fail-open — and a
+    // no-op in the create --worktree flow, where the feature dir only lands in
+    // the worktree after create's copy (create regenerates it then).
+    try {
+      if (existsSync(join(worktreePath, '.morph', 'features', feature, 'feature.json'))) {
+        const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
+        writeHandoff(feature, worktreePath);
+      }
+    } catch { /* fail-open */ }
+
     // Persist in state (non-blocking — feature may not be in state yet).
     // NOTE: imports from core/ (the lib/ path was a latent bug that silently
     // no-op'd this whole block); loadState/saveState operate on the cwd's state.
@@ -442,6 +481,7 @@ export async function runWorktreeSetup(feature, options = {}) {
       branch,
       feature,
       materialized: materialized.materialized,
+      ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
       nextStep: `Abra o Claude Code em ${worktreePath} para trabalhar nesta feature`,
     };
   } catch (err) {
@@ -524,7 +564,7 @@ export function worktreeLinkCommand(options = {}) {
  * @param {string} cwd
  * @returns {Array<{ path: string, branch: string|null, head: string|null }>}
  */
-function parseWorktreeList(cwd) {
+export function parseWorktreeList(cwd) {
   let output;
   try {
     output = execSync('git worktree list --porcelain', { cwd, stdio: 'pipe' }).toString();
@@ -1084,6 +1124,15 @@ export async function worktreeFinishCommand(feature, options = {}) {
     try {
       execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' });
     } catch { /* fail-open */ }
+
+    // Fleet env: the worktree is gone, so no server can be running on its
+    // block — release it for the next feature. ONLY here: a kept/declined
+    // worktree may still be serving on those ports. Fail-open metadata cleanup.
+    try {
+      const { releaseEnvBlock } = await import('../../lib/worktree/env-allocator.js');
+      const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
+      if (common) releaseEnvBlock(feature, { gitCommonDir: resolve(root, common) });
+    } catch { /* fail-open */ }
   }
 
   // The feature is now merged into the primary root — clear the `worktree`

package/src/commands/state/advance.js

@@ -86,6 +86,14 @@ export async function advanceCommand(featureName, options = {}) {
       if (!existsSync(nextPath)) mkdirSync(nextPath, { recursive: true });
     }
 
+    // Fleet handoff: a phase transition is exactly when a session hands the
+    // feature over (to a new instance, or to itself after /compact) — refresh
+    // the derived handoff.md so the next reader starts from the new phase.
+    try {
+      const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
+      writeHandoff(featureName, process.cwd());
+    } catch { /* fail-open */ }
+
     console.log(chalk.green(`\n✅ Advanced "${featureName}" past the ${phase} phase.`));
     if (gate) console.log(chalk.gray(`   Gate "${gate}" approved (${approvedBy}).`));
     if (nextDir) console.log(chalk.gray(`   Scaffolded ${nextDir}/ — ready for the next phase's first artifact.\n`));

package/src/commands/state/create.js

@@ -155,6 +155,12 @@ export async function createCommand(featureName, options = {}) {
             // the copy (no features yet), so its `materialized:false` was stale.
             const remat = await materializeState(worktreeResult.path);
             worktreeResult.materialized = remat.materialized;
+            // Same reason the setup path generates one: the new instance's first
+            // read. Regenerated here because setup ran before the copy above.
+            try {
+              const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
+              writeHandoff(featureName, worktreeResult.path);
+            } catch { /* fail-open */ }
           } catch { /* fail-open — the feature already exists in root */ }
         }
       }

package/src/commands/state/handoff.js

@@ -0,0 +1,49 @@
+/**
+ * `morph-spec handoff <feature>` — generate the compressed session-handoff
+ * document (`.morph/features/{f}/handoff.md`).
+ *
+ * The fleet workflow hands a feature between Claude Code instances (a new
+ * worktree session, a resumed session after a phase transition). The handoff
+ * is the sanctioned way to carry context across: derived, regenerable, and
+ * pointer-based (see handoff-generator.js). This command is also called
+ * in-process by `worktree setup`, `create --worktree` and `advance` — the CLI
+ * surface exists for the LLM/user to refresh the document on demand.
+ */
+
+import chalk from 'chalk';
+import { buildHandoff, writeHandoff } from '../../lib/generators/handoff-generator.js';
+
+/**
+ * @param {string} featureName
+ * @param {{ json?: boolean }} [options]
+ */
+export function handoffCommand(featureName, options = {}) {
+  const result = buildHandoff(featureName, process.cwd());
+  if (!result) {
+    if (options.json) {
+      console.log(JSON.stringify({ error: 'feature-not-found', feature: featureName }));
+    } else {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+    }
+    process.exit(1);
+  }
+
+  const path = writeHandoff(featureName, process.cwd());
+  if (!path) {
+    if (options.json) {
+      console.log(JSON.stringify({ error: 'write-failed', feature: featureName }));
+    } else {
+      console.error(chalk.red(`\n❌ Could not write handoff.md for ${featureName}\n`));
+    }
+    process.exit(1);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ path, feature: featureName, ...result.meta }));
+    return;
+  }
+
+  console.log(chalk.green(`\n✅ Handoff gerado: ${path}`));
+  console.log(chalk.gray(`   fase ${result.meta.phase} · tasks ${result.meta.tasksDone}/${result.meta.tasksTotal} · ${result.meta.generatedAt}`));
+  console.log(chalk.gray('   A próxima sessão lê este documento antes de continuar (ponteiros, não cópias).\n'));
+}

package/src/lib/generators/handoff-generator.js

@@ -0,0 +1,267 @@
+/**
+ * handoff-generator.js — compressed session-handoff document (fleet).
+ *
+ * A fleet runs one Claude Code instance per feature worktree. What travels
+ * between sessions must be a HANDOFF, not an export: a compact document that
+ * points at the feature's own files instead of copying their contents, so a
+ * fresh instance starts focused instead of inheriting a wall of stale context.
+ *
+ * Deterministic by construction — everything here is derived from feature.json,
+ * tasks.json, decisions.md and the worktree env manifest. The document is
+ * therefore REGENERABLE (never hand-edited, never merged): `morph-spec handoff`
+ * rebuilds it, and setup/create/advance regenerate it at the moments a new
+ * session is most likely to pick the feature up.
+ *
+ * Every section is fail-open: a missing tasks.json or a corrupt decisions.md
+ * degrades that section, never the document.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { execSync } from 'child_process';
+import { derivePhaseForFeature, getPendingGates } from '../../../framework/hooks/shared/state-reader.js';
+
+const PHASE_DIRS = {
+  proposal: '0-proposal',
+  uiux: '1-design',
+  plan: '2-plan',
+  implement: '3-implement',
+  review: '4-review',
+};
+
+/** Ordered pointer candidates — only existing files make it into the doc. */
+const POINTER_CANDIDATES = [
+  ['0-proposal/proposal.md', 'proposta e critérios de aceite'],
+  ['2-plan/spec.md', 'especificação técnica'],
+  ['2-plan/mandate.md', 'contrato de implementação (leia antes de cada task)'],
+  ['2-plan/tasks.json', 'DAG de tasks (status vivo)'],
+  ['decisions.md', 'decisões registradas'],
+  ['3-implement/recap.md', 'recap da implementação'],
+  ['4-review/review-report.md', 'relatório do Gate 3'],
+];
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8').replace(/^/, ''));
+}
+
+function taskSummary(featureDir) {
+  try {
+    const tasksPath = join(featureDir, '2-plan', 'tasks.json');
+    if (!existsSync(tasksPath)) return null;
+    const data = readJson(tasksPath);
+    if (!Array.isArray(data.tasks)) return null;
+    const done = data.tasks.filter((t) => t.status === 'done').length;
+    const doneIds = new Set(data.tasks.filter((t) => t.status === 'done').map((t) => t.id));
+    const ready = data.tasks.filter(
+      (t) => t.status === 'pending' && Array.isArray(t.dependencies) && t.dependencies.every((d) => doneIds.has(d)),
+    );
+    return { done, total: data.tasks.length, ready };
+  } catch {
+    return null;
+  }
+}
+
+function decisionTitles(featureDir, limit = 5) {
+  try {
+    const path = join(featureDir, 'decisions.md');
+    if (!existsSync(path)) return [];
+    const titles = [...readFileSync(path, 'utf8').matchAll(/^##\s+(.+)$/gm)].map((m) => m[1].trim());
+    return titles.slice(-limit);
+  } catch {
+    return [];
+  }
+}
+
+function readWorktreeEnv(cwd) {
+  try {
+    const path = join(cwd, '.morph', 'worktree.env');
+    if (!existsSync(path)) return null;
+    const content = readFileSync(path, 'utf8');
+    const get = (key) => content.match(new RegExp(`^${key}=(.+)$`, 'm'))?.[1] || null;
+    const port = get('PORT');
+    return port ? { port, range: get('MORPH_PORT_RANGE') } : null;
+  } catch {
+    return null;
+  }
+}
+
+function nextAction(feature, phase, tasks, featureName) {
+  const gates = feature.approvals || feature.approvalGates || {};
+  const approved = (g) => gates[g]?.approved === true;
+
+  switch (phase) {
+    case 'proposal':
+      // An approved Gate 1 with no plan artifact yet means "plan work is open":
+      // the derived phase only flips when 2-plan/spec.md lands (derivePhase is
+      // artifact-first). Pointing back at the proposal here would be wrong.
+      return approved('proposal')
+        ? `Gate 1 aprovado — produza \`2-plan/spec.md\` + \`mandate.md\` + \`tasks.json\` (a fase avança com o primeiro artefato; Gate 2 em seguida).`
+        : `Complete \`0-proposal/proposal.md\` e aprove o Gate 1 (\`morph-spec advance ${featureName}\`). Skill: /morph-proposal ${featureName}.`;
+    case 'uiux':
+      return approved('uiux')
+        ? `Gate de uiux aprovado — produza \`2-plan/spec.md\` + \`mandate.md\` + \`tasks.json\` (Gate 2 em seguida).`
+        : `Complete \`1-design/design-system.md\` e aprove o gate de uiux (\`morph-spec advance ${featureName}\`).`;
+    case 'plan':
+      return `Produza \`2-plan/spec.md\` + \`mandate.md\` + \`tasks.json\` e aprove o Gate 2 (\`morph-spec advance ${featureName}\`).`;
+    case 'implement': {
+      const ready = tasks?.ready?.map((t) => `${t.id} "${t.title}"`).join(', ');
+      return ready
+        ? `Execute as tasks ready — ${ready} — via /morph-apply ${featureName} (verify antes do juiz, barra 9).`
+        : `Todas as tasks concluídas ou bloqueadas — rode \`morph-spec advance ${featureName}\` para escancarar a review, ou destrave dependências. Skill: /morph-apply ${featureName}.`;
+    }
+    case 'review':
+      return approved('review')
+        ? `Gate 3 aprovado — feche: \`morph-spec worktree finish ${featureName}\` e depois \`morph-spec archive ${featureName}\` na raiz.`
+        : `Produza \`4-review/review-report.md\` (avaliador independente) e aprove o Gate 3; depois \`worktree finish\` + \`archive\`.`;
+    default:
+      return `Rode \`morph-spec status ${featureName}\` para orientar o próximo passo.`;
+  }
+}
+
+/**
+ * Build the handoff document for a feature, resolved against `cwd` (primary
+ * root or worktree — wherever the feature's `.morph/features/{f}` lives).
+ *
+ * @param {string} featureName
+ * @param {string} [cwd]
+ * @returns {{ markdown: string, meta: { generatedAt: string, phase: string, tasksDone: number, tasksTotal: number } } | null}
+ */
+export function buildHandoff(featureName, cwd = process.cwd()) {
+  const featureDir = join(cwd, '.morph', 'features', featureName);
+  if (!existsSync(join(featureDir, 'feature.json'))) return null;
+
+  let feature;
+  try {
+    feature = readJson(join(featureDir, 'feature.json'));
+  } catch {
+    return null;
+  }
+
+  let phase = 'proposal';
+  let pendingGates = [];
+  try {
+    phase = derivePhaseForFeature(featureName, cwd) || 'proposal';
+    pendingGates = getPendingGates(featureName, cwd) || [];
+  } catch { /* fail-open — proposal defaults keep the doc useful */ }
+
+  const generatedAt = new Date().toISOString();
+  const tasks = taskSummary(featureDir);
+  const env = readWorktreeEnv(cwd);
+  const decisions = decisionTitles(featureDir);
+  const worktree = feature.worktree || null;
+
+  const gates = feature.approvals || feature.approvalGates || {};
+  const gateLine = Object.entries(gates)
+    .map(([name, g]) => (g?.approved ? `${name} ✔${g.approvedBy ? ` (${g.approvedBy})` : ''}` : `${name} pendente`))
+    .join(' · ') || '—';
+
+  const relFeatureDir = `.morph/features/${featureName}`;
+  const pointers = POINTER_CANDIDATES
+    .filter(([rel]) => existsSync(join(featureDir, rel)))
+    .map(([rel, why], i) => `${i + 1}. \`${relFeatureDir}/${rel}\` — ${why}`);
+
+  const lines = [
+    `# Handoff — ${featureName}`,
+    '',
+    `> Documento derivado, gerado em ${generatedAt} por \`morph-spec handoff\`.`,
+    '> Regenere com o comando — nunca edite à mão. Aponta para os arquivos da',
+    '> feature em vez de copiá-los: leia os ponteiros, não confie em resumo velho.',
+    '',
+    '## Identidade',
+    '',
+    `- Feature: **${featureName}** (${feature.workType || 'feature'}) · fase: **${phase}** · status: ${feature.status || '—'}`,
+    worktree?.path
+      ? `- Local: worktree \`${worktree.path}\` · branch \`${worktree.branch || `morph/${featureName}`}\``
+      : '- Local: raiz primária (sem worktree registrado)',
+    env
+      ? `- Ambiente: PORT ${env.port}${env.range ? ` (bloco ${env.range})` : ''} — fonte \`.morph/worktree.env\`; suba dev servers SEMPRE nessas portas`
+      : null,
+    '',
+    '## Estado',
+    '',
+    `- Gates: ${gateLine}`,
+    tasks
+      ? `- Tasks: ${tasks.done}/${tasks.total} done · ready agora: ${tasks.ready.length ? tasks.ready.map((t) => `**${t.id}** "${t.title}"`).join(', ') : 'nenhuma'}`
+      : '- Tasks: sem tasks.json ainda (fase de planejamento não concluída)',
+    pendingGates.length ? `- Gates pendentes: ${pendingGates.join(', ')}` : null,
+    '',
+    '## Leia nesta ordem (ponteiros — nada copiado)',
+    '',
+    ...(pointers.length ? pointers : ['1. (nenhum artefato ainda — feature recém-criada)']),
+    decisions.length ? '' : null,
+    decisions.length ? `Últimas decisões: ${decisions.map((d) => `"${d}"`).join(' · ')}` : null,
+    '',
+    '## Próxima ação',
+    '',
+    nextAction(feature, phase, tasks, featureName),
+    '',
+    '## Retomar',
+    '',
+    worktree?.path ? `- \`cd ${worktree.path}\` e abra o Claude Code (uma instância por worktree).` : '- Abra o Claude Code na raiz do projeto.',
+    `- Visão da frota: \`morph-spec fleet\` · status: \`morph-spec status ${featureName}\``,
+    '',
+  ].filter((l) => l !== null);
+
+  return {
+    markdown: `${lines.join('\n')}`,
+    meta: {
+      generatedAt,
+      phase,
+      tasksDone: tasks?.done ?? 0,
+      tasksTotal: tasks?.total ?? 0,
+    },
+  };
+}
+
+/** Marks the exclude block this generator owns in `.git/info/exclude`. */
+const HANDOFF_EXCLUDE_MARKER = '# morph-spec: derived handoff docs (managed — see handoff-generator)';
+const HANDOFF_EXCLUDE_PATTERN = '/.morph/**/handoff.md';
+
+/**
+ * The handoff is DERIVED from committed sources, so it is never committed
+ * itself — regenerate > synchronize, the same principle as the materialized
+ * state.json. Left visible, every `worktree setup`/`advance` would drop an
+ * untracked file into the very `git status` the finish gates read. The
+ * common-dir `.git/info/exclude` hides it in every worktree of the repo
+ * (including the primary root); `**` also covers a feature folder after
+ * `archive` moves it. Idempotent and fail-open — a handoff that shows up as
+ * untracked is noise, never data loss.
+ */
+function ensureHandoffExcluded(cwd) {
+  try {
+    const common = execSync('git rev-parse --git-common-dir', { cwd, stdio: 'pipe' }).toString().trim();
+    if (!common) return;
+    const infoDir = join(resolve(cwd, common), 'info');
+    const excludePath = join(infoDir, 'exclude');
+    const current = existsSync(excludePath) ? readFileSync(excludePath, 'utf8') : '';
+    const present = new Set(current.split(/\r?\n/).map((l) => l.trim()));
+    if (present.has(HANDOFF_EXCLUDE_PATTERN)) return;
+    mkdirSync(infoDir, { recursive: true });
+    appendFileSync(excludePath, [
+      current && !current.endsWith('\n') ? '\n' : '',
+      present.has(HANDOFF_EXCLUDE_MARKER) ? '' : `${HANDOFF_EXCLUDE_MARKER}\n`,
+      `${HANDOFF_EXCLUDE_PATTERN}\n`,
+    ].join(''));
+  } catch { /* fail-open */ }
+}
+
+/**
+ * Write `.morph/features/{f}/handoff.md`. Returns the written path, or null
+ * when the feature does not exist (nothing is created).
+ *
+ * @param {string} featureName
+ * @param {string} [cwd]
+ * @returns {string|null}
+ */
+export function writeHandoff(featureName, cwd = process.cwd()) {
+  const result = buildHandoff(featureName, cwd);
+  if (!result) return null;
+  const path = join(cwd, '.morph', 'features', featureName, 'handoff.md');
+  try {
+    ensureHandoffExcluded(cwd);
+    writeFileSync(path, result.markdown, 'utf8');
+    return path;
+  } catch {
+    return null;
+  }
+}

package/src/lib/generators/index.js

@@ -5,9 +5,7 @@
  */
 
 export * from './design-system-generator.js';
-export * from './context-generator.js';
-export * from './recap-generator.js';
+export * from './handoff-generator.js';
 export * from './metadata-extractor.js';
 export * from './architecture-scanner.js';
 export * from './scaffold-generator.js';
-export * from './mandate-generator.js';

package/src/lib/validators/verify-runner.js

@@ -18,7 +18,7 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 
-import { runBuildCheck, getBuildCommand } from '../../../framework/hooks/shared/build-check.js';
+import { runBuildCheck, getBuildSteps } from '../../../framework/hooks/shared/build-check.js';
 import { runTestSuite, resolveTestCommand } from '../tasks/test-runner.js';
 import { runValidation } from './validation-runner.js';
 import { loadRubric, aggregateScores } from './score-aggregator.js';
@@ -58,12 +58,13 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   } = options;
 
   const stack = readStack(projectPath);
+  const paths = readProjectPaths(projectPath);
 
   const nodes = {};
   const feedback = [];
 
   // 1. build
-  nodes.build = await runBuildNode({ projectPath, stack, timeout, skipBuild, _runBuildCheck });
+  nodes.build = await runBuildNode({ projectPath, stack, paths, timeout, skipBuild, _runBuildCheck });
   appendBuildFeedback(feedback, nodes.build);
 
   // 2. tests — skipped entirely (no invocation) when build already failed.
@@ -94,20 +95,20 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
 // Build node
 // ============================================================================
 
-async function runBuildNode({ projectPath, stack, timeout, skipBuild, _runBuildCheck }) {
+async function runBuildNode({ projectPath, stack, paths = {}, timeout, skipBuild, _runBuildCheck }) {
   if (skipBuild) {
     return { status: 'skip', command: null, durationMs: 0, reason: 'requested', output: '' };
   }
 
-  const hasTsConfig = existsSync(join(projectPath, 'tsconfig.json'));
-  const command = getBuildCommand(stack, hasTsConfig);
-  if (!command) {
+  const steps = getBuildSteps(stack, { cwd: projectPath, frontendPath: paths.frontendPath, backendPath: paths.backendPath });
+  if (steps.length === 0) {
     const reason = stack ? `no build command for stack "${stack}"` : 'no stack configured';
     return { status: 'skip', command: null, durationMs: 0, reason, output: '' };
   }
+  const command = steps.map((s) => s.command).join(' && ');
 
   const start = Date.now();
-  const result = await _runBuildCheck(projectPath, stack, timeout);
+  const result = await _runBuildCheck(projectPath, stack, timeout, paths);
   const durationMs = Date.now() - start;
 
   return {
@@ -311,6 +312,22 @@ function readStack(projectPath) {
   }
 }
 
+/** Read frontend/backend sub-paths for a monorepo, so the build node can run
+ *  each stack's build command from its own directory instead of assuming a
+ *  single root (see getBuildSteps() in build-check.js). Absent in single-stack
+ *  projects — every consumer treats missing paths as "use projectPath". */
+function readProjectPaths(projectPath) {
+  try {
+    const configPath = join(projectPath, '.morph', 'config', 'config.json');
+    if (!existsSync(configPath)) return {};
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    const { frontendPath, backendPath } = config?.project ?? {};
+    return { frontendPath, backendPath };
+  } catch {
+    return {};
+  }
+}
+
 function linesOf(text) {
   const trimmed = (text || '').trim();
   return trimmed ? trimmed.split('\n') : [];