@polymorphism-tech/morph-spec 10.5.2 → 10.5.3

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 10.5.2  
+**Version:** 10.5.3  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -376,4 +376,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v10.5.2 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v10.5.3 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "10.5.2",
+  "version": "10.5.3",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -174,4 +174,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v10.5.2 by Polymorphism Tech*
+*morph-spec v10.5.3 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -89,4 +89,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v10.5.2 by Polymorphism Tech*
+*morph-spec v10.5.3 by Polymorphism Tech*

package/framework/docs/CLI.md

@@ -418,7 +418,7 @@ Isolamento entre worktrees: `COMPOSE_PROJECT_NAME=morph-{feature}` separa os con
 
 **Vigia durante o `verify --detach`** (`heavy.criticalFreeMemGb`, 1, `0` desliga): o piso julga o começo de um nó; o vigia, um processo próprio, lê a RAM a cada 10 s durante a rodada. Abaixo do valor, tenta o reclaim na 1ª leitura; seis leituras seguidas abaixo param **só aquela rodada**, com a árvore de processos dela: exit 3, sem stamp, nunca vermelho.
 
-**Máquina responsiva** (`heavy.yieldToUser`, ligado): cada rodada usa só a sua parte dos núcleos (`núcleos / heavy.slots`, mínimo 2) por `DOTNET_PROCESSOR_COUNT` (build e testes) e `--maxWorkers` no Vitest. Prioridade baixa fica de fora de propósito: numa máquina ocupada, o processo perde a disputa e falha pelo próprio limite de tempo. O preço é rodada um pouco mais lenta. `DOTNET_PROCESSOR_COUNT` já definido no ambiente vence. O hook `heavy-gate` toma vaga, mas não muda o comando do Bash: lá isso não se aplica.
+**Máquina responsiva** (`heavy.yieldToUser`, ligado): um quarto dos núcleos fica de fora (mínimo 2); a cada nó, a rodada sozinha usa o resto, e com outra na fila usa `resto / heavy.slots`, por `DOTNET_PROCESSOR_COUNT` (build e testes), `VITEST_MAX_FORKS`, `VITEST_MAX_THREADS` e `--maxWorkers`. Numa máquina de 16 núcleos: 12 sozinha, 6 acompanhada. Medido em duas suítes reais do Vitest: sem custo de tempo acompanhada, 4% sozinha, e metade da latência para abrir um processo. O comando solto, fora da fila, também respeita: `init` e `update` gravam a parte acompanhada em `env` de `.claude/settings.local.json`, sem sobrescrever valor que já esteja lá. Prioridade baixa fica de fora de propósito: numa máquina ocupada, o processo perde a disputa e falha pelo próprio limite de tempo.
 
 **Fila que não recusa** (`heavy.detachedWaitMinutes`, 60): fora de um shell não há timeout de chamada, então o `verify --detach` espera a vez em vez de sair com exit 3 em `waitTimeoutSec`. `MORPH_HEAVY_WAIT_SEC` sobrepõe a espera.
 

package/framework/hooks/shared/background-spawn.js

@@ -0,0 +1,20 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const HOST = fileURLToPath(import.meta.url);
+
+/**
+ * Arguments for a detached node process. On Windows `detached` means no console at all and
+ * `windowsHide` is ignored, so every console child opens a visible window; a child that is not
+ * detached has a hidden console but dies with its node parent (libuv job). The host holds both
+ * ends: detached itself, it stays alive for a child whose hidden console all descendants inherit.
+ */
+export function backgroundArgs(args, platform = process.platform) {
+  return platform === 'win32' ? [HOST, ...args] : args;
+}
+
+if (process.argv[1] === HOST) {
+  const child = spawn(process.execPath, process.argv.slice(2), { stdio: 'inherit', windowsHide: true });
+  child.on('error', () => process.exit(1));
+  child.on('exit', (code) => process.exit(code ?? 1));
+}

package/framework/hooks/shared/graph-refresh.js

@@ -12,6 +12,7 @@ import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { readPrimaryHead, resolveGitCommonDir, workTreeTop } from './git-paths.js';
 import { findFirstOnPath, quoteForCmd } from './morph-cli.js';
+import { backgroundArgs } from './background-spawn.js';
 import { ensureCommonExclude } from './git-exclude.js';
 import { pidAlive } from './process-alive.js';
 import {
@@ -274,7 +275,7 @@ export function kickGraphRefresh(dir, { spawnFn = spawn, env = process.env } = {
     return { kicked: false, reason: 'graphify-unavailable' };
   }
   try {
-    const child = spawnFn(process.execPath, [WORKER, '--run', root], {
+    const child = spawnFn(process.execPath, backgroundArgs([WORKER, '--run', root]), {
       cwd: resolveGitCommonDir(root), env, detached: true, stdio: 'ignore', windowsHide: true,
     });
     child.on?.('error', () => {});

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

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
+import { availableParallelism } from 'node:os';
 import { join } from 'node:path';
 
 const CONFIG_FILE = join('.morph', 'config', 'config.json');
@@ -22,6 +23,14 @@ export const HEAVY_DEFAULTS = Object.freeze({
 
 export const HEAVY_KINDS = Object.freeze(['unit', 'build', 'e2e']);
 
+export const CPU_SHARE_ENVS = Object.freeze(['DOTNET_PROCESSOR_COUNT', 'VITEST_MAX_FORKS', 'VITEST_MAX_THREADS']);
+
+/** A quarter of the machine stays with the person; what is left goes to one run, or is split by the slots. */
+export function cpuShareOf(slots, { cores = availableParallelism(), alone = false } = {}) {
+  const usable = cores - Math.max(2, Math.floor(cores / 4));
+  return Math.max(2, alone ? usable : Math.floor(usable / slots));
+}
+
 const isBool = (v) => typeof v === 'boolean';
 const isGb = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
 const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);

package/framework/schemas/config.schema.json

@@ -299,7 +299,7 @@
         "yieldToUser": {
           "type": "boolean",
           "default": true,
-          "description": "Heavy runs leave room for what the person is using: each run keeps to its share of the cores (cores / slots) through DOTNET_PROCESSOR_COUNT and vitest --maxWorkers. Priority is left alone on purpose: below normal, a process starves on a busy machine and fails by its own timeouts."
+          "description": "Heavy runs leave room for what the person is using: a quarter of the cores stays out, a run alone takes the rest and a run with company takes rest / slots, through DOTNET_PROCESSOR_COUNT, VITEST_MAX_FORKS, VITEST_MAX_THREADS and --maxWorkers. `init` and `update` write the shared value to `env` in .claude/settings.local.json for what runs outside the queue. Priority is left alone on purpose: below normal, a process starves on a busy machine and fails by its own timeouts."
         },
         "criticalFreeMemGb": {
           "type": "number",

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: "10.5.2"
+cliVersion: "10.5.3"
 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: "10.5.2"
+cliVersion: "10.5.3"
 stacks:
   - umbraco
 ---

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

@@ -4,7 +4,7 @@ description: Implementa o plano aprovado de uma feature morph-spec inteiro nesta
 version: core
 when_to_use: Use com o gate do plano aprovado ("/morph-apply {feature}", "implementar feature"), em "/morph-review {feature}" (entra no §5), em "/morph-hotfix {feature}" ou incidente de produção (references/hotfix.md), ou quando `morph-spec next` mandar implement, verify, fix, review ou finish
 user-invocable: true
-cliVersion: "10.5.2"
+cliVersion: "10.5.3"
 ---
 
 # morph-apply

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

@@ -4,7 +4,7 @@ description: Leva um pedido ou o link de uma issue ao plano aprovado — roteia
 version: core
 when_to_use: Use quando uma feature, bug ou chore começar ("/morph-plan {feature}", "/morph-plan <link da issue>", "vamos planejar X"), ou ao retomar uma feature cujo gate plan ainda não foi aprovado
 user-invocable: true
-cliVersion: "10.5.2"
+cliVersion: "10.5.3"
 ---
 
 # morph-plan

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "10.5.2",
+  "version": "10.5.3",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/lib/heavy/gate.js

@@ -1,7 +1,8 @@
-import { availableParallelism, freemem } from 'node:os';
-import { minFreeMemFor, readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
+import { freemem } from 'node:os';
+import { CPU_SHARE_ENVS, cpuShareOf, minFreeMemFor, readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
 import { heavyClass } from '../../../framework/hooks/shared/heavy-command.js';
-import { GB } from '../../../framework/hooks/shared/heavy-holders.js';
+import { GB, readHolders } from '../../../framework/hooks/shared/heavy-holders.js';
+import { pidAlive } from '../../../framework/hooks/shared/process-alive.js';
 import {
   acquireHeavy, awaitFreeMemory, describeBusy, enterVerifySuite, heavyDir, isVerifySuite, releaseHeavy, updateLease,
 } from '../../../framework/hooks/shared/heavy-slots.js';
@@ -27,9 +28,6 @@ export class HeavyBusyError extends Error {
 
 const NODE_REUSE_ENV = 'MSBUILDDISABLENODEREUSE';
 const LEASE_ENV = 'MORPH_HEAVY_LEASE';
-const CPU_ENV = 'DOTNET_PROCESSOR_COUNT';
-
-export const cpuShareOf = (slots, cores = availableParallelism()) => Math.max(2, Math.floor(cores / slots));
 
 export function createHeavyGate({
   projectPath, label = 'verify', feature = null, config = readHeavyConfig(projectPath),
@@ -43,8 +41,18 @@ export function createHeavyGate({
   let exitHandler = null;
   let saved = null;
   let reclaimed = false;
+  let cpuShare = null;
   const politeRun = config.enabled && config.yieldToUser;
 
+  // Judged at each node: a run alone takes nearly the machine, and steps back once another one is in.
+  const applyCpuShare = () => {
+    if (!politeRun) return;
+    const { holders = readHolders } = deps;
+    const live = holders(heavyDir(env), { now: Date.now, isAlive: pidAlive, maxHoldMs: config.maxHoldMinutes * 60_000 });
+    cpuShare = cpuShareOf(config.slots, { alone: !live.some((h) => h.pid !== process.pid) });
+    for (const name of CPU_SHARE_ENVS) env[name] = String(cpuShare);
+  };
+
   const reclaimBelow = (floor) => {
     const { freeMem = freemem, reclaim = reclaimUnlessDisabled } = deps;
     if (reclaimed || !config.reclaimIdleMinutes || freeMem() / GB >= floor) return;
@@ -105,7 +113,7 @@ export function createHeavyGate({
   return {
     config,
     get waitedMs() { return waitedMs; },
-    get cpuShare() { return politeRun ? cpuShareOf(config.slots) : null; },
+    get cpuShare() { return cpuShare; },
 
     enter(node, kind = heavyClass(node)) {
       const suite = isVerifySuite({ label, node });
@@ -113,6 +121,7 @@ export function createHeavyGate({
         if (suite && lease && !suiteEntered) awaitSuite();
         raiseFloor(kind);
         updateLease(lease, { node });
+        applyCpuShare();
         return;
       }
       for (const warning of config.warnings ?? []) log(`heavy: ${warning}`);
@@ -143,9 +152,9 @@ export function createHeavyGate({
         waitedMs = result.waitedMs;
       }
 
-      saved = { [NODE_REUSE_ENV]: env[NODE_REUSE_ENV], [LEASE_ENV]: env[LEASE_ENV], [CPU_ENV]: env[CPU_ENV] };
+      saved = Object.fromEntries([NODE_REUSE_ENV, LEASE_ENV, ...CPU_SHARE_ENVS].map((name) => [name, env[name]]));
       if (config.disableNodeReuse) env[NODE_REUSE_ENV] = '1';
-      if (politeRun) env[CPU_ENV] ??= String(cpuShareOf(config.slots));
+      applyCpuShare();
       if (lease) env[LEASE_ENV] = String(process.pid);
       entered = true;
       if (lease) {

package/src/lib/heavy/reclaim.js

@@ -90,7 +90,7 @@ export function reclaimMemory({ projectPath, feature = null, config, env = proce
   if (!config.reclaimIdleMinutes) return { freed: [], containers: [] };
 
   const cachedExec = onceByArgs(exec);
-  const live = holders(config, env, now());
+  const live = holders(config, env, now);
   const held = new Set(live.map((h) => h.feature).filter(Boolean));
   const idleMs = config.reclaimIdleMinutes * 60_000;
 

package/src/lib/verify/detached.js

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
+import { backgroundArgs } from '../../../framework/hooks/shared/background-spawn.js';
 import { heavyDir } from '../../../framework/hooks/shared/heavy-holders.js';
 import { pidAlive } from '../../../framework/hooks/shared/process-alive.js';
 import { treeFingerprint } from '../git/tree-fingerprint.js';
@@ -71,7 +72,8 @@ function spawnStage(stage, { argv, cwd, env, paths, script, spawnFn = spawn }) {
   const out = openSync(paths.out, 'a');
   const err = openSync(paths.err, 'a');
   try {
-    const child = spawnFn(process.execPath, [script, ...argv], {
+    const args = [script, ...argv];
+    const child = spawnFn(process.execPath, stage === 'launch' ? args : backgroundArgs(args), {
       cwd,
       detached: true,
       windowsHide: true,

package/src/utils/hooks-installer.js

@@ -3,6 +3,7 @@ import { readFile } from 'fs/promises';
 import { existsSync, readdirSync } from 'fs';
 import { homedir } from 'os';
 import { realEffects } from '../lib/installers/effects.js';
+import { CPU_SHARE_ENVS, cpuShareOf, readHeavyConfig } from '../../framework/hooks/shared/heavy-config.js';
 
 const HOOKS_VERSION = '3.17.0';
 
@@ -275,6 +276,13 @@ export async function installClaudeHooks(targetPath, { fx = realEffects() } = {}
     settings.plansDirectory = '.morph/plans';
   }
 
+  // What runs outside the queue (a loose `dotnet test`) keeps to a run's share too; a value already here stays.
+  const heavy = readHeavyConfig(targetPath);
+  if (heavy.yieldToUser) {
+    const share = String(cpuShareOf(heavy.slots));
+    settings.env = { ...Object.fromEntries(CPU_SHARE_ENVS.map((name) => [name, share])), ...settings.env };
+  }
+
   settings._morph_managed = settings._morph_managed || {};
   settings._morph_managed.hooks_version = HOOKS_VERSION;
   settings._morph_managed.hooks_installed = [...new Set(MORPH_HOOKS.map(h => h.event))];