@polymorphism-tech/morph-spec 8.40.0 → 8.42.0

package/src/commands/project/worktree.js

@@ -35,7 +35,7 @@
  */
 
 import { execSync, execFileSync } from 'child_process';
-import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, lstatSync, unlinkSync, rmdirSync, cpSync } from 'fs';
+import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, lstatSync, unlinkSync, rmdirSync, cpSync, copyFileSync, readdirSync } from 'fs';
 import { join, resolve, dirname, basename } from 'path';
 import chalk from 'chalk';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
@@ -612,6 +612,43 @@ export function buildTaskBranchName(name) {
   return `morph-task/${name}`;
 }
 
+const ROOT_ENV_FILE_RE = /^\.env(\..+)?$/;
+
+/**
+ * Copy the root's `.env` / `.env.*` into a new tree: a sub-agent that builds
+ * or runs the app needs the same secrets, and they are never committed. Only
+ * a REAL file (never a link — nothing in the tree may reach the root through
+ * one), only when the tree lacks it (never overwrite), and only when git
+ * IGNORES it there: an untracked-but-visible copy would dirty the tree, and
+ * `finish`/`worktree remove --if-clean` refuse a dirty tree. At teardown the
+ * copy is byte-identical to the root's, which `triageIgnoredPaths` classifies
+ * as REPLICABLE — deleted with nothing lost.
+ *
+ * @param {string} worktreePath
+ * @param {string} root
+ * @returns {string[]} names copied
+ */
+export function copyRootEnvFiles(worktreePath, root) {
+  let names;
+  try {
+    names = readdirSync(root).filter((n) => ROOT_ENV_FILE_RE.test(n));
+  } catch {
+    return [];
+  }
+  const copied = [];
+  for (const name of names) {
+    const dst = join(worktreePath, name);
+    try {
+      if (!lstatSync(join(root, name)).isFile()) continue;
+      try { lstatSync(dst); continue; } catch { /* absent — not even a dangling link */ }
+      execFileSync('git', ['check-ignore', '-q', '--', name], { cwd: worktreePath, stdio: 'pipe' });
+      copyFileSync(join(root, name), dst);
+      copied.push(name);
+    } catch { /* not ignored, unreadable or unwritable — leave it out */ }
+  }
+  return copied;
+}
+
 /**
  * Non-exiting core of `worktree provision` — the tree `claude -w`,
  * `EnterWorktree` and `Agent isolation:"worktree"` ask for when the name is
@@ -668,7 +705,11 @@ export async function runWorktreeProvision(name, options = {}) {
     execFileSync('git', ['worktree', 'add', worktreePath, branch], { cwd: root, stdio: 'pipe' });
 
     setupInfraLinks(worktreePath, root);
-    const envBlock = await allocateWorktreeEnv(worktreePath, root, `task/${name}`);
+    const envFiles = copyRootEnvFiles(worktreePath, root);
+    // A tree born from `morph/<f>` works FOR that feature: MORPH_FEATURE says
+    // so, while the port block stays the task's own (`task/<name>`).
+    const forFeature = String(options.base || '').match(/^morph\/(.+)$/)?.[1] ?? null;
+    const envBlock = await allocateWorktreeEnv(worktreePath, root, `task/${name}`, { morphFeature: forFeature });
     const materialized = await ensureLocalState(worktreePath);
     const graph = seedWorktreeGraph(worktreePath, root);
 
@@ -681,6 +722,8 @@ export async function runWorktreeProvision(name, options = {}) {
       branchedFrom,
       kind: 'task-isolation',
       name,
+      ...(forFeature ? { feature: forFeature } : {}),
+      ...(envFiles.length ? { envFiles } : {}),
       materialized: materialized.materialized,
       ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
       ...(graph.seeded ? { graph: 'seeded' } : {}),
@@ -797,12 +840,25 @@ export function envKeyForWorktree(worktreePath, root) {
  * Shared by `setup` (feature key), `provision` (task key) and `link --all`
  * (regeneration), so the manifest has exactly one writer.
  *
+ * `morphFeature` (task trees born from `morph/<f>`) only renames the
+ * `MORPH_FEATURE` line. Left undefined — the `link --all` regeneration, which
+ * derives the key from the branch and cannot see the base — the value the
+ * file already carries is kept, so a repair never forgets the feature.
+ *
  * @param {string} worktreePath
  * @param {string} root - primary root
  * @param {string} envKey - `<feature>` or `task/<name>`
+ * @param {{ morphFeature?: string|null }} [opts]
  * @returns {Promise<{ index: number, base: number, range: [number, number] }|null>}
  */
-export async function allocateWorktreeEnv(worktreePath, root, envKey) {
+export async function allocateWorktreeEnv(worktreePath, root, envKey, { morphFeature } = {}) {
+  const envPath = join(worktreePath, '.morph', 'worktree.env');
+  if (morphFeature === undefined && envKey.startsWith('task/')) {
+    try {
+      const kept = readFileSync(envPath, 'utf8').match(/^MORPH_FEATURE=(.+)$/m)?.[1]?.trim();
+      morphFeature = kept && kept !== envKey ? kept : null;
+    } catch { morphFeature = null; }
+  }
   try {
     const { allocateEnvBlock, resolveFleetConfig, buildEnvFileContent } =
       await import('../../lib/worktree/env-allocator.js');
@@ -816,7 +872,7 @@ export async function allocateWorktreeEnv(worktreePath, root, envKey) {
       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(envKey, block, stack), 'utf8');
+    writeFileSync(envPath, buildEnvFileContent(envKey, block, stack, { morphFeature }), 'utf8');
     excludeWorktreePaths(root, [join('.morph', 'worktree.env')]);
     return block;
   } catch {

package/src/commands/state/gate-check.js

@@ -9,6 +9,7 @@ import { persistGateDecision, VALID_GATES, readTrustFromConfig } from './gate-de
 import { minimatch } from 'minimatch';
 import { detectDefaultBranch, getHeadSha, getDiffStat, changedPathsAgainst } from '../../lib/git/default-branch.js';
 import { readMorphConfig } from '../../lib/tasks/test-runner.js';
+import { oversizedTasks } from '../../lib/tasks/tasks-json-parser.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 
 /**
@@ -196,6 +197,10 @@ function collectSignals(featureName, feature, cwd, gateName) {
     designSystemDivergence: false,
   };
 
+  // Fato de disco, fora de OVERRIDABLE_SIGNAL_KEYS: task que não cabe num
+  // dispatch se fatia no plano, não depois de um sub-agent bater no teto.
+  if (gateName === 'plan') signals.oversizedTasks = oversizedTasks({ tasks });
+
   // Só onde o checklist decide algo: no fecho do design e no ship. Fato de
   // disco, fora de OVERRIDABLE_SIGNAL_KEYS como `mutationProof`.
   if (gateName === 'uiux' || gateName === 'review') {

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/ai/code-audit.js

@@ -25,7 +25,7 @@
 import { readFileSync } from 'node:fs';
 import { relative } from 'node:path';
 import { collectProjectFiles } from './ai-project-scan.js';
-import { stripComments } from './comment-stripper.js';
+import { stripComments } from '../../../framework/hooks/shared/comment-stripper.js';
 
 /** Símbolos renomeados antes do 1.0 GA, e o nome vivo de cada um. */
 export const RENAMED_SYMBOLS = {

package/src/lib/ai/registry-audit.js

@@ -22,7 +22,7 @@ import { readFileSync } from 'node:fs';
 import { existsSync } from 'node:fs';
 import { isAbsolute, join, basename } from 'node:path';
 import { collectProjectFiles } from './ai-project-scan.js';
-import { jsoncToJson } from './comment-stripper.js';
+import { jsoncToJson } from '../../../framework/hooks/shared/comment-stripper.js';
 
 /** Limite de tamanho para um JSON candidato (bytes de texto) — evita ler dumps. */
 const MAX_JSON_CHARS = 512 * 1024;

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/dotnet-test-introspection.js

@@ -23,7 +23,7 @@ import { existsSync, readFileSync, readdirSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 
 import { isInside } from './test-runner.js';
-import { jsoncToJson } from '../ai/comment-stripper.js';
+import { jsoncToJson } from '../../../framework/hooks/shared/comment-stripper.js';
 
 const MTP_RUNNER = 'Microsoft.Testing.Platform';
 const FLOOR_PROPERTY = /<TestingPlatformCommandLineArguments\b[^>]*>[^<]*--minimum-expected-tests/i;

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/validators/code-budget/code-budget-validator.js

@@ -21,8 +21,9 @@ import { join } from 'path';
 
 import { addedLinesAgainst, detectDefaultBranch } from '../../git/default-branch.js';
 import { resolveBaseRef } from '../../git/branch-classifier.js';
-import { isProjectSource, isTestFile } from '../reuse/symbol-scanner.js';
-import { citesProcess, commentLines } from './comment-scanner.js';
+import { isTestFile } from '../reuse/symbol-scanner.js';
+import { isGenerated, isProjectSource } from '../../../../framework/hooks/shared/source-files.js';
+import { citesProcess, commentLines } from '../../../../framework/hooks/shared/comment-scanner.js';
 
 /** Razão teste ÷ produção acima da qual se avisa. */
 export const MAX_TEST_RATIO = 1.5;
@@ -39,9 +40,6 @@ export const MIN_CODE_LINES = 40;
 /** Quantos locais citar no aviso de comentário antes de resumir com "(+N)". */
 const MAX_CITED = 4;
 
-/** Código gerado não é escrito por ninguém, então não entra em nenhum dos lados. */
-const GENERATED = /(?:\.Designer|\.g|\.g\.i)\.cs$|ModelSnapshot\.cs$/i;
-
 const decimal = (n) => n.toFixed(1).replace('.', ',');
 
 /**
@@ -56,7 +54,7 @@ export function measureCodeBudget(files) {
   const measured = { commentLines: 0, processLines: [], testLines: 0, productionLines: 0, commentsByFile: {} };
 
   for (const { path, content, added } of files) {
-    if (!isProjectSource(path) || GENERATED.test(path)) continue;
+    if (!isProjectSource(path) || isGenerated(path)) continue;
     const addedSet = added ? new Set(added) : null;
     const isAdded = (n) => addedSet === null || addedSet.has(n);
 

package/src/lib/validators/code-budget/index.js

@@ -6,4 +6,4 @@
  */
 
 export * from './code-budget-validator.js';
-export * from './comment-scanner.js';
+export * from '../../../../framework/hooks/shared/comment-scanner.js';

package/src/lib/validators/reuse/symbol-scanner.js

@@ -18,24 +18,7 @@
  */
 
 import { isTestPath, languageOf } from '../../graph/sanitize.js';
-
-/** Extensões que este scanner sabe ler. Fora daqui, o arquivo é ignorado. */
-const SCANNABLE = /\.(cs|ts|tsx|js|jsx|mjs|cjs)$/i;
-
-/**
- * Diretórios que contêm arquivos com extensão de código mas que não são o
- * código-fonte do projeto. `.morph/` é o caso que apareceu de verdade: o
- * `archive/{feature}/1-design/contracts.cs` de uma feature arquivada entra no
- * grafo do ProspectPRO como um tipo `RoulettePriority` a mais, e acusaria a
- * entidade real de duplicar o próprio artefato de planejamento.
- */
-const NOT_SOURCE = /(^|\/)(?:\.morph|node_modules|dist|build|out|\.next|bin|obj|coverage)\//;
-
-/**
- * Declaration file do TypeScript. `auth-debug.d.ts` + `auth-debug.ts`
- * declarando o mesmo tipo é o mecanismo da linguagem, não duplicação.
- */
-const DECLARATION_FILE = /\.d\.ts$/i;
+import { isProjectSource } from '../../../../framework/hooks/shared/source-files.js';
 
 /**
  * Nomes que a convenção usa como tipo LOCAL de arquivo, não como conceito do
@@ -63,16 +46,6 @@ const WEB_DECL =
 /** Linha que é claramente comentário — não vale a pena parsear. */
 const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*|<!--)/;
 
-/**
- * @param {string} sourceFile
- * @returns {boolean} código do projeto numa extensão lida, fora de `.d.ts` e de
- *   pasta que não é fonte — teste incluído
- */
-export function isProjectSource(sourceFile) {
-  const f = String(sourceFile || '').replace(/\\/g, '/');
-  return SCANNABLE.test(f) && !DECLARATION_FILE.test(f) && !NOT_SOURCE.test(f);
-}
-
 /**
  * @param {string} sourceFile
  * @returns {boolean} arquivo de teste, pelo mesmo predicado do grafo

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');
 }
 

package/src/utils/hooks-installer.js

@@ -216,14 +216,15 @@ const MORPH_HOOKS = [
   // order as before. post-edit-typecheck declared no timeout of its own (it
   // can legitimately spend up to its internal TSC_TIMEOUT_MS=30000 running
   // `npx tsc --noEmit`), so the chain declares none rather than under-
-  // provisioning it with just the sum of the other two links' 3000ms each. ===
+  // provisioning it with just the sum of the other two links' 3000ms each.
+  // comment-guard is LAST: it blocks, and a block ends the chain. ===
   {
     event: 'PostToolUse',
     matcher: 'Write|Edit',
     hooks: [{
       type: 'command',
       command: 'node framework/hooks/claude-code/core/chain.js',
-      args: ['post-edit-typecheck', 'tasks-json-guard', 'trace-autogen']
+      args: ['post-edit-typecheck', 'tasks-json-guard', 'trace-autogen', 'comment-guard']
     }]
   },