@polymorphism-tech/morph-spec 8.41.0 → 8.43.0

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

@@ -0,0 +1,85 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { freemem, homedir } from 'node:os';
+import { join } from 'node:path';
+import { pidAlive } from './process-alive.js';
+
+export const GB = 1024 ** 3;
+export const WRITE_GRACE_MS = 5000;
+export const EXCLUSIVE_MAX_AGE_MS = 2 * 60 * 1000;
+export const SLOT_FILE = /^slot-\d+\.lock$/;
+
+export function heavyDir(env = process.env, { platform = process.platform, home = homedir() } = {}) {
+  if (env.MORPH_HEAVY_DIR) return env.MORPH_HEAVY_DIR;
+  if (platform === 'win32') return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'morph-spec', 'heavy');
+  return join(env.XDG_STATE_HOME || join(home, '.local', 'state'), 'morph-spec', 'heavy');
+}
+
+export const mtimeOf = (path) => {
+  try { return statSync(path).mtimeMs; } catch { return null; }
+};
+
+const leaseTtlMs = (meta) => (Number.isFinite(meta.ttlMs) && meta.ttlMs > 0 ? meta.ttlMs : Infinity);
+
+export function readLockFile(path, { now, isAlive, maxHoldMs }) {
+  const t = now();
+  let meta;
+  try {
+    meta = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    const mtime = mtimeOf(path);
+    if (mtime === null) return null;
+    const writing = t - mtime < WRITE_GRACE_MS;
+    return { path, pid: null, since: null, label: '(gravando)', live: writing, unreadable: true };
+  }
+  const age = t - Date.parse(meta.since);
+  const inWindow = age >= 0 && age < maxHoldMs;
+  // A per-call lease belongs to a hook process that is long gone: only its TTL says when it lapses.
+  const live = meta.leaseId ? inWindow && age < leaseTtlMs(meta) : inWindow && Boolean(isAlive(meta.pid));
+  return { ...meta, path, live };
+}
+
+export function scanHolders(dir, ctx) {
+  let names = [];
+  try { names = readdirSync(dir).filter((n) => SLOT_FILE.test(n)); } catch { return { live: [], stale: [] }; }
+  const live = [];
+  const stale = [];
+  for (const name of names) {
+    const holder = readLockFile(join(dir, name), ctx);
+    if (!holder) continue;
+    (holder.live ? live : stale).push(holder);
+  }
+  return { live, stale };
+}
+
+export function readHolders(dir, ctx) {
+  return scanHolders(dir, ctx).live;
+}
+
+export function readExclusive(dir, ctx) {
+  const holder = readLockFile(join(dir, 'exclusive.lock'), { ...ctx, maxHoldMs: EXCLUSIVE_MAX_AGE_MS });
+  return holder?.live ? holder : null;
+}
+
+const ageText = (ms) => {
+  const min = Math.floor(ms / 60000);
+  return min < 1 ? `${Math.max(0, Math.floor(ms / 1000))}s` : `${min}m`;
+};
+
+export function describeHolder(h, now = Date.now()) {
+  const what = [h.label, [h.feature, h.node].filter(Boolean).join('/')].filter(Boolean).join(' ');
+  const age = h.since ? `, há ${ageText(now - Date.parse(h.since))}` : '';
+  const who = h.leaseId ? 'chamada Bash' : `pid ${h.pid ?? '?'}`;
+  return `${what || 'processo'}, ${who}${age}`;
+}
+
+export function heavyStatus({
+  dir, maxHoldMs, now = Date.now, isAlive = pidAlive, freeMem = freemem,
+}) {
+  const ctx = { now, isAlive, maxHoldMs };
+  return {
+    dir,
+    holders: readHolders(dir, ctx),
+    exclusive: readExclusive(dir, ctx),
+    freeGb: freeMem() / GB,
+  };
+}

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/source-files.js

@@ -0,0 +1,34 @@
+/**
+ * Which files count as the project's hand-written source. One reading for the
+ * `reuse` and `code-budget` validators and the `comment-guard` hook, so the
+ * three never disagree about the same file.
+ *
+ * @module source-files
+ */
+
+const SCANNABLE = /\.(cs|ts|tsx|js|jsx|mjs|cjs)$/i;
+
+// `.morph/` is real: an archived feature's `contracts.cs` entered ProspectPRO's
+// graph as a second `RoulettePriority`.
+const NOT_SOURCE = /(^|\/)(?:\.morph|node_modules|dist|build|out|\.next|bin|obj|coverage)\//;
+
+const DECLARATION_FILE = /\.d\.ts$/i;
+
+const GENERATED = /(?:\.Designer|\.g|\.g\.i)\.cs$|ModelSnapshot\.cs$/i;
+
+/**
+ * @param {string} sourceFile
+ * @returns {boolean} project code in a scanned extension, tests included
+ */
+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} generated C# nobody writes by hand
+ */
+export function isGenerated(sourceFile) {
+  return GENERATED.test(String(sourceFile || ''));
+}

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/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.41.0"
+cliVersion: "8.43.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.41.0"
+cliVersion: "8.43.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.41.0"
+cliVersion: "8.43.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
@@ -193,7 +195,9 @@ dispatch Agent (subagent_type: "morph-{id}") with prompt:
     Comentário: o padrão é nenhum. Nome, tipo e teste explicam o código; sem
     `///`/JSDoc em membro de aplicação, cabeçalho, banner de seção ou história
     da task. Só o porquê que o código não mostra, em uma linha
-    (`architecture-code-comments`).
+    (`architecture-code-comments`). O elo com a pós-condição vai no nome do
+    teste; a densidade do arquivo vizinho não é modelo. O hook `comment-guard`
+    bloqueia a edição que adiciona história, banner ou bloco longo.
     Não modifique spec.md, mandate.md.
 
     Contrato do relatório final:
@@ -236,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
@@ -294,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.41.0"
+cliVersion: "8.43.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.41.0"
+cliVersion: "8.43.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.41.0"
+cliVersion: "8.43.0"
 ---
 
 # morph-hotfix