@polymorphism-tech/morph-spec 8.40.0 → 8.41.0

package/src/commands/tasks/dag.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { parseTasksJsonLenient } from '../../lib/tasks/tasks-json-parser.js';
+import { parseTasksJsonLenient, oversizedTasks, MAX_TASK_OUTPUTS } from '../../lib/tasks/tasks-json-parser.js';
 import { planDispatch } from '../../lib/tasks/dispatch-planner.js';
 import { renderMermaidFlowchart } from '../../lib/tasks/mermaid-renderer.js';
 import { checkUseCases } from '../../lib/specs/usecase-check.js';
@@ -16,6 +16,15 @@ export function printLifecycleWarnings(lifecycle) {
   for (const w of lifecycle.warnings) console.error(chalk.yellow(`  ${w}`));
 }
 
+function planGateApproved(featureDir) {
+  try {
+    const feature = JSON.parse(readFileSync(join(featureDir, 'feature.json'), 'utf8'));
+    return feature?.approvalGates?.plan?.approved === true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * `morph-spec dag <feature>` — analyze the tasks.json DAG and print the
  * sequential vs parallel dispatch decision, weighted by effort.
@@ -72,11 +81,17 @@ export async function dagCommand(featureName, options = {}) {
     // revocation rows the finish would fail to apply. Warnings only.
     const lifecycle = checkLifecycle({ cwd: process.cwd(), featureDir, tasksData: data });
 
+    // Task acima do teto não cabe num dispatch. Antes do Gate 2 é erro (o plano
+    // ainda fatia); depois é aviso, para não travar feature em voo.
+    const oversized = oversizedTasks(data);
+    const sizeBlocks = oversized.length > 0 && !planGateApproved(featureDir);
+    const taskSize = { max: MAX_TASK_OUTPUTS, oversized, blocking: sizeBlocks };
+
     const plan = planDispatch(data);
 
     if (options.json) {
-      console.log(JSON.stringify({ ...plan, useCases: ucCheck, artifactCriteria, lifecycle }, null, 2));
-      if (ucCheck.errors.length) process.exit(1);
+      console.log(JSON.stringify({ ...plan, useCases: ucCheck, artifactCriteria, lifecycle, taskSize }, null, 2));
+      if (ucCheck.errors.length || sizeBlocks) process.exit(1);
       return;
     }
 
@@ -88,6 +103,14 @@ export async function dagCommand(featureName, options = {}) {
       console.error(chalk.gray('\n  Corrija a referência no tasks.json ou restaure o use case.\n'));
       process.exit(1);
     }
+    if (oversized.length) {
+      const tone = sizeBlocks ? chalk.red : chalk.yellow;
+      const head = sizeBlocks ? '❌' : '⚠';
+      console.error(tone(`\n${head} Tamanho de task — ${plural(oversized.length, 'task', 'tasks')} acima de ${MAX_TASK_OUTPUTS} outputs`));
+      for (const t of oversized) console.error(tone(`  ${t.id}: ${t.outputs} outputs`));
+      console.error(chalk.gray('  Fatie por pós-condição: uma task cabe num dispatch (morph-plan, "Tamanho da task").\n'));
+      if (sizeBlocks) process.exit(1);
+    }
     if (ucCheck.warnings.length) {
       console.error(chalk.yellow(`\n⚠ Use cases — ${plural(ucCheck.warnings.length, 'aviso', 'avisos')}`));
       for (const w of ucCheck.warnings) console.error(chalk.yellow(`  ${w}`));

package/src/commands/validation/verify.js

@@ -1,9 +1,10 @@
 import chalk from 'chalk';
-import { readFileSync } from 'fs';
-import { resolve, join } from 'path';
+import { resolve } from 'path';
 import { getFeature, updateFeature } from '../../core/state/state-manager.js';
 import { runVerify, readTask, VerifyUsageError } from '../../lib/validators/verify-runner.js';
 import { resolvePrimaryRoot } from '../project/worktree.js';
+import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
+import { canonicalPath } from '../../lib/tasks/test-runner.js';
 import { getHeadSha } from '../../lib/git/default-branch.js';
 import { EVAL_RUNNER } from '../../lib/tasks/eval-node.js';
 import { buildVerifyEvent, recordVerifyEvent, findRepeatedVerify } from '../../lib/telemetry/verify-event.js';
@@ -93,25 +94,25 @@ function formatVerifyResult(result) {
   return lines.join('\n');
 }
 
+const samePath = (a, b) => canonicalPath(a).replace(/\\/g, '/') === canonicalPath(b).replace(/\\/g, '/');
+
 /**
- * Decide whether it's safe to persist a verify result to feature.json.
+ * Persist only in the tree that OWNS the feature — the same predicate
+ * `list`/`handoff`/the mutator guard read (`resolveFeatureTree`), asked from
+ * the PRIMARY ROOT so every tree gets the same answer. Any other tree (a
+ * sub-agent's `morph-task/*` tree branched from `morph/{f}`, a scratch
+ * checkout) must never write feature.json: its copy is not the one the gates
+ * read, and the write would merge-conflict with the owner's.
  *
- * Safe contexts: the primary git root, or the feature's own REGISTERED
- * worktree (`worktree.path` — where feature.json is authoritative and
- * travels with the branch). Any other worktree (e.g. a harness subagent's
- * temporary scratch worktree) must never write feature.json — that would
- * risk a merge conflict / violate the single-writer clause.
+ * The old rule read only the root's `worktree.path` pointer, which a feature
+ * created INSIDE its worktree never has: a `worktrees/homolog-v2` on
+ * `morph/chat-demo-simulacao` measured `unregistered-worktree` on 11/11 runs,
+ * and `repeatOf` (computed only when persisting) never fired. Git's worktree
+ * registry names that tree as the owner.
  *
- * Worktree registration is ROOT-OWNED data: `runWorktreeSetup` (see
- * src/commands/project/worktree.js) writes `.worktree` ONLY into the PRIMARY
- * ROOT's copy of feature.json (via saveState after chdir'ing back to root) —
- * it never touches the worktree's own branch-local copy. So this must read
- * the ROOT's feature.json to find the registration, never the cwd-local one
- * (`getFeature(featureName)` resolves relative to `process.cwd()`, which
- * inside a worktree is the branch-local copy and will never carry
- * `.worktree` — reading it here would make this branch permanently dead code
- * for the exact case it exists to handle: verify running from inside a
- * registered worktree).
+ * The root is not special: with a live worktree owning the feature, the
+ * root's copy is the birth-instant skeleton and a stamp there is drift —
+ * `owner-tree-elsewhere`, the verify side of `assertOwnerTree`.
  *
  * @param {{ cwd: string, featureName: string, noPersist: boolean }} params
  * @returns {{ persist: boolean, reason: string|null }}
@@ -120,26 +121,9 @@ function decidePersistence({ cwd, featureName, noPersist }) {
   if (noPersist) return { persist: false, reason: 'no-persist-flag' };
 
   const root = resolvePrimaryRoot(cwd);
-  const normalizedCwd = resolve(cwd).replace(/\\/g, '/');
-
-  if (normalizedCwd === root) return { persist: true, reason: null };
-
-  // cwd is (or looks like) a worktree — consult the ROOT's feature.json for
-  // the registration. Fail-open: an unreadable/missing root feature.json
-  // means we can't confirm registration, so treat as unregistered.
-  let registeredWt = null;
-  try {
-    const rootFeatureJsonPath = join(root, '.morph', 'features', featureName, 'feature.json');
-    const rootFeature = JSON.parse(readFileSync(rootFeatureJsonPath, 'utf8'));
-    registeredWt = rootFeature.worktree?.path
-      ? String(rootFeature.worktree.path).replace(/\\/g, '/')
-      : null;
-  } catch {
-    registeredWt = null;
-  }
-
-  if (registeredWt && normalizedCwd === registeredWt) return { persist: true, reason: null };
-  return { persist: false, reason: 'unregistered-worktree' };
+  const owner = resolveFeatureTree(featureName, root);
+  if (owner.tree && samePath(owner.tree, cwd)) return { persist: true, reason: null };
+  return { persist: false, reason: samePath(root, cwd) ? 'owner-tree-elsewhere' : 'unregistered-worktree' };
 }
 
 /**

package/src/lib/risk-detector.js

@@ -27,6 +27,8 @@
  *     section?, uncovered? } derivado do 1-design/mockups.md. No uiux, checklist
  *     de tela incompleto pausa; no ship, item decidido sem a conferência do
  *     avaliador pausa. Mockup legado é isento nos dois, com a razão listada
+ *   - oversizedTasks + gate: array    — tasks acima de MAX_TASK_OUTPUTS outputs;
+ *     pausa SÓ no plano (gate 'plan'): a task tem de caber num dispatch
  *   - evalScore: number               — morph-eval score (pause if < 9)
  *   - taskCount: number               — total tasks (pause if > 20)
  */
@@ -425,6 +427,14 @@ export function shouldPauseGate(config, signals) {
     };
   }
 
+  if (signals.gate === 'plan' && Array.isArray(signals.oversizedTasks) && signals.oversizedTasks.length > 0) {
+    const list = signals.oversizedTasks.map((t) => `${t.id} (${t.outputs})`).join(', ');
+    return {
+      pause: true,
+      reason: `task grande demais para um dispatch: ${list} outputs — fatie por pós-condição`,
+    };
+  }
+
   if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
     return {
       pause: true,
@@ -498,6 +508,9 @@ export function getRiskSignals(signals) {
       out.push(`prompt/modelo tocado (${touched.length}) com eval ${signals.evalsStatus ?? 'não declarado'}`);
     }
   }
+  if (signals.gate === 'plan' && Array.isArray(signals.oversizedTasks) && signals.oversizedTasks.length > 0) {
+    out.push(`tasks grandes demais: ${signals.oversizedTasks.map((t) => t.id).join(', ')}`);
+  }
   if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
     out.push(`eval score ${signals.evalScore}/10`);
   }

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

@@ -193,6 +193,27 @@ export function parseTasksJsonSync(filePath) {
   return data;
 }
 
+/**
+ * Teto de `outputs` por task: a task inteira tem de caber num dispatch. Medido
+ * em campo (chat-demo-simulacao): tasks de 12 a 30 outputs levaram 6 de 10
+ * sub-agents ao teto de turnos, e cada retomada custou um contexto frio.
+ */
+export const MAX_TASK_OUTPUTS = 8;
+
+/**
+ * A régua única de "task grande demais", lida pelo `dag` e pelo `gate-check`.
+ * Fora de `validateTasksJson` de propósito: `outputs` segue mutável depois do
+ * Gate 2, e o teto num write de status travaria feature em voo.
+ *
+ * @returns {{ id: string, outputs: number }[]}
+ */
+export function oversizedTasks(data) {
+  const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
+  return tasks
+    .filter(t => Array.isArray(t?.outputs) && t.outputs.length > MAX_TASK_OUTPUTS)
+    .map(t => ({ id: t.id, outputs: t.outputs.length }));
+}
+
 /**
  * @returns {object[]} tasks with status === 'pending'
  */

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

@@ -191,16 +191,22 @@ export function portLayout(block, { stack = '', feature = '' } = {}) {
  * feature, and exactly the `portLayout()` pairs — nothing else, so the file
  * cannot drift from what compose receives.
  *
- * @param {string} feature
+ * `morphFeature` is for a task tree born from `morph/<f>`: `MORPH_FEATURE`
+ * names the feature it works for, while the block and `COMPOSE_PROJECT_NAME`
+ * stay keyed by `feature` (`task/<n>`) — keying them by `<f>` would hand the
+ * sub-agent the feature's own ports and compose project.
+ *
+ * @param {string} feature - the env-registry key: `<feature>` or `task/<name>`
  * @param {{ base: number, range: [number, number] }} block
  * @param {string} [stack] - config.json `project.stack` (e.g. "nextjs+dotnet")
+ * @param {{ morphFeature?: string|null }} [opts]
  * @returns {string}
  */
-export function buildEnvFileContent(feature, block, stack = '') {
+export function buildEnvFileContent(feature, block, stack = '', { morphFeature = null } = {}) {
   const lines = [
     `# Managed by morph-spec — ambiente dedicado desta worktree (feature: ${feature}).`,
     '# Derivado, git-invisível, regenerado por `worktree setup|link`; nunca editar nem commitar.',
-    `MORPH_FEATURE=${feature}`,
+    `MORPH_FEATURE=${morphFeature || feature}`,
     ...Object.entries(portLayout(block, { stack, feature })).map(([k, v]) => `${k}=${v}`),
   ];
   return `${lines.join('\n')}\n`;

package/src/utils/agents-installer.js

@@ -102,6 +102,35 @@ export function resolveMaxTurns(agent) {
   return agent.maxTurns ?? DEFAULT_MAX_TURNS;
 }
 
+/** Values Claude Code accepts in a subagent's `effort` frontmatter. */
+export const VALID_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+/**
+ * The ONE rule for a valid `effort` — same four readers as `maxTurnsProblem`.
+ * Absent means the frontmatter carries no `effort:` line and the sub-agent
+ * inherits the session's effort, byte-for-byte what the generator emitted
+ * before the field existed.
+ *
+ * @param {unknown} value - the raw agents.json value
+ * @returns {string|null} what was expected, or null when valid
+ */
+export function effortProblem(value) {
+  if (value === undefined) return null;
+  return VALID_EFFORTS.includes(value) ? null : `esperado um de ${VALID_EFFORTS.join('|')}`;
+}
+
+/**
+ * @param {string} id - persona id (agents.json key)
+ * @param {unknown} value - the raw agents.json value
+ * @returns {string|null} null when valid
+ */
+export function effortError(id, value) {
+  const problem = effortProblem(value);
+  if (!problem) return null;
+  return `agents.json: persona "${id}" tem effort inválido (${JSON.stringify(value)}) — ${problem}. ` +
+    'Remova o campo para herdar o effort da sessão.';
+}
+
 /** A surface id is the key the mockup checklist names (`Superfície: admin-app`). */
 const SURFACE_ID_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
@@ -192,7 +221,9 @@ export function personaStandardIds(persona) {
 
 /** The first validity error of a persona entry, or null — what drift reports as `invalid`. */
 function personaError(agent) {
-  return maxTurnsError(agent.id, agent.maxTurns) ?? surfacesError(agent.id, agent.surfaces, agent.standards);
+  return maxTurnsError(agent.id, agent.maxTurns)
+    ?? surfacesError(agent.id, agent.surfaces, agent.standards)
+    ?? effortError(agent.id, agent.effort);
 }
 
 /**
@@ -376,6 +407,8 @@ export function renderAgentMd(agent, knownMcpIds = null) {
   const maxTurns = resolveMaxTurns(agent);
   const surfaces = surfacesError(agent.id, agent.surfaces, agent.standards);
   if (surfaces) throw new Error(surfaces);
+  const effort = effortError(agent.id, agent.effort);
+  if (effort) throw new Error(effort);
   const frontmatter = buildFrontmatter(agent, description, knownMcpIds, maxTurns);
   const body = buildBody(agent, maxTurns);
   return `---\n${frontmatter}---\n\n${MANAGED_HEADER}\n\n${body}\n`;
@@ -409,6 +442,7 @@ function buildFrontmatter(agent, description, knownMcpIds, maxTurns) {
     // exactly what the hardcoded `maxTurns: 20` rendered.
     `maxTurns: ${maxTurns}`,
   ];
+  if (agent.effort) lines.push(`effort: ${agent.effort}`);
   if (agent.color) lines.push(`color: ${agent.color}`);
   lines.push(`memory: project`, '');
   return lines.join('\n');
@@ -475,6 +509,22 @@ function buildBody(agent, maxTurns) {
       '`PARCIAL` on line 1, done, remaining, files, no score (final report only) — then continue or stop, your call; the final report replaces it.',
   );
 
+  // The dispatch template is paraphrased by the orchestrator in the field; this
+  // body is the only text every implementer dispatch is guaranteed to carry.
+  // Gated on `effort` so a persona without it renders byte-for-byte as before.
+  if (agent.effort && isImplementer(agent)) {
+    lines.push(
+      '',
+      '## Working fast',
+      '',
+      'Independent tool calls go in the SAME response: read every listed file at once, fire the Greps together. ' +
+        'Use Read/Grep/Glob, never grep/sed/cat/find via Bash. Check a library API in the `context7` MCP before guessing ' +
+        '(load a deferred `mcp__` tool with ToolSearch). Write the tests the budget asks for, then run only your own ' +
+        'filter ONCE before the report — no red→green cycles, no `morph-spec verify` (the orchestrator proves it). ' +
+        'Never alter, revert or move production code to watch a test fail: mutation proof belongs to the Gate 3 evaluator.',
+    );
+  }
+
   return lines.join('\n');
 }