@polymorphism-tech/morph-spec 8.42.0 → 8.44.0

package/framework/hooks/shared/heavy-slots.js

@@ -0,0 +1,207 @@
+import {
+  closeSync, mkdirSync, openSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync, writeSync,
+} from 'node:fs';
+import { freemem } from 'node:os';
+import { join } from 'node:path';
+import { pidAlive } from './process-alive.js';
+import {
+  GB, SLOT_FILE, describeHolder, mtimeOf, readExclusive, scanHolders,
+} from './heavy-holders.js';
+
+export { heavyDir, heavyStatus, describeHolder } from './heavy-holders.js';
+
+const MUTEX_STALE_MS = 10_000;
+const POLL_MS = 500;
+const REPORT_EVERY_MS = 30_000;
+
+export function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(1, ms));
+}
+
+function withClaimMutex(dir, fn, { now }) {
+  const path = join(dir, 'claim.lock');
+  for (let attempt = 0; attempt < 50; attempt++) {
+    try {
+      mkdirSync(path);
+      try {
+        return { value: fn() };
+      } finally {
+        try { rmdirSync(path); } catch { /* já removido */ }
+      }
+    } catch (err) {
+      if (err?.code !== 'EEXIST') return null;
+      const mtime = mtimeOf(path);
+      if (mtime !== null && now() - mtime > MUTEX_STALE_MS) {
+        try { rmdirSync(path); } catch { /* outro já recolheu */ }
+      } else {
+        sleepSync(20);
+      }
+    }
+  }
+  return null;
+}
+
+function liveHoldersPruningStale(dir, ctx) {
+  const { live, stale } = scanHolders(dir, ctx);
+  for (const holder of stale) {
+    try { unlinkSync(holder.path); } catch { /* já solto */ }
+  }
+  return live;
+}
+
+function blockedText(blocked, slots, now) {
+  const holders = blocked.holders.map((h) => describeHolder(h, now)).join('; ');
+  if (blocked.reason === 'exclusive') return `aguardando limpeza do servidor de build (${describeHolder(blocked.exclusive, now)})`;
+  if (blocked.reason === 'memory') {
+    const cause = blocked.holders.length
+      ? `slots em uso: ${holders}`
+      : 'nenhum slot em uso: a pressão vem de fora do semáforo (vmmem do WSL, IDE, outros processos)';
+    return `aguardando RAM livre: ${blocked.freeGb.toFixed(1)} GB < ${blocked.minFreeMemGb} GB mínimos — ${cause}`;
+  }
+  return `aguardando slot pesado (${blocked.holders.length}/${slots}): ${holders}`;
+}
+
+function tryClaim(dir, opts, ctx) {
+  const {
+    slots, label, feature, node, cwd, minFreeMemGb, freeMem, lease: leaseSpec,
+  } = opts;
+  const guarded = withClaimMutex(dir, () => {
+    const holders = liveHoldersPruningStale(dir, ctx);
+    const exclusive = readExclusive(dir, ctx);
+    if (exclusive) return { blocked: { reason: 'exclusive', holders, exclusive } };
+    if (holders.length >= slots) return { blocked: { reason: 'slots', holders } };
+    const freeGb = freeMem() / GB;
+    if (minFreeMemGb > 0 && freeGb < minFreeMemGb) return { blocked: { reason: 'memory', holders, freeGb, minFreeMemGb } };
+
+    for (let i = 0; i < slots + holders.length + 1; i++) {
+      const path = join(dir, `slot-${i}.lock`);
+      try {
+        const fd = openSync(path, 'wx');
+        const meta = {
+          pid: leaseSpec ? null : process.pid,
+          since: new Date(ctx.now()).toISOString(),
+          label,
+          feature,
+          node,
+          cwd,
+          ...(leaseSpec ? { leaseId: leaseSpec.id, ttlMs: leaseSpec.ttlMs } : {}),
+        };
+        writeSync(fd, JSON.stringify(meta));
+        closeSync(fd);
+        return { lease: { path, pid: meta.pid, slot: i, meta } };
+      } catch (err) {
+        if (err?.code !== 'EEXIST') return { blocked: { reason: 'slots', holders } };
+      }
+    }
+    return { blocked: { reason: 'slots', holders } };
+  }, ctx);
+  return guarded ? guarded.value : { blocked: { reason: 'contended', holders: [] } };
+}
+
+export function acquireHeavy(opts) {
+  const {
+    dir, slots, waitTimeoutMs, maxHoldMs,
+    now = Date.now, sleep = sleepSync, isAlive = pidAlive, freeMem = freemem,
+    log = (m) => process.stderr.write(`${m}\n`), env = process.env,
+  } = opts;
+  const ctx = { now, isAlive, maxHoldMs };
+  const claimOpts = { ...opts, freeMem, minFreeMemGb: opts.minFreeMemGb ?? 0 };
+
+  try { mkdirSync(dir, { recursive: true }); } catch { return { status: 'acquired', lease: null, waitedMs: 0, unavailable: true }; }
+
+  const leaseOwner = Number(env.MORPH_HEAVY_LEASE);
+  if (Number.isInteger(leaseOwner) && leaseOwner > 0 && scanHolders(dir, ctx).live.some((h) => h.pid === leaseOwner)) {
+    return { status: 'acquired', lease: null, waitedMs: 0, reentrant: true };
+  }
+
+  const start = now();
+  let lastReport = -Infinity;
+  for (;;) {
+    const attempt = tryClaim(dir, claimOpts, ctx);
+    if (attempt.lease) return { status: 'acquired', lease: attempt.lease, waitedMs: now() - start };
+
+    const waited = now() - start;
+    const { blocked } = attempt;
+    if (waited >= waitTimeoutMs) {
+      return {
+        status: 'busy', reason: blocked.reason, holders: blocked.holders, freeGb: blocked.freeGb ?? null, waitedMs: waited,
+      };
+    }
+    if (blocked.reason !== 'contended' && now() - lastReport >= REPORT_EVERY_MS) {
+      log(blockedText(blocked, slots, now()));
+      lastReport = now();
+    }
+    sleep(Math.min(POLL_MS, Math.max(1, waitTimeoutMs - waited)));
+  }
+}
+
+export function updateLease(lease, patch) {
+  if (!lease) return;
+  try {
+    const current = JSON.parse(readFileSync(lease.path, 'utf8'));
+    if (current.pid !== lease.pid) return;
+    writeFileSync(lease.path, JSON.stringify({ ...current, ...patch }));
+  } catch { /* o lease foi recolhido; nada a atualizar */ }
+}
+
+export function releaseHeavy(lease) {
+  if (!lease) return;
+  try {
+    if (JSON.parse(readFileSync(lease.path, 'utf8')).pid === lease.pid) unlinkSync(lease.path);
+  } catch { /* já solto */ }
+}
+
+export function releaseLeaseById(dir, id) {
+  let names = [];
+  try { names = readdirSync(dir).filter((n) => SLOT_FILE.test(n)); } catch { return false; }
+  for (const name of names) {
+    const path = join(dir, name);
+    try {
+      if (JSON.parse(readFileSync(path, 'utf8')).leaseId !== id) continue;
+      unlinkSync(path);
+      return true;
+    } catch { /* já solto, ou ainda sendo gravado */ }
+  }
+  return false;
+}
+
+export function describeBusy(result, config) {
+  const waited = Math.round(result.waitedMs / 1000);
+  if (result.reason === 'memory') {
+    return `sem RAM livre há ${waited}s (${result.freeGb?.toFixed(1)} GB < ${config.minFreeMemGb} GB mínimos, heavy.minFreeMemGb)`;
+  }
+  if (result.reason === 'exclusive') return `limpeza do servidor de build ainda em curso após ${waited}s`;
+  return `${result.holders.length}/${config.slots} slots pesados ocupados por ${waited}s (heavy.waitTimeoutSec)`;
+}
+
+export function runExclusive(opts, fn) {
+  const {
+    dir, label, maxHoldMs, now = Date.now, isAlive = pidAlive,
+  } = opts;
+  const ctx = { now, isAlive, maxHoldMs };
+  try { mkdirSync(dir, { recursive: true }); } catch { return { ran: false, reason: 'unavailable', holders: [] }; }
+
+  const own = Number((opts.env ?? process.env).MORPH_HEAVY_LEASE);
+  const claimed = withClaimMutex(dir, () => {
+    const holders = liveHoldersPruningStale(dir, ctx).filter((h) => h.pid !== own);
+    if (holders.length) return { ran: false, reason: 'holders', holders };
+    if (readExclusive(dir, ctx)) return { ran: false, reason: 'exclusive', holders: [] };
+    try {
+      const fd = openSync(join(dir, 'exclusive.lock'), 'wx');
+      writeSync(fd, JSON.stringify({ pid: process.pid, since: new Date(now()).toISOString(), label }));
+      closeSync(fd);
+    } catch {
+      return { ran: false, reason: 'exclusive', holders: [] };
+    }
+    return { ran: true };
+  }, ctx);
+
+  if (!claimed) return { ran: false, reason: 'contended', holders: [] };
+  if (!claimed.value.ran) return claimed.value;
+
+  try {
+    return { ran: true, result: fn() };
+  } finally {
+    try { unlinkSync(join(dir, 'exclusive.lock')); } catch { /* já solto */ }
+  }
+}

package/framework/hooks/shared/process-alive.js

@@ -0,0 +1,8 @@
+export function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'EPERM';
+  }
+}

package/framework/hooks/shared/worktree-root.js

@@ -0,0 +1,93 @@
+/**
+ * worktree-root.js — onde as worktrees do morph-spec moram, num lugar só.
+ *
+ * Padrão: `<raiz>/worktrees/<nome>` (mais o legado `.worktrees/`). Com `worktree.root` na
+ * config (ou `MORPH_WORKTREE_ROOT`), as novas nascem em `<root>/<chave-do-repo>/<nome>`, FORA da
+ * árvore aberta no editor. A chave é `basename-<hash da raiz>`: só o basename colidiria entre dois
+ * repositórios de mesmo nome que dividem o mesmo root.
+ *
+ * Um root DENTRO da raiz é recusado: toda lista que se orienta pelo nome do container
+ * (.gitignore, graphifyignore, descoberta de testes, tar do --linux, globs do editor) deixaria de
+ * enxergá-lo, em silêncio. Recusado, vale o padrão e o motivo volta em `warning`.
+ *
+ * O predicado "está no container" é a UNIÃO do layout configurado com o padrão e o legado: uma
+ * worktree que já existe continua reconhecida depois que a chave muda. Mora em `hooks/shared`
+ * porque hook não importa `src/`; o `src/` importa daqui.
+ *
+ * @module worktree-root
+ */
+
+import { createHash } from 'crypto';
+import { readFileSync } from 'fs';
+import { homedir } from 'os';
+import { basename, isAbsolute, join, relative, resolve } from 'path';
+
+// No leading dot (C1): Jest escapes it inside an absolute `rootDir` glob, so `.worktrees/` made a whole
+// frontend suite report 0 tests without an error. `.worktrees/` is the pre-C1 name, still read everywhere.
+export const WORKTREES_DIR = 'worktrees';
+export const LEGACY_WORKTREES_DIR = '.worktrees';
+export const WORKTREE_DIR_NAMES = [WORKTREES_DIR, LEGACY_WORKTREES_DIR];
+
+const fwd = (p) => String(p).replace(/\\/g, '/');
+const foldCase = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+
+/** `basename-<8 hex do hash da raiz>` — estável entre `R:` e `r:` no Windows. */
+export function repoKey(primaryRoot) {
+  const root = fwd(resolve(primaryRoot));
+  const hash = createHash('sha1').update(foldCase(root)).digest('hex').slice(0, 8);
+  return `${basename(root)}-${hash}`;
+}
+
+function configuredRoot(primaryRoot, env) {
+  if (typeof env.MORPH_WORKTREE_ROOT === 'string' && env.MORPH_WORKTREE_ROOT.trim()) return env.MORPH_WORKTREE_ROOT.trim();
+  try {
+    const raw = readFileSync(join(primaryRoot, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, '');
+    const value = JSON.parse(raw)?.worktree?.root;
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function isInside(root, path) {
+  const rel = relative(root, path);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/**
+ * @param {string} primaryRoot
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ dir: string|null, base?: string, warning?: string }} `dir` = `<root>/<repoKey>`
+ */
+export function externalContainer(primaryRoot, { env = process.env } = {}) {
+  const configured = configuredRoot(primaryRoot, env);
+  if (!configured) return { dir: null };
+  const expanded = configured === '~' || /^~[\\/]/.test(configured) ? join(homedir(), configured.slice(1)) : configured;
+  const base = resolve(primaryRoot, expanded);
+  if (isInside(resolve(primaryRoot), base)) {
+    return { dir: null, warning: `worktree.root (${configured}) fica dentro da raiz do projeto; ignorado, valem worktrees/ — as listas de exclusão se orientam por esse nome` };
+  }
+  return { dir: fwd(join(base, repoKey(primaryRoot))), base: fwd(base) };
+}
+
+/** Where a NEW worktree lands. */
+export function newWorktreesDir(primaryRoot, opts) {
+  return externalContainer(primaryRoot, opts).dir ?? `${fwd(resolve(primaryRoot))}/${WORKTREES_DIR}`;
+}
+
+/** Every directory that counts as "the container", external first. Forward slashes. */
+export function containerDirs(primaryRoot, opts) {
+  const root = fwd(resolve(primaryRoot));
+  const external = externalContainer(primaryRoot, opts).dir;
+  return [...(external ? [external] : []), ...WORKTREE_DIR_NAMES.map((name) => `${root}/${name}`)];
+}
+
+/** Is `path` under any of `dirs` (a `containerDirs` result)? Ask `containerDirs` once per audit, not once per path. */
+export function isUnder(dirs, path) {
+  const target = foldCase(fwd(resolve(path)));
+  return dirs.some((dir) => target.startsWith(`${foldCase(dir)}/`));
+}
+
+export function isInContainer(primaryRoot, path, opts) {
+  return isUnder(containerDirs(primaryRoot, opts), path);
+}

package/framework/rules/ai-agents-standards.md

@@ -50,6 +50,7 @@ stacks:
 | `ai-agents/conversational-agent-with-phases.md` | conversa com fases no turno — allow-list de tools, `ChatToolMode`, teto de tool calls |
 | `ai-agents/guardrails.md` | regra proibida vira código — guard de tool, pertinência, argumento não confiável, fail-open |
 | `ai-agents/testing-ai.md` | testar agente sem rede — `IChatClient` fake, harness de turno, golden de prompt |
+| `ai-agents/tool-adapters.md` | tool de agente que carrega regra de negócio — a regra em `*Ops` com desfecho tipado, o texto do modelo no adaptador, teste em duas camadas e migração neutra |
 | `ai-agents/evals-with-cache.md` | eval de modelo/prompt no CI **sem credencial e sem rede**: cache de respostas commitada, dataset versionado, o que entra na chave de cache, troca de modelo e regressão de prompt |
 | `ai-agents/cost-and-budget.md` | custo em dinheiro — `UsageCostMiddleware`, tarifa por token, teto de orçamento |
 | `ai-agents/llm-runtime-defaults.md` | knobs de runtime da chamada — timeout, retry, `strict` JSON schema, temperatura/reasoning |

package/framework/schemas/config.schema.json

@@ -149,6 +149,86 @@
           ]
         }
       }
+    },
+    "heavy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Slots per USER (shared by every session on the machine, kept in %LOCALAPPDATA%/morph-spec/heavy on Windows and ~/.local/state/morph-spec/heavy elsewhere) for the heavy nodes: build, tests and e2e of `verify`, `e2e up`, and `morph-spec heavy run`. A value it cannot read falls back to the default with a warning - this block never blocks work by being wrong. `MORPH_HEAVY=off` switches the whole semaphore off (the test suite does), `MORPH_HEAVY_SLOTS` overrides `slots`, `MORPH_HEAVY_DIR` moves the directory.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "false turns the semaphore off: no slot is taken, no RAM is checked, and `dotnet build-server shutdown` is never run (without the semaphore nothing proves another session is not compiling)."
+        },
+        "slots": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 2,
+          "description": "How many heavy nodes run at once on this machine."
+        },
+        "minFreeMemGb": {
+          "type": "number",
+          "minimum": 0,
+          "default": 4,
+          "description": "Free RAM (os.freemem) below which a heavy node WAITS instead of starting and dying 'killed' for memory. It waits with or without a slot holder - the pressure often comes from outside (WSL vmmem, the IDE). 0 disables the check."
+        },
+        "waitTimeoutSec": {
+          "type": "number",
+          "minimum": 0,
+          "default": 600,
+          "description": "How long to wait for a slot or for RAM. On timeout `verify` exits 3 (busy) and persists NOTHING - a queue is neither a green nor a red gate. 0 means do not wait."
+        },
+        "maxHoldMinutes": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "default": 90,
+          "description": "A slot held longer than this is treated as stale even if its pid is alive (pid reuse)."
+        },
+        "shutdownBuildServer": {
+          "type": "boolean",
+          "default": true,
+          "description": "Run `dotnet build-server shutdown` at the end of a feature-scope `verify` and of `e2e down`, only when no slot is held and no dotnet build/test is alive. Never at the end of a task-scope verify: every task would pay a cold compiler."
+        },
+        "disableNodeReuse": {
+          "type": "boolean",
+          "default": false,
+          "description": "Set MSBUILDDISABLENODEREUSE=1 while a heavy node runs, so MSBuild worker nodes do not stay resident."
+        },
+        "gateBash": {
+          "type": "boolean",
+          "default": false,
+          "description": "Opt-in. A PreToolUse hook takes a slot before a raw heavy Bash command (dotnet build|test|publish|pack, npm|pnpm|yarn test|build, vitest, jest, docker compose up|build, ...) runs and the matching Post hook gives it back. Waits up to heavy.waitTimeoutSec (capped below the hook timeout), then refuses the call with a busy message instead of running it. Foreground Bash only: a run_in_background call is not gated, and a call denied or interrupted after the hook keeps its slot until its timeout lapses, and that timeout starts before the permission prompt."
+        }
+      }
+    },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Worktree behaviour of this project. Other keys are left open; the readers are src/lib/worktree/vscode-settings.js and src/lib/worktree/agent-reaper.js.",
+      "properties": {
+        "root": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where NEW worktrees are created, outside the project tree: they land in <root>/<repo>-<hash>/<name> (the hash keeps two repos with the same folder name apart). Absolute, `~/...`, or relative to the primary root. A path that resolves INSIDE the project root is ignored with a warning, because every exclusion list (.gitignore, graph ignore, test discovery, the --linux tar, editor globs) is keyed on worktrees/. Existing worktrees under worktrees/ keep being recognised. `MORPH_WORKTREE_ROOT` overrides it for one run."
+        },
+        "editorSettings": {
+          "type": "boolean",
+          "default": true,
+          "description": "false stops `init`, `update`, `worktree setup|provision` and `doctor --worktrees --prune` from adding the worktree/node_modules (and, on .NET, bin/obj) excludes to .vscode/settings.json. `MORPH_EDITOR_SETTINGS=0` does the same for one run."
+        },
+        "reap": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "graceMinutes": {
+              "type": "number",
+              "minimum": 0,
+              "default": 30,
+              "description": "How long a sub-agent's events.jsonl must stay quiet after its AgentUsage before `worktree reap` removes the tree: a stopped agent can still be resumed by SendMessage. An invalid value falls back to 30."
+            }
+          }
+        }
+      }
     }
   }
 }

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.44.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.44.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.44.0"
 ---
 
 # morph-apply
@@ -107,6 +107,8 @@ while (true):
     // de uma task não paga a suíte inteira). `--filter {ids}` só para FORÇAR a
     // escolha de nós; `--full` desliga o recorte.
     run: morph-spec verify {feature} {task.id} --json
+    // exit 3 / status == 'busy': fila de slot pesado cheia, NÃO vermelho — nada foi verificado nem gravado.
+    // Repita a mesma chamada; não conta como tentativa e não dispara o loop de correção.
     if verify.status == 'fail':
       // vermelho: feedback determinístico direto ao loop, SEM gastar o juiz LLM.
       feedback = verify.feedback   // usado como input do próximo attempt
@@ -238,7 +240,10 @@ dispatch Agent (subagent_type: "morph-{id}") with prompt:
        por decisão sua; ao concluir, o relatório final substitui o parcial, sem o
        `PARCIAL`. Sem limite declarado, bastam os commits por marco.
     6. PROCESSOS: NUNCA `taskkill /IM node.exe` (derruba os MCPs de todas as
-       sessões). Encerre dev server pelo PID que você mesmo subiu.
+       sessões). Encerre dev server pelo PID que você mesmo subiu. Build e
+       suíte pesados (`dotnet build`, `dotnet test`, `docker compose up`) rodam
+       por `morph-spec heavy run -- <comando>`: exit 3 é fila cheia, não erro do
+       código — espere e repita.
     7. RETORNO: o relatório no arquivo canônico é o retorno. `SendMessage` não é
        substituto do relatório e não deve ser chamado.
     8. MUTAÇÃO: nunca altere, reverta, mova ou apague código de produção para ver
@@ -296,7 +301,7 @@ Quando o `morph-spec dag {feature}` reporta `isolation.recommended: "worktree"`
 1. **Dispatch:** mesmo `subagent_type: "morph-{id}"` e standards de §3b, mais `isolation: "worktree"`. O worktree vem do hook `WorktreeCreate` do morph: nasce em `worktrees/<n>` na branch `morph-task/<n>`, com junctions (`node_modules`, `.claude`, `.morph/framework`) e `.morph/worktree.env` já prontos — se faltar infra mesmo assim, o agente roda `morph-spec worktree link --all` (fail-open); se ainda impossível, reporta "verificação: não executada" (o verify pós-merge cobre). Dev server/compose dentro do worktree já sai nas portas do bloco (o hook `worktree-env-inject` prefixa o comando; fora do Claude, `eval "$(morph-spec env)"`). O worktree nasce da branch `morph/<feature>` quando a sessão está nela (o trabalho já integrado da feature vem junto, sem `merge` manual) e com os `.env*` da raiz copiados — o prompt de dispatch não manda o agente preparar nada disso. Sessão fora de `morph/<feature>` (orquestrador na raiz) faz o worktree nascer da default: aí, e só aí, o prompt abre com `git merge --ff-only morph/<feature>`. O agente commita na branch do worktree como último ato e reporta a branch. Ele não roda `morph-spec verify` (cláusula 3): a prova é o verify do orquestrador depois do merge.
 2. **Integração (orquestrador, a cada relatório que chega):** faça o merge de cada branch reportada, uma por vez, na ordem de chegada — `git merge --no-ff <branch>`. Conflito → `git merge --abort`, marque a task de volta a `pending` com nota "merge conflict — reexecutar sequencial", siga para a próxima branch. Os paths em conflito são exatamente os de `isolation.collisions` do dag.
 3. **Pós-merge:** `verify {feature} {taskId}` no merge de cada task (dispatch rolling, §3b), depois `morph-eval` + `morph-spec score`; `morph-spec verify {feature} --json` de escopo feature UMA vez, quando nada mais está em voo (o merge é o novo ponto de integração — verificação compartilhada obrigatória).
-4. **Cleanup:** o hook `WorktreeRemove` remove o worktree **limpo** ao fim do subagent (branch sobrevive) — mas não conte com ele: rode `morph-spec worktree remove --target <path>` por worktree que sobrou (NUNCA `git worktree remove` cru — as junctions do passo 1 seriam atravessadas e o `node_modules`/`.claude` da raiz apagados) + `git branch -d morph-task/<n>` das branches integradas + `git worktree prune` (fail-open). Worktree sujo (subagent não commitou) fica, vira `unintegrated-work` no `doctor --worktrees`, e a task volta a `pending`. Branches não integradas ficam e são registradas no recap com o motivo.
+4. **Cleanup:** o hook `WorktreeRemove` remove o worktree **limpo** ao fim do subagent (branch sobrevive) — mas não conte com ele: rode `morph-spec worktree remove --target <path>` por worktree que sobrou (NUNCA `git worktree remove` cru — as junctions do passo 1 seriam atravessadas e o `node_modules`/`.claude` da raiz apagados) + `git branch -d morph-task/<n>` das branches integradas + `git worktree prune` (fail-open). Depois de cada retorno de agent com `isolation`, e ao fim do batch, rode `morph-spec worktree reap --json`: remove só o worktree de `agent-<hex>` que parou limpo e sem commit exclusivo, e lista o resto com a razão (`not-a-registered-worktree` no `remove --target` seguinte = o reaper já o levou). Worktree sujo (subagent não commitou) fica, vira `agent-worktree-leftover` no `doctor --worktrees`, e a task volta a `pending`. Branches não integradas ficam e são registradas no recap com o motivo.
 5. **Agente morto no meio:** se commitou, a branch sobrevive (retomável); senão, a task volta a `pending` na lane sequencial. Registre a falha de protocolo no recap.
 
 > Anti-padrões: não misture unidades isoladas e não-isoladas no mesmo batch; o subagent nunca faz merge (integração é exclusiva do orquestrador).

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.44.0"
 ---
 
 # morph-brainstorming

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.42.0"
+cliVersion: "8.44.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-hotfix/SKILL.md

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.44.0"
 ---
 
 # morph-hotfix

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.42.0"
+cliVersion: "8.44.0"
 ---
 
 # morph-implement
@@ -132,7 +132,10 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
       por decisão sua; ao concluir, o relatório final substitui o parcial, sem o
       `PARCIAL`. Sem limite declarado, bastam os commits por marco.
    6. PROCESSOS: NUNCA `taskkill /IM node.exe` (derruba os MCPs de todas as
-      sessões). Encerre dev server pelo PID que você mesmo subiu.
+      sessões). Encerre dev server pelo PID que você mesmo subiu. Build e
+      suíte pesados (`dotnet build`, `dotnet test`, `docker compose up`) rodam
+      por `morph-spec heavy run -- <comando>`: exit 3 é fila cheia, não erro do
+      código — espere e repita.
    7. RETORNO: o relatório no arquivo canônico é o retorno. `SendMessage` não é
       substituto do relatório e não deve ser chamado.
    8. MUTAÇÃO: nunca altere, reverta, mova ou apague código de produção para ver
@@ -153,7 +156,9 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
    deixa o disco a meio caminho — e um relatório lido sobre uma árvore que ninguém conferiu avalia
    um estado que ninguém quis. Árvore inesperadamente suja ou `markers` não vazio é falha de
    protocolo: registre no recap antes de pontuar. Essa saída serve ao passo 7 enquanto a árvore
-   não mudar; depois de uma correção sua, rode de novo.
+   não mudar; depois de uma correção sua, rode de novo. Dispatch com `isolation: "worktree"`:
+   depois de ler o relatório, `morph-spec worktree reap --json` remove o worktree do agent que parou
+   limpo e sem commit exclusivo; o que fica vem listado com a razão.
 
    Após o retorno do dispatch: **leia primeiro** `.morph/features/{feature}/3-implement/reports/[ID].md`
    — é o valor de retorno autoritativo. Trate a mensagem de texto do sub-agent, se chegou inteira,
@@ -267,7 +272,7 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
    > tasks.json + recap.md + `taskScores` do feature.json. **NÃO escreva o trace
    > manualmente** — a escrita manual foi removida da cerimônia por task.
 
-9. Quando invocada por `morph-apply`, retornar o controle à skill orquestradora — ela decide qual task vem em seguida via `getReadyTasks(data)`. Não rode a suíte de testes inteira do projeto por conta própria ao fim da task quando invocada pela `morph-apply` — a verificação determinística (`morph-spec verify {feature} {task}`) é do orquestrador, logo após seu retorno (ver morph-apply §3a). **Única exceção:** a execução de evidência do passo 5 — só o nó `evals`, filtrado, com `--skip-e2e`, nunca persistida (`--no-persist`); ela não é a verificação da task e não substitui a do orquestrador. **A divisão:** no loop por task o recorte é **automático** — o `group` da task escolhe as suítes e os arquivos de teste dos `outputs` (passo 8) estreitam o comando dentro de cada uma (o relógio de uma task não paga a suíte inteira); `--filter {ids}` só força a escolha de suítes (um nó não casado aparece como `skip` nomeando o filtro, e um filtro que não casa nada é erro de uso, exit 2) e `--full` desliga o recorte. O sub-agent despachado roda só o filtro dos próprios testes, uma vez (cláusula 3), e nunca o `verify`. A suíte **inteira** roda no Gate 3 e no CI, sem filtro — `verify {feature}` nunca recorta. A suíte completa de um projeto grande não cabe numa invocação de Bash do harness — rode em background ou por partes, nunca "suba o limite" (não há constante de timeout global no CLI). Detalhe e forma de `project.tests[]`: `.morph/framework/CLI.md`, seção "Suítes de teste". Quando invocada manualmente, verificar se há próxima task ready e iniciá-la imediatamente aplicando esta skill desde o passo 1 (auto-advance). Pause apenas se encontrar ambiguidade bloqueante não coberta pelo mandate.
+9. Quando invocada por `morph-apply`, retornar o controle à skill orquestradora — ela decide qual task vem em seguida via `getReadyTasks(data)`. Não rode a suíte de testes inteira do projeto por conta própria ao fim da task quando invocada pela `morph-apply` — a verificação determinística (`morph-spec verify {feature} {task}`) é do orquestrador, logo após seu retorno (ver morph-apply §3a). **`verify` com exit 3** (`status: "busy"`) é fila de slot pesado cheia, não vermelho: nada foi verificado e nada foi gravado — repita a mesma chamada em vez de abrir uma tentativa de correção. **Única exceção:** a execução de evidência do passo 5 — só o nó `evals`, filtrado, com `--skip-e2e`, nunca persistida (`--no-persist`); ela não é a verificação da task e não substitui a do orquestrador. **A divisão:** no loop por task o recorte é **automático** — o `group` da task escolhe as suítes e os arquivos de teste dos `outputs` (passo 8) estreitam o comando dentro de cada uma (o relógio de uma task não paga a suíte inteira); `--filter {ids}` só força a escolha de suítes (um nó não casado aparece como `skip` nomeando o filtro, e um filtro que não casa nada é erro de uso, exit 2) e `--full` desliga o recorte. O sub-agent despachado roda só o filtro dos próprios testes, uma vez (cláusula 3), e nunca o `verify`. A suíte **inteira** roda no Gate 3 e no CI, sem filtro — `verify {feature}` nunca recorta. A suíte completa de um projeto grande não cabe numa invocação de Bash do harness — rode em background ou por partes, nunca "suba o limite" (não há constante de timeout global no CLI). Detalhe e forma de `project.tests[]`: `.morph/framework/CLI.md`, seção "Suítes de teste". Quando invocada manualmente, verificar se há próxima task ready e iniciá-la imediatamente aplicando esta skill desde o passo 1 (auto-advance). Pause apenas se encontrar ambiguidade bloqueante não coberta pelo mandate.
 
 ## Output esperado
 - Código implementado conforme o standard consultado (direto ou via sub-agent)

package/framework/skills/core/morph-machine/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: morph-machine
+description: Cuida da RAM e da CPU da máquina enquanto o morph-spec trabalha — fila de builds e testes pesados (heavy), processos órfãos, worktrees de sub-agent que sobram. Invoque quando a máquina ou o editor estiver lento ou sem RAM, quando um comando voltar "⏳ não rodou" ou sair com exit 3 (fila cheia), quando sobrar agent-* em worktrees/, ou antes de despachar vários sub-agents que compilam ou testam em paralelo.
+version: core
+when-to-invoke: quando a máquina está lenta ou sem RAM, um comando pesado esperou ou foi recusado pela fila, sobrou worktree de sub-agent, ou vários sub-agents pesados vão rodar em paralelo
+user-invokable: false
+cliVersion: "8.44.0"
+---
+
+# morph-machine
+
+## Objetivo
+
+Manter a máquina do dev utilizável enquanto o trabalho paralelo do morph-spec roda. Você aplica isto sozinho quando o sintoma aparece; o usuário não precisa pedir.
+
+## Regras que não se negociam
+
+- **Nunca** `taskkill /IM`, `pkill`, `killall` nem `Stop-Process -Name`: derrubam os MCPs de todas as sessões abertas. O único que encerra processo é `doctor --procs --prune`, e por PID.
+- **Fila cheia não é erro de código.** `⏳ … não rodou`, `slots pesados ocupados` e exit 3 querem dizer "espere e repita o MESMO comando". Não entra no loop de correção, não conta como tentativa e não é vermelho no `verify`.
+- **Nunca remova worktree** por `git worktree remove`, `rm -rf` ou `Remove-Item -Recurse`: atravessa a junction e apaga o conteúdo real da raiz. Só `finish`, `worktree remove` ou `worktree reap`.
+- **Destrutivo pergunta antes.** `doctor --procs --prune` e `worktree reap` (sem `--dry-run`): mostre a lista e use `AskUserQuestion`.
+
+## Sintoma → comando
+
+| Sintoma | Comando | Como ler e o que fazer |
+|---|---|---|
+| Máquina ou editor lento, pouca RAM | `morph-spec doctor --procs` (só lê) | Cada linha diz órfão ou protegido, com a razão. Sem órfão, a pressão vem de fora (vmmem do WSL, IDE): diga isso e passe a sugestão de `.wslconfig` que o relatório traz. Com órfão, mostre a lista e ofereça `--prune`. |
+| Comando voltou `⏳ … não rodou` ou exit 3 | `morph-spec heavy status` | Mostra quem segura cada vaga, há quanto tempo, e a RAM livre. A vaga solta sozinha (processo morto ou timeout). Espere e repita. Se a causa for RAM e nenhuma vaga estiver presa, rode `doctor --procs`. |
+| Vão rodar vários sub-agents pesados em paralelo | `morph-spec heavy status` antes | São 2 vagas por padrão. O que não couber espera na fila sem falhar, mas cada espera custa turnos: despache só o que cabe. |
+| Build ou teste pesado avulso, fora do `verify` | `morph-spec heavy run -- <comando>` | Ou ligue o `heavy.gateBash` (abaixo) e o hook cuida disso. |
+| Sobrou `agent-*` em `worktrees/` ou branch `morph-task/agent-*` | `morph-spec worktree reap --dry-run`, depois `worktree reap` | Só remove o que parou, está limpo e não tem commit exclusivo; o resto volta com a razão (`dirty`, `locked`…). `doctor --worktrees` lista tudo, inclusive árvore fora do contêiner. |
+| A worktree precisa de arquivo fora do git (`.env`, segredos) | `.worktreeinclude` na raiz do repo | Um padrão por linha, sintaxe do gitignore. Copia só o que casa **e** é ignorado; nunca `node_modules`, build ou `.git`. O `setup` e o `provision` aplicam. |
+| Editor pesado por causa das worktrees | `worktree.root` em `.morph/config/config.json` | Põe as worktrees fora da árvore aberta (caminho absoluto fora do projeto). `init` e `update` já gravam as exclusões no `.vscode/settings.json`. |
+
+## Ligar o `heavy.gateBash`
+
+Por padrão só o `verify`, o `e2e up` e o `heavy run` passam pela fila. O `dotnet build`, `dotnet test` ou `npm test` cru de um sub-agent não passa. Com `"heavy": { "gateBash": true }` em `.morph/config/config.json` (depois `morph-spec update`), um hook toma a vaga antes desses comandos e a devolve depois; sem vaga no prazo, a chamada é recusada com a causa.
+
+Recomende (`AskUserQuestion`, com a opção recomendada primeiro) quando sub-agents rodam build ou teste cru em paralelo, quando há mais de uma sessão na máquina, ou quando já houve queda por RAM. **Nunca ligue sem perguntar:** o efeito é uma chamada recusada quando a fila enche.
+
+Limites: não cobre `run_in_background`, PowerShell nem comando fora da lista; uma chamada negada por regra ou interrompida segura a vaga até o timeout dela.
+
+## Referências
+
+- `.morph/framework/CLI.md` — seções `heavy`, `worktree reap`, `doctor --procs` e `worktree.root`.
+- `MORPH.md` §2.2 (worktrees) e a cláusula 6 dos templates de dispatch (PROCESSOS).

package/framework/skills/core/morph-media/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a AUTORIA de mídia gerada por IA — escolher o modelo pelo
 version: core
 when-to-invoke: quando a tarefa é PRODUZIR imagem ou vídeo por IA (catálogo, marketing, asset de LP) e alguém precisa decidir modelo, prompt e aprovação
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.44.0"
 stacks:
   - dotnet
   - nextjs

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.44.0"
 ---
 
 # morph-plan

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.42.0"
+cliVersion: "8.44.0"
 ---
 
 # morph-proposal