@polymorphism-tech/morph-spec 8.1.2 → 8.2.1

package/src/core/paths/output-schema.js

@@ -49,6 +49,11 @@ export const OUTPUT_SCHEMA = {
 
   // 4-review/
   reviewReport:   { filename: 'review-report.md',      phaseDir: '4-review',    phase: 'review',    protected: false },
+  // Durable report the dispatched morph-evaluator sub-agent writes itself
+  // (MORPH.md §6) — the orchestrator reads it and synthesizes reviewReport
+  // from it; the two never collide because one is raw sub-agent output and
+  // the other is the orchestrator's curated Gate 3 presentation.
+  evaluatorReport:{ filename: 'evaluator-report.md',   phaseDir: '4-review',    phase: 'review',    protected: false },
 };
 
 // ============================================================================
@@ -89,6 +94,29 @@ export function getFeatureDir(featureName) {
   return join('.morph', 'features', featureName).replace(/\\/g, '/');
 }
 
+/**
+ * Per-task sub-agent report — the durable "return value" channel for a
+ * dispatched implementation task (MORPH.md §6). A sub-agent's final text
+ * message may never reach the orchestrator (idle_notification with no text
+ * is an observed failure mode); the file it writes here always does. Doesn't
+ * fit OUTPUT_SCHEMA's one-fixed-filename-per-type model since the filename
+ * is parameterized by taskId, so it's a sibling helper instead of a schema
+ * entry.
+ *
+ * @param {string} featureName
+ * @param {string} taskId - e.g. "T7"
+ * @returns {string} morph-relative, forward-slash path
+ */
+export function getTaskReportPath(featureName, taskId) {
+  return join('.morph', 'features', featureName, '3-implement', 'reports', `${taskId}.md`)
+    .replace(/\\/g, '/');
+}
+
+/** Absolute filesystem variant of {@link getTaskReportPath}. */
+export function getAbsoluteTaskReportPath(projectRoot, featureName, taskId) {
+  return join(projectRoot, '.morph', 'features', featureName, '3-implement', 'reports', `${taskId}.md`);
+}
+
 /**
  * Get all output paths for a feature, ready for state.json `outputs` block.
  */

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/stack/stack-profile.js

@@ -51,24 +51,55 @@ function readStack(cwd) {
   }
 }
 
+/** Merge two or more profiles' validator lists (deduped) and boolean flags. */
+function mergeProfiles(profiles) {
+  return {
+    isDotnet: profiles.some((p) => p.isDotnet),
+    isNextjs: profiles.some((p) => p.isNextjs),
+    defaultValidators: [...new Set(profiles.flatMap((p) => p.defaultValidators))],
+    checkpointValidators: [...new Set(profiles.flatMap((p) => p.checkpointValidators))],
+    buildCommand: profiles.map((p) => p.buildCommand).find(Boolean) ?? null,
+  };
+}
+
 /**
  * Get the StackProfile for the current project.
+ *
+ * `stack` may be a compound value (e.g. "dotnet-nextjs", "dotnet+nextjs") —
+ * the framework's own convention for monorepos (see stack-filter.js's
+ * getProjectTags, which splits project.stack the same way). Each segment is
+ * resolved independently and matching profiles are merged, instead of the
+ * whole compound string failing every exact-match check and silently
+ * collapsing to the empty profile (0 default validators).
  */
 export function getStackProfile(cwd, stackOverride) {
   const root = cwd ?? process.cwd();
   const raw = stackOverride ?? readStack(root);
   const stack = raw?.toLowerCase() ?? 'unknown';
 
-  let profile;
-  if (NEXTJS_STACKS.has(stack)) {
-    profile = PROFILES.nextjs;
-  } else if (NO_VALIDATOR_STACKS.has(stack)) {
-    profile = PROFILES.empty;
-  } else if (DOTNET_STACKS.has(stack) || stack === 'unknown') {
-    profile = PROFILES.dotnet;
-  } else {
-    profile = PROFILES.empty;
+  const segments = stack.split(/[-+]/).filter(Boolean);
+
+  // Single-segment stack (the overwhelming common case): resolve exactly as
+  // before, byte-for-byte, including the 'unknown' → dotnet fallback.
+  if (segments.length <= 1) {
+    let profile;
+    if (NEXTJS_STACKS.has(stack)) {
+      profile = PROFILES.nextjs;
+    } else if (NO_VALIDATOR_STACKS.has(stack)) {
+      profile = PROFILES.empty;
+    } else if (DOTNET_STACKS.has(stack) || stack === 'unknown') {
+      profile = PROFILES.dotnet;
+    } else {
+      profile = PROFILES.empty;
+    }
+    return { stack, ...profile };
   }
 
+  // Compound stack: resolve each recognized segment and merge.
+  const matched = [];
+  if (segments.some((s) => DOTNET_STACKS.has(s))) matched.push(PROFILES.dotnet);
+  if (segments.some((s) => NEXTJS_STACKS.has(s))) matched.push(PROFILES.nextjs);
+
+  const profile = matched.length > 0 ? mergeProfiles(matched) : PROFILES.empty;
   return { stack, ...profile };
 }

package/src/lib/tasks/tasks-json-parser.js

@@ -98,6 +98,27 @@ export async function parseTasksJson(filePath) {
   return data;
 }
 
+/**
+ * Lenient variant for read-only analysis commands (e.g. `morph-spec dag`):
+ * a missing `version` field is defaulted to "1.0" instead of failing
+ * validation — legacy tasks.json predating the field is still analyzable.
+ * All other schema errors still throw exactly like `parseTasksJson`.
+ *
+ * @param {string} filePath - Absolute path to tasks.json
+ * @returns {Promise<{ data: object, versionDefaulted: boolean }>}
+ */
+export async function parseTasksJsonLenient(filePath) {
+  const data = await fs.readJson(filePath);
+  const versionDefaulted = data.version === undefined;
+  if (versionDefaulted) data.version = '1.0';
+
+  const { valid, errors } = validateTasksJson(data);
+  if (!valid) {
+    throw new Error(`Invalid tasks.json:\n  ${errors.join('\n  ')}`);
+  }
+  return { data, versionDefaulted };
+}
+
 /**
  * Synchronous variant — used by hooks.
  */

package/src/lib/tasks/test-runner.js

@@ -4,13 +4,16 @@
  * Resolution order for test command:
  *   1. .morph/config/config.json → project.testCommand
  *   2. .sln or .csproj present at project root → "dotnet test"
- *   3. package.json present AND has scripts.test → "npm test"
- *   4. null (no test suite detected)
+ *   3. Nested *Tests.csproj anywhere in the tree (monorepo without a root
+ *      .sln) → "dotnet test <proj> --nologo -v q" for each match
+ *   4. package.json present AND has scripts.test → "npm test"
+ *   5. null (no test suite detected)
  */
 
 import { execSync } from 'child_process';
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
+import { globSync } from 'glob';
 
 /**
  * Resolve the test command for a project.
@@ -46,7 +49,26 @@ export function resolveTestCommand(projectPath = '.') {
     // Unreadable project directory — fall through to next detection
   }
 
-  // 3. package.json present AND has scripts.test → npm test
+  // 3. No root-level project file — look for a nested test project
+  // (e.g. tests/MyApp.Tests/MyApp.Tests.csproj), common in monorepos that
+  // have no root .sln. Run each matched project explicitly rather than a
+  // bare `dotnet test` (which finds nothing to build at the root).
+  try {
+    const testProjects = globSync('**/*Tests.csproj', {
+      cwd: projectPath,
+      ignore: ['**/bin/**', '**/obj/**', '**/node_modules/**'],
+    });
+    if (testProjects.length > 0) {
+      return testProjects
+        .sort()
+        .map((p) => `dotnet test "${p}" --nologo -v q`)
+        .join(' && ');
+    }
+  } catch {
+    // Glob failure — fall through to next detection
+  }
+
+  // 4. package.json present AND has scripts.test → npm test
   const packageJsonPath = join(projectPath, 'package.json');
   if (existsSync(packageJsonPath)) {
     try {
@@ -59,7 +81,7 @@ export function resolveTestCommand(projectPath = '.') {
     }
   }
 
-  // 4. Nothing found
+  // 5. Nothing found
   return null;
 }
 

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

@@ -124,7 +124,10 @@ export async function runValidation(projectPath, featureName, options = {}) {
     const _profileForContracts = getStackProfile(projectPath);
     const contractsType = resolveContractsOutputType(_profileForContracts.stack);
     const contractsPath = getAbsoluteOutputPath(projectPath, featureName, contractsType);
-    if (existsSync(contractsPath) && !_profileForContracts.isNextjs) {
+    // Positive check on isDotnet (contract-compliance is a VSA/.NET concern) —
+    // NOT `!isNextjs`, which used to wrongly suppress it for a compound
+    // "dotnet-nextjs" stack that has a .NET backend but is ALSO isNextjs.
+    if (existsSync(contractsPath) && _profileForContracts.isDotnet) {
       validatorIds.push('contract-compliance');
     }
   }

package/src/lib/worktree/env-allocator.js

@@ -0,0 +1,149 @@
+/**
+ * env-allocator.js — deterministic per-worktree port-block allocation (fleet).
+ *
+ * Two parallel features that both start `next dev` (or `dotnet run`) collide on
+ * the same default port, and the failure is invisible until one server kills
+ * the other. Worktrees isolate files and branches, not runtime — this module
+ * closes that gap by giving every feature worktree its own stable block of
+ * ports.
+ *
+ * The registry lives at `<git-common-dir>/morph-spec/env-registry.json` — under
+ * `.git/` on purpose, for the same reasons as `finish-backup/`: it can never
+ * dirty the `git status` the worktree-finish gates read, it survives
+ * `git clean -fdx`, and the COMMON dir is the one location every linked
+ * worktree of the repo shares.
+ *
+ * Allocation is deterministic (first free index), idempotent per feature, and
+ * released only when `worktree finish` actually removed the worktree. Writes
+ * are tmp+rename so a crash never leaves a torn registry; a corrupt registry
+ * is treated as empty (fail-open — the cost is a re-allocation, never a crash).
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const DEFAULT_BASE_PORT = 4000;
+const DEFAULT_BLOCK_SIZE = 10;
+const MAX_PORT = 65535;
+
+/** Registry file path for a repo's common git dir. */
+export function registryPath(gitCommonDir) {
+  return join(gitCommonDir, 'morph-spec', 'env-registry.json');
+}
+
+function readRegistry(gitCommonDir) {
+  try {
+    const raw = readFileSync(registryPath(gitCommonDir), 'utf8').replace(/^/, '');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.allocations === 'object' && parsed.allocations !== null) {
+      return parsed;
+    }
+  } catch { /* fail-open: corrupt or absent registry restarts empty */ }
+  return { version: 1, allocations: {} };
+}
+
+function writeRegistry(gitCommonDir, registry) {
+  const path = registryPath(gitCommonDir);
+  mkdirSync(join(gitCommonDir, 'morph-spec'), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
+  renameSync(tmp, path);
+}
+
+/**
+ * Read fleet overrides from the project's committed config.json.
+ * Fail-open: missing/malformed config (or a Windows BOM) → defaults.
+ *
+ * @param {string} rootPath - primary root of the project
+ * @returns {{ basePort: number, blockSize: number }}
+ */
+export function resolveFleetConfig(rootPath) {
+  const defaults = { basePort: DEFAULT_BASE_PORT, blockSize: DEFAULT_BLOCK_SIZE };
+  try {
+    const raw = readFileSync(join(rootPath, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, '');
+    const cfg = JSON.parse(raw);
+    const fleet = cfg?.fleet || {};
+    return {
+      basePort: Number.isInteger(fleet.basePort) && fleet.basePort > 0 ? fleet.basePort : defaults.basePort,
+      blockSize: Number.isInteger(fleet.blockSize) && fleet.blockSize > 0 ? fleet.blockSize : defaults.blockSize,
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+/**
+ * Allocate (or return the existing) port block for a feature.
+ * First-free-index policy: released slots are reused, so long-lived repos
+ * don't creep toward the port ceiling.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string, basePort?: number, blockSize?: number }} opts
+ * @returns {{ index: number, base: number, range: [number, number], created: boolean }}
+ */
+export function allocateEnvBlock(feature, { gitCommonDir, basePort = DEFAULT_BASE_PORT, blockSize = DEFAULT_BLOCK_SIZE }) {
+  const registry = readRegistry(gitCommonDir);
+
+  const existing = registry.allocations[feature];
+  if (existing && Number.isInteger(existing.index)) {
+    const base = basePort + existing.index * blockSize;
+    return { index: existing.index, base, range: [base, base + blockSize - 1], created: false };
+  }
+
+  const used = new Set(
+    Object.values(registry.allocations)
+      .map((a) => a?.index)
+      .filter((i) => Number.isInteger(i)),
+  );
+  let index = 0;
+  while (used.has(index)) index += 1;
+
+  const base = basePort + index * blockSize;
+  if (base + blockSize - 1 > MAX_PORT) {
+    throw new Error(`env-allocator: port block ${base}-${base + blockSize - 1} exceeds ${MAX_PORT}`);
+  }
+
+  registry.allocations[feature] = { index, base, createdAt: new Date().toISOString() };
+  writeRegistry(gitCommonDir, registry);
+  return { index, base, range: [base, base + blockSize - 1], created: true };
+}
+
+/**
+ * Release a feature's block. Returns false when nothing was allocated.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string }} opts
+ * @returns {boolean}
+ */
+export function releaseEnvBlock(feature, { gitCommonDir }) {
+  const registry = readRegistry(gitCommonDir);
+  if (!registry.allocations[feature]) return false;
+  delete registry.allocations[feature];
+  writeRegistry(gitCommonDir, registry);
+  return true;
+}
+
+/**
+ * Render the `.morph/worktree.env` contents for a block, stack-aware.
+ * `PORT` covers next/vite/node dev servers; dotnet gets its own URL on base+1
+ * so a full-stack worktree runs web and api side by side inside one block.
+ *
+ * @param {string} feature
+ * @param {{ base: number, range: [number, number] }} block
+ * @param {string} [stack] - config.json `project.stack` (e.g. "nextjs+dotnet")
+ * @returns {string}
+ */
+export function buildEnvFileContent(feature, block, stack = '') {
+  const lines = [
+    `# Managed by morph-spec — fleet env desta worktree (feature: ${feature}).`,
+    '# Derivado e local: nunca commitar, nunca editar à mão (regenerado pelo worktree setup).',
+    `MORPH_FEATURE=${feature}`,
+    `MORPH_PORT_BASE=${block.base}`,
+    `MORPH_PORT_RANGE=${block.range[0]}-${block.range[1]}`,
+    `PORT=${block.base}`,
+  ];
+  if (/\bdotnet\b/i.test(String(stack))) {
+    lines.push(`ASPNETCORE_URLS=http://localhost:${block.base + 1}`);
+  }
+  return `${lines.join('\n')}\n`;
+}