@polymorphism-tech/morph-spec 9.6.0 → 9.7.0

package/framework/hooks/shared/host-services.js

@@ -0,0 +1,433 @@
+// Host processes that the e2e stack runs next to compose (api, portal), one PID file per project.
+// Nothing here imports e2e-check.js: it imports this module, and the timing constants mirror its own.
+
+import { execFileSync, spawn, spawnSync } from 'child_process';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+import { tokenize } from './command-tokens.js';
+import { pidAlive } from './process-alive.js';
+
+export const DEFAULT_HOST_TIMEOUT = 180_000;
+
+const HEALTH_POLL_MS = 2_000;
+
+const OUTPUT_TAIL_LINES = 20;
+
+const NO_HEALTH_GRACE_MS = 2_000;
+
+const KILL_WAIT_MS = 5_000;
+
+const VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+export function hostStatePath(gitCommonDir, projectName) {
+  return join(gitCommonDir, 'morph-spec', `e2e-host-${projectName}.json`);
+}
+
+export function hostLogPath(gitCommonDir, projectName, name) {
+  return join(gitCommonDir, 'morph-spec', `e2e-host-${projectName}-${name}.log`);
+}
+
+/** Process creation time as the OS reports it, or null when the PID is gone. */
+export function readProcessCreatedAt(pid, platform = process.platform) {
+  try {
+    const out = platform === 'win32'
+      ? execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command',
+        `(Get-Process -Id ${Number(pid)}).StartTime.ToFileTimeUtc()`],
+      { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] })
+      : execFileSync('ps', ['-o', 'lstart=', '-p', String(Number(pid))],
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Resolves `${VAR}` in `env` and `health`: stack env first, then `process.env`. */
+export function interpolateEnv(service, stackEnv = {}) {
+  const missing = new Set();
+  const sub = (text) => String(text).replace(VAR_RE, (_, name) => {
+    const value = stackEnv?.[name] ?? process.env[name];
+    if (value === undefined || value === null || value === '') {
+      missing.add(name);
+      return '';
+    }
+    return String(value);
+  });
+  const env = {};
+  for (const [key, value] of Object.entries(service.env ?? {})) env[key] = sub(value);
+  const health = service.health ? sub(service.health) : null;
+  return { env, health, missing: [...missing] };
+}
+
+const SERVICE_KEYS = new Set(['name', 'cwd', 'build', 'start', 'env', 'health', 'timeoutMs']);
+
+function validateServices(services) {
+  if (!Array.isArray(services)) return 'e2e.hostServices must be an array';
+  const seen = new Set();
+  for (const [i, svc] of services.entries()) {
+    const label = typeof svc?.name === 'string' && svc.name ? `"${svc.name}"` : `#${i}`;
+    if (!svc || typeof svc !== 'object' || Array.isArray(svc)) return `e2e.hostServices[${i}] must be an object`;
+    if (typeof svc.name !== 'string' || !/^[A-Za-z0-9._-]+$/.test(svc.name)) {
+      return `e2e.hostServices[${i}].name must be a non-empty string of [A-Za-z0-9._-]`;
+    }
+    if (seen.has(svc.name)) return `e2e.hostServices has two services named "${svc.name}"`;
+    seen.add(svc.name);
+    const unknown = Object.keys(svc).find((key) => !SERVICE_KEYS.has(key));
+    if (unknown) return `hostService ${label}: unknown field "${unknown}"`;
+    if (typeof svc.start !== 'string' || !svc.start.trim()) return `hostService ${label}: "start" must be a non-empty string`;
+    for (const field of ['cwd', 'build', 'health']) {
+      if (svc[field] !== undefined && typeof svc[field] !== 'string') return `hostService ${label}: "${field}" must be a string`;
+    }
+    if (svc.env !== undefined) {
+      if (!svc.env || typeof svc.env !== 'object' || Array.isArray(svc.env)) return `hostService ${label}: "env" must be an object`;
+      for (const [key, value] of Object.entries(svc.env)) {
+        if (typeof value !== 'string' && typeof value !== 'number') {
+          return `hostService ${label}: env.${key} must be a string or number`;
+        }
+      }
+    }
+    if (svc.timeoutMs !== undefined && !(Number.isFinite(svc.timeoutMs) && svc.timeoutMs > 0)) {
+      return `hostService ${label}: "timeoutMs" must be a positive number`;
+    }
+  }
+  return null;
+}
+
+function readState(gitCommonDir, projectName) {
+  try {
+    const parsed = JSON.parse(readFileSync(hostStatePath(gitCommonDir, projectName), 'utf8').replace(/^/, ''));
+    return Array.isArray(parsed?.services) ? parsed.services : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(gitCommonDir, projectName, records) {
+  const target = hostStatePath(gitCommonDir, projectName);
+  if (records.length === 0) {
+    try { unlinkSync(target); } catch { /* already gone */ }
+    return;
+  }
+  mkdirSync(join(gitCommonDir, 'morph-spec'), { recursive: true });
+  const tmp = `${target}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify({ version: 1, project: projectName, services: records }, null, 2)}\n`, 'utf8');
+  renameSync(tmp, target);
+}
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+const PROBE_SCRIPT =
+  'fetch(process.argv[1],{signal:AbortSignal.timeout(Number(process.argv[2]))})' +
+  '.then(r=>process.exit(r.status<500?0:1),()=>process.exit(1))';
+
+function probeHealth(url, timeoutMs = 1_500) {
+  const r = spawnSync(process.execPath, ['-e', PROBE_SCRIPT, url, String(timeoutMs)], {
+    timeout: timeoutMs + 1_000,
+    windowsHide: true,
+    stdio: 'ignore',
+  });
+  return r.status === 0;
+}
+
+// Only the recorded identity may be killed: a recycled PID belongs to someone else.
+function killRecord(record, readCreatedAt) {
+  if (!running(record.pid)) {
+    return { killed: false, warning: `hostService "${record.name}": PID ${record.pid} was no longer running; record dropped` };
+  }
+  const current = readCreatedAt(record.pid);
+  if (!record.createdAt || current !== record.createdAt) {
+    return {
+      killed: false,
+      warning: `hostService "${record.name}": PID ${record.pid} is alive but its creation time differs ` +
+        `from the recorded one (recycled PID); not killed, record dropped`,
+    };
+  }
+  if (process.platform === 'win32') killWindowsTree(record.pid);
+  else killPosixGroup(record.pid);
+  return { killed: true };
+}
+
+function waitUntil(predicate) {
+  const deadline = Date.now() + KILL_WAIT_MS;
+  while (!predicate() && Date.now() < deadline) sleep(100);
+  return predicate();
+}
+
+// The process that spawned the shell blocks in a sync loop and never reaps it: a zombie is not alive.
+function running(pid) {
+  if (!pidAlive(pid)) return false;
+  if (process.platform === 'win32') return true;
+  const r = spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], { encoding: 'utf8' });
+  return r.status !== 0 || !String(r.stdout).trim().startsWith('Z');
+}
+
+function groupAlive(pgid) {
+  const r = spawnSync('ps', ['-A', '-o', 'pgid=,stat='], { encoding: 'utf8' });
+  if (r.status !== 0) {
+    try {
+      process.kill(-pgid, 0);
+      return true;
+    } catch (err) {
+      return err?.code === 'EPERM';
+    }
+  }
+  return String(r.stdout).split('\n').some((line) => {
+    const [group, stat = ''] = line.trim().split(/\s+/);
+    return Number(group) === pgid && !stat.startsWith('Z');
+  });
+}
+
+// The port belongs to the grandchild, not the shell: wait on the whole group.
+function killPosixGroup(pgid) {
+  try { process.kill(-pgid, 'SIGTERM'); } catch { /* group already gone */ }
+  if (!waitUntil(() => !groupAlive(pgid))) {
+    try { process.kill(-pgid, 'SIGKILL'); } catch { /* group already gone */ }
+    waitUntil(() => !groupAlive(pgid));
+  }
+}
+
+const WIN_SNAPSHOT =
+  'Get-CimInstance Win32_Process | ForEach-Object { [pscustomobject]@{ p = $_.ProcessId; pp = $_.ParentProcessId; ' +
+  't = if ($_.CreationDate) { $_.CreationDate.ToFileTimeUtc() } else { 0 } } } | ConvertTo-Json -Compress';
+
+function windowsSnapshot() {
+  try {
+    const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', WIN_SNAPSHOT],
+      { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024 });
+    const parsed = JSON.parse(out.trim() || '[]');
+    return Array.isArray(parsed) ? parsed : [parsed];
+  } catch {
+    return [];
+  }
+}
+
+// Windows keeps a dead parent's PID in ParentProcessId, so a child only counts when born after its parent.
+function windowsDescendants(rows, roots) {
+  const byPid = new Map(rows.map((r) => [r.p, r]));
+  const found = [];
+  const queue = [...roots];
+  while (queue.length > 0) {
+    const parent = byPid.get(queue.shift());
+    if (!parent) continue;
+    for (const row of rows) {
+      if (row.pp === parent.p && row.p !== parent.p && row.t >= parent.t && !found.includes(row.p) && !roots.includes(row.p)) {
+        found.push(row.p);
+        queue.push(row.p);
+      }
+    }
+  }
+  return found;
+}
+
+// Every PID goes through process.kill: killing via a console tool is banned in hooks (doctor-procs canary).
+// The rescan catches a child spawned between the snapshot and its parent's death.
+function killWindowsTree(rootPid) {
+  const first = windowsSnapshot();
+  const killed = [rootPid, ...windowsDescendants(first, [rootPid])];
+  for (const pid of killed) {
+    try { process.kill(pid); } catch { /* already gone */ }
+  }
+  const killedRows = first.filter((r) => killed.includes(r.p));
+  const rescan = windowsSnapshot().filter((r) => !killed.includes(r.p));
+  const stragglers = windowsDescendants([...killedRows, ...rescan], killed);
+  for (const pid of stragglers) {
+    try { process.kill(pid); } catch { /* already gone */ }
+  }
+  waitUntil(() => [...killed, ...stragglers].every((pid) => !pidAlive(pid)));
+}
+
+function tailLines(text, n = OUTPUT_TAIL_LINES) {
+  return String(text || '').trimEnd().split(/\r?\n/).slice(-n).join('\n');
+}
+
+function readLogTail(path) {
+  try { return tailLines(readFileSync(path, 'utf8')); } catch { return ''; }
+}
+
+/** @returns {{ killed: string[], skipped: string[], warnings: string[] }} */
+export function stopHostServices(gitCommonDir, projectName, { readCreatedAt = readProcessCreatedAt } = {}) {
+  const result = { killed: [], skipped: [], warnings: [] };
+  if (!gitCommonDir) return result;
+  const records = readState(gitCommonDir, projectName);
+  if (!records) return result;
+  for (const record of records) {
+    const outcome = killRecord(record, readCreatedAt);
+    if (outcome.killed) result.killed.push(record.name);
+    else {
+      result.skipped.push(record.name);
+      result.warnings.push(outcome.warning);
+    }
+  }
+  writeState(gitCommonDir, projectName, []);
+  return result;
+}
+
+/** Liveness by PID only: the creation-time read is too slow for a poll. */
+export function hostServicesStatus(gitCommonDir, projectName) {
+  const records = readState(gitCommonDir, projectName) ?? [];
+  return records.map((r) => {
+    const alive = pidAlive(r.pid);
+    return { name: r.name, pid: r.pid, alive, health: r.health ? alive && probeHealth(r.health) : null };
+  });
+}
+
+// A detached cmd.exe has no console, so the console apps it starts get a fresh one and drop the
+// log handles; a detached node holding the shell keeps them inherited down the tree.
+const WIN_LAUNCHER =
+  "const c=require('child_process').spawn(process.argv[1],{shell:true,stdio:'inherit',windowsHide:true});" +
+  'c.on(\'exit\',(k)=>process.exit(k??1))';
+
+function launch(svc, ctx, deadline, exec) {
+  const fail = (reason, output = '') => ({ ok: false, reason: `hostService "${svc.name}": ${reason}`, output });
+  const remaining = () => deadline - Date.now();
+
+  if (svc.build) {
+    const [file, ...args] = tokenize(svc.build);
+    const built = exec(file, args, { cwd: svc.dir, env: svc.childEnv, timeout: remaining() });
+    // A build killed at its timeout comes back as a plain non-zero exit: the deadline decides first.
+    if (remaining() <= 0) return fail(`timed out after ${svc.timeoutMs} ms during build`, tailLines(built.output));
+    if (built.code !== 0) return fail(`build failed (${svc.build}, exit ${built.code})`, tailLines(built.output));
+  }
+
+  const log = hostLogPath(ctx.gitCommonDir, ctx.projectName, svc.name);
+  mkdirSync(join(ctx.gitCommonDir, 'morph-spec'), { recursive: true });
+  const fd = openSync(log, 'w');
+  let child;
+  try {
+    // The CLI ends with process.exit: the child must own its group and hold none of our pipes.
+    const win = process.platform === 'win32';
+    child = spawn(win ? process.execPath : svc.start, win ? ['-e', WIN_LAUNCHER, svc.start] : [], {
+      cwd: svc.dir,
+      env: { ...process.env, ...svc.childEnv },
+      shell: !win,
+      detached: true,
+      windowsHide: true,
+      stdio: ['ignore', fd, fd],
+    });
+    child.on('error', () => {});
+    child.unref();
+  } finally {
+    closeSync(fd);
+  }
+  if (!child?.pid) return fail(`could not start (${svc.start})`, readLogTail(log));
+
+  const record = {
+    name: svc.name,
+    pid: child.pid,
+    createdAt: ctx.readCreatedAt(child.pid),
+    stamp: ctx.stamp ?? null,
+    log,
+    health: svc.health,
+  };
+
+  if (!svc.health) {
+    sleep(Math.min(NO_HEALTH_GRACE_MS, Math.max(remaining(), 0)));
+    if (!running(child.pid)) return { ...fail('exited right after start', readLogTail(log)), record };
+    return { ok: true, record };
+  }
+
+  while (true) {
+    if (probeHealth(svc.health)) return { ok: true, record };
+    if (!running(child.pid)) return { ...fail('exited before its health check went green', readLogTail(log)), record };
+    if (remaining() <= 0) {
+      return { ...fail(`health ${svc.health} not green within ${svc.timeoutMs} ms`, readLogTail(log)), record };
+    }
+    sleep(Math.min(HEALTH_POLL_MS, remaining()));
+  }
+}
+
+function isReusable(record, svc, ctx) {
+  if (!record || !running(record.pid)) return false;
+  if (ctx.readCreatedAt(record.pid) !== record.createdAt) return false;
+  return svc.health ? probeHealth(svc.health) : true;
+}
+
+/** @returns {{ status: 'pass'|'fail'|'skip', reused: boolean, services: object[], warnings: string[], reason?: string, output?: string }} */
+export function startHostServices(cwd, options = {}, exec) {
+  const {
+    services,
+    env: stackEnv = {},
+    gitCommonDir,
+    projectName,
+    stamp = null,
+    forceFresh = false,
+    readCreatedAt = readProcessCreatedAt,
+  } = options;
+
+  if (services === undefined || (Array.isArray(services) && services.length === 0)) {
+    return { status: 'skip', reused: false, services: [], warnings: [], reason: 'no e2e.hostServices configured' };
+  }
+  const invalid = validateServices(services);
+  if (invalid) return { status: 'fail', reused: false, services: [], warnings: [], reason: invalid };
+
+  const resolved = [];
+  for (const svc of services) {
+    const { env, health, missing } = interpolateEnv(svc, stackEnv);
+    if (missing.length > 0) {
+      return {
+        status: 'fail',
+        reused: false,
+        services: [],
+        warnings: [],
+        reason: `hostService "${svc.name}": no value for ${missing.map((v) => `\${${v}}`).join(', ')} ` +
+          '(looked in the e2e stack env and the process env)',
+      };
+    }
+    const dir = resolve(cwd, svc.cwd ?? '.');
+    if (!existsSync(dir)) {
+      return { status: 'fail', reused: false, services: [], warnings: [], reason: `hostService "${svc.name}": cwd ${dir} does not exist` };
+    }
+    resolved.push({
+      name: svc.name,
+      dir,
+      build: svc.build,
+      start: svc.start,
+      health,
+      timeoutMs: svc.timeoutMs ?? DEFAULT_HOST_TIMEOUT,
+      childEnv: { ...stackEnv, ...env },
+    });
+  }
+
+  const ctx = { gitCommonDir, projectName, stamp, readCreatedAt };
+  const previous = readState(gitCommonDir, projectName) ?? [];
+  const sameSet = previous.length === resolved.length && resolved.every((s) => previous.some((r) => r.name === s.name));
+  const divergent = forceFresh || !sameSet || previous.some((r) => r.stamp !== stamp);
+  const warnings = divergent && previous.length > 0
+    ? stopHostServices(gitCommonDir, projectName, { readCreatedAt }).warnings
+    : [];
+  const prior = divergent ? [] : previous;
+
+  const records = [];
+  const startedNow = [];
+  const out = [];
+  for (const [i, svc] of resolved.entries()) {
+    const old = prior.find((r) => r.name === svc.name);
+    if (isReusable(old, svc, ctx)) {
+      records.push(old);
+      out.push({ name: svc.name, pid: old.pid, reused: true, log: old.log });
+      continue;
+    }
+    if (old) {
+      const killed = killRecord(old, readCreatedAt);
+      if (killed.warning) warnings.push(killed.warning);
+    }
+
+    const result = launch(svc, ctx, Date.now() + svc.timeoutMs, exec);
+    if (!result.ok) {
+      for (const r of [...startedNow, result.record].filter(Boolean)) killRecord(r, readCreatedAt);
+      const unreached = resolved.slice(i + 1).map((s) => prior.find((r) => r.name === s.name)).filter(Boolean);
+      const kept = [...records.filter((r) => !startedNow.includes(r)), ...unreached];
+      writeState(gitCommonDir, projectName, kept);
+      return { status: 'fail', reused: false, services: out, warnings, reason: result.reason, output: result.output };
+    }
+    records.push(result.record);
+    startedNow.push(result.record);
+    writeState(gitCommonDir, projectName, records);
+    out.push({ name: svc.name, pid: result.record.pid, reused: false, log: result.record.log });
+  }
+
+  return { status: 'pass', reused: startedNow.length === 0, services: out, warnings };
+}

package/framework/schemas/config.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "MORPH-SPEC .morph/config/config.json",
-  "description": "Describes project.tests[] — the plural declaration of the project's test suites — and finishBackup.retention. Everything else in config.json is deliberately left open (additionalProperties: true) so that configs already in the field never break on a key this schema has not heard of. The authorities at runtime are validateTestNodes() in src/lib/tasks/test-nodes.js and resolveBackupRetention() in src/lib/worktree/finish-backup.js: a schema nothing calls is decoration.",
+  "description": "Describes project.tests[] — the plural declaration of the project's test suites —, e2e.hostServices and finishBackup.retention. Everything else in config.json is deliberately left open (additionalProperties: true) so that configs already in the field never break on a key this schema has not heard of. The authorities at runtime are validateTestNodes() in src/lib/tasks/test-nodes.js and resolveBackupRetention() in src/lib/worktree/finish-backup.js: a schema nothing calls is decoration.",
   "type": "object",
   "additionalProperties": true,
   "properties": {
@@ -119,6 +119,58 @@
         }
       }
     },
+    "e2e": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "The verification stack of `e2e up` and of the verify e2e node. Only hostServices is described here; the other keys (auth, command, portEnvNames, ...) stay open.",
+      "properties": {
+        "hostServices": {
+          "type": "array",
+          "description": "Apps that run as host processes next to the compose stack, when building them inside the Docker VM is expensive: compose keeps only the dependencies. Order on `e2e up` and on the verify e2e node: compose up --wait, then each service in array order (build, start detached, health), then the auth seed. They stay up until `e2e down`, `finish`, `delete` or `worktree remove`. Reused while the code stamp (HEAD + status + diff) matches and health is green; a divergent stamp or --fresh/--fresh-e2e kills, rebuilds and restarts them. A failure (build exit != 0, timeout, health never green) fails `e2e up` (exit 1) and the e2e node with the service name and its log tail, kills what this run started and skips the seed. The authority at runtime is validateServices() in framework/hooks/shared/host-services.js.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "start"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9._-]+$",
+                "description": "Unique in the array. Names the log file (<git-common-dir>/morph-spec/e2e-host-<project>-<name>.log) and every message about the service."
+              },
+              "cwd": {
+                "type": "string",
+                "default": ".",
+                "description": "Working directory of build and start, relative to the project root. One that does not exist refuses."
+              },
+              "build": {
+                "type": "string",
+                "description": "Runs before start; a non-zero exit fails the bring-up."
+              },
+              "start": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The process, started detached; its output goes to the service log."
+              },
+              "env": {
+                "type": "object",
+                "additionalProperties": { "type": ["string", "number"] },
+                "description": "Added on top of process.env and the stack env (port block + e2e.auth.envFile). ${VAR} is resolved from the stack env, then process.env; a VAR with no value (or an empty one) refuses before any build, naming the variable and the service."
+              },
+              "health": {
+                "type": "string",
+                "description": "URL polled until it answers with an HTTP status below 500. ${VAR} interpolates like env. Without it, a process still alive 2 s after start counts as ready."
+              },
+              "timeoutMs": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "default": 180000,
+                "description": "Ceiling for build + start + health together."
+              }
+            }
+          }
+        }
+      }
+    },
     "finishBackup": {
       "type": "object",
       "additionalProperties": true,

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_use: Use quando for iniciar um novo projeto de LP com o template Umbraco genérico
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.7.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_use: Use quando o usuário pedir "use /migrate-lp-to-umbraco {projeto}" ou descrever a necessidade de migrar uma LP para Umbraco
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.7.0"
 stacks:
   - umbraco
 ---

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

@@ -4,7 +4,7 @@ description: Executa as fatias do plano de uma feature morph-spec — dispatch p
 version: core
 when_to_use: Use com o gate do plano aprovado, em "use /morph-apply {feature}" ou "implementar feature"
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-apply

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_use: Use quando chegar "/morph-hotfix {feature}", quando a morph-plan rotear o pedido como workType hotfix, ou quando o usuário disser "produção caiu / hotfix / urgente" a respeito de um incidente
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-hotfix

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

@@ -4,7 +4,7 @@ description: Cuida da RAM e da CPU da máquina enquanto o morph-spec trabalha
 version: core
 when_to_use: Use quando a máquina estiver 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-invocable: false
-cliVersion: "9.6.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-machine

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_use: Use quando a tarefa for PRODUZIR imagem ou vídeo por IA (catálogo, marketing, asset de LP) e alguém precisar decidir modelo, prompt e aprovação
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.7.0"
 stacks:
   - dotnet
   - nextjs

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

@@ -4,7 +4,7 @@ description: Leva uma feature do pedido ao plano aprovado — roteia o tipo de t
 version: core
 when_to_use: Use quando uma feature, bug ou chore começar ("/morph-plan {feature}", "vamos planejar X"), ou ao retomar uma feature cujo gate plan ainda não foi aprovado
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-plan
@@ -105,7 +105,7 @@ O `create` já escreveu o esqueleto em `2-plan/plan.md` (leia e preencha; `chore
 - Cenário que se observa por um artefato de outra fatia (rota, endpoint, componente que ela cria) faz da fatia que o cobre um `depende:` daquela — senão as duas caem na mesma onda e o teste do cenário não tem por onde provar. O `plan-check` não vê de quem é a rota: a regra é sua.
 
 **Contrato de implementação**: o que quem implementa precisa e o código não diz.
-- **Verificação de runtime:** o stack sobe por `morph-spec e2e up {feature}` (compose do projeto; sem compose, isso é uma fatia); os fluxos que o verificador navega, nos verbos dos cenários; base URL `process.env.PLAYWRIGHT_BASE_URL ?? \`http://localhost:${process.env.PORT ?? 3000}\``, compose com `"${PORT:-3000}:3000"` e sem `container_name` (standard `infrastructure/docker/local-compose-isolation`). App com login: `e2e.auth` em `config.json` (`mode: seed|storageState|bypass|none`, `seedCommand`, `storageStatePath`, `envFile`), credenciais num `.env.e2e` gitignored — **`mode` é obrigatório sempre que houver `seedCommand`**, sem ele o seed fica inerte. Biblioteca pura: registre a dispensa e o porquê.
+- **Verificação de runtime:** o stack sobe por `morph-spec e2e up {feature}` (compose do projeto; sem compose, isso é uma fatia); os fluxos que o verificador navega, nos verbos dos cenários; base URL `process.env.PLAYWRIGHT_BASE_URL ?? \`http://localhost:${process.env.PORT ?? 3000}\``, compose com `"${PORT:-3000}:3000"` e sem `container_name` (standard `infrastructure/docker/local-compose-isolation`). App cujo build é caro dentro do Docker sobe como processo do host por `e2e.hostServices` (compose só com as dependências; campos em `morph-spec e2e --help`). App com login: `e2e.auth` em `config.json` (`mode: seed|storageState|bypass|none`, `seedCommand`, `storageStatePath`, `envFile`), credenciais num `.env.e2e` gitignored — **`mode` é obrigatório sempre que houver `seedCommand`**, sem ele o seed fica inerte. Biblioteca pura: registre a dispensa e o porquê.
 - **Baseline é um COMANDO, nunca um número.** O plano congela e é lido por dias: um número cravado está errado na primeira fatia, e quem confia nele "conserta" o que não quebrou. Registre como medir (`npm test`, `dotnet test`); o `expectedCount` sai de `morph-spec verify {feature} --record-baseline`, nunca digitado. Sem `project.stack`/`project.tests` no `config.json`, a `morph-apply` os declara a partir destes comandos antes do primeiro verify.
 - **Pré-requisito é um PREDICADO, nunca um SHA literal:** "`git merge-base --is-ancestor origin/main HEAD` sai 0" — o SHA muda no primeiro squash.
 

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

@@ -4,7 +4,7 @@ description: Conduz o Gate 3 — despacha verificador ∥ revisor (∥ seguranç
 version: core
 when_to_use: Use quando a fase review começar, com todas as fatias com relatório final e o verify da feature verde
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-review
@@ -51,7 +51,8 @@ símbolo público do diff, `morph-spec graph affected <símbolo> --prod --json`;
 (`no-graph`/`not-found`/`ambiguous`), siga sem o blast radius — o revisor cai para `git grep` — e
 registre a ausência no recado a ele. Cada agente nasce com contexto fresco e **nunca recebe relatório anterior** (ancoragem).
 `chore` tem review leve: só o revisor (∥ segurança, quando exigida) — sem verificador, sem cobertura de
-`Cn`, sem mutação. Despache todos na mesma resposta:
+`Cn`, sem mutação. Despache todos na mesma resposta, **sem nome no dispatch**: com nome, o `agent_type` que o hook
+`test-budget` lê vira o nome, e o guard de review não reconhece o papel.
 ```
 dispatch Agent (subagent_type: "morph-verifier", model: {reviewModels.verifier.model}) with prompt:
   feature, base, sha, JSON do verify (nós, e2e, URL) se já terminou, 1-design/mockups.md e

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

@@ -4,7 +4,7 @@ description: Localiza um standard específico via busca server-side (morph-spec
 version: core
 when_to_use: Use quando precisar consultar um standard específico durante a implementação
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-standards

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

@@ -4,7 +4,7 @@ description: Conduz a fase opcional de UI/UX de uma feature com plano aprovado
 version: core
 when_to_use: Use quando o ramo de design for tomado (morph-spec advance {feature} --design, depois do gate do plano) e antes de /morph-apply
 user-invocable: true
-cliVersion: "9.6.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-uiux

package/framework/standards/STANDARDS.json

@@ -1629,9 +1629,10 @@
         "portNames": "#project-named-port-variables",
         "rules": "#core-rules",
         "enforcement": "#what-the-harness-enforces",
+        "hostServices": "#services-on-the-host",
         "skeleton": "#minimal-compose-skeleton"
       },
-      "digest": "Every worktree runs its OWN compose stack (project morph-{feature}, own postgres, own volumes). Ports come from the worktree block: PORT +0, API_PORT +1 (ASPNETCORE_URLS on .NET), POSTGRES_PORT +2, REDIS_PORT +3 — publish via ${VAR:-default}:container, never a fixed host port, never container_name (not prefixed by the project → collides). Stable POSTGRES_DB, healthcheck on every service, DATABASE_URL with an in-network default, playwright.config reads PLAYWRIGHT_BASE_URL. A non-isolable compose fails the verify e2e node inside a worktree. finish tears down with volumes (--keep-volumes opts out). Cloud DB credentials go in e2e.auth.envFile, never in .morph/worktree.env. A compose that reads a port by ANOTHER name (PG_PORT) is not fed by the block: declare it in config.json e2e.portEnvNames ({\"postgres\": \"PG_PORT\"}) and the harness exports it with the same value in worktree.env, the compose env and the hook."
+      "digest": "Every worktree runs its OWN compose stack (project morph-{feature}, own postgres, own volumes). Ports come from the worktree block: PORT +0, API_PORT +1 (ASPNETCORE_URLS on .NET), POSTGRES_PORT +2, REDIS_PORT +3 — publish via ${VAR:-default}:container, never a fixed host port, never container_name (not prefixed by the project → collides). Stable POSTGRES_DB, healthcheck on every service, DATABASE_URL with an in-network default, playwright.config reads PLAYWRIGHT_BASE_URL. A non-isolable compose fails the verify e2e node inside a worktree. finish/delete tear down with --rmi local -v (--keep-volumes drops -v on finish); worktree remove of a morph-task/* branch with -v, of morph/{f} without. An app whose build is expensive in the Docker VM runs as a host process via e2e.hostServices (compose keeps only the dependencies; ports from the block). Cloud DB credentials go in e2e.auth.envFile, never in .morph/worktree.env. A compose that reads a port by ANOTHER name (PG_PORT) is not fed by the block: declare it in config.json e2e.portEnvNames ({\"postgres\": \"PG_PORT\"}) and the harness exports it with the same value in worktree.env, the compose env and the hook."
     },
     {
       "id": "infrastructure-neon-pgrag",