@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/framework/hooks/claude-code/core/worktree-remove.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * worktree-remove.js — WorktreeRemove hook
+ *
+ * Event: WorktreeRemove (Claude Code's own cleanup of a tree it created via
+ * `claude -w` / EnterWorktree / Agent isolation). Input carries
+ * `worktree_path` (absolute). No decision control, output ignored — this hook
+ * ALWAYS exits 0.
+ *
+ * Why it exists: Claude Code's native removal is a raw `git worktree remove`,
+ * which FOLLOWS the infra junctions the WorktreeCreate hook put in that tree
+ * and empties the primary root's `.claude/` and `.morph/framework/`. This
+ * hook routes the removal through `morph-spec worktree remove --target
+ * --if-clean` instead: junctions dropped first, PROVE-or-DECLINE, and a tree
+ * holding uncommitted work is left alone (Claude Code's notion of "clean" is
+ * not the user's).
+ *
+ * Secondary net: in headless runs the event was observed NOT to fire; the
+ * PreToolUse guard (block-destructive-worktree-removal) stays the primary
+ * defense. Fail-open everywhere — diagnostics to stderr, never a throw, never
+ * a non-zero exit.
+ */
+
+import { existsSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { dirname, resolve } from 'path';
+import { stateExists } from '../../shared/state-reader.js';
+import { resolveGitCommonDir } from '../../shared/git-paths.js';
+import { runMorphSpec } from '../../shared/morph-cli.js';
+
+const fwd = (p) => String(p).replace(/\\/g, '/');
+
+function primaryRoot(startDir) {
+  try {
+    const out = execFileSync('git', ['worktree', 'list', '--porcelain'], { cwd: startDir, stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+    const first = out.split('\n').find((l) => l.startsWith('worktree '));
+    if (first) return fwd(first.slice('worktree '.length).trim());
+  } catch { /* fall through */ }
+  const common = resolveGitCommonDir(startDir);
+  return common ? fwd(dirname(common)) : null;
+}
+
+/**
+ * @param {object} payload - parsed WorktreeRemove stdin payload ({ cwd, worktree_path })
+ * @returns {Promise<null>} always null — the event ignores output
+ */
+export async function run(payload) {
+  try {
+    const target = payload?.worktree_path;
+    if (!target || !existsSync(target)) return null;
+
+    const start = payload?.cwd || process.env.CLAUDE_PROJECT_DIR || dirname(resolve(target));
+    const root = primaryRoot(start) || primaryRoot(dirname(resolve(target)));
+    if (!root) return null;
+    // Nothing to govern outside a morph project — and never a raw removal
+    // from here either: the tree is simply left for git's own cleanup.
+    if (!stateExists(root)) return null;
+
+    const r = runMorphSpec(['worktree', 'remove', '--target', fwd(resolve(target)), '--if-clean', '--json'], { cwd: root });
+    if (r.unavailable) {
+      process.stderr.write(`worktree-remove: morph-spec CLI not found — "${target}" left in place (remove it with \`morph-spec worktree remove --target\`, never with raw git: it follows the infra junctions out).\n`);
+      return null;
+    }
+    if (!r.ok) {
+      const why = r.json?.error || r.json?.hint || r.stderr?.trim() || `exit ${r.code}`;
+      process.stderr.write(`worktree-remove: "${target}" NOT removed — ${why}\n`);
+    }
+    return null;
+  } catch (err) {
+    process.stderr.write(`worktree-remove: ${err?.message || err}\n`);
+    return null;
+  }
+}
+
+// Standalone tail: output is ignored by this event, so nothing is printed;
+// the exit code is always 0.
+if (!process.env.MORPH_HOOK_CHAINED) {
+  const { readStdin } = await import('../../shared/stdin-reader.js');
+  try { await run(await readStdin()); } catch { /* fail-open */ }
+  process.exit(0);
+}

package/framework/hooks/shared/command-tokens.js

@@ -0,0 +1,23 @@
+/**
+ * command-tokens.js — shell-ish tokenizer shared by the PreToolUse Bash guards.
+ *
+ * Lives in shared/ (not inside a hook) on purpose: every core hook ends in a
+ * standalone tail that reads stdin and exits, so a hook importing a sibling
+ * hook for a helper would fire THAT tail in its own process — consuming the
+ * payload and exiting before the importer ever ran. block-raw-worktree-add
+ * and block-destructive-worktree-removal both read paths off these tokens,
+ * so they agree on what a quoted path is.
+ */
+
+/**
+ * Split a shell-ish command into tokens, honoring single and double quotes.
+ * @param {string} command
+ * @returns {string[]}
+ */
+export function tokenize(command) {
+  const tokens = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let m;
+  while ((m = re.exec(String(command || ''))) !== null) tokens.push(m[1] ?? m[2] ?? m[3]);
+  return tokens;
+}

package/framework/hooks/shared/git-paths.js

@@ -58,6 +58,31 @@ function findDotGit(startDir) {
   }
 }
 
+/**
+ * Is `startDir` inside a LINKED (secondary) worktree?
+ *
+ * Same on-disk fact `resolveGitCommonDir` reads: git represents a linked
+ * worktree's `.git` as a FILE holding a `gitdir:` pointer, and a primary
+ * checkout's `.git` as a DIRECTORY. The e2e isolation rule keys on this —
+ * a compose that cannot be isolated is a hard failure only where a second
+ * stack could actually collide with the primary's (see e2e-check.js
+ * `decideIsolation`).
+ *
+ * Fail-open: outside any repo, or on an unreadable path, answers `false` —
+ * the lenient direction (warn instead of fail).
+ *
+ * @param {string} startDir
+ * @returns {boolean}
+ */
+export function isSecondaryWorktree(startDir) {
+  try {
+    const found = findDotGit(startDir);
+    return Boolean(found && !found.isDirectory);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Resolve the git COMMON dir for `startDir` — pure filesystem, no subprocess.
  * Always returns an absolute path (unlike `git rev-parse --git-common-dir`,

package/framework/hooks/shared/hook-response.js

@@ -122,3 +122,20 @@ export async function runStandalone(run) {
   }
   process.exit(0);
 }
+
+/**
+ * Pure builder for a PreToolUse rewrite: Claude Code runs the tool with
+ * `updatedInput` in place of the original `tool_input`, and the decision is
+ * an explicit `allow` (a rewrite without a decision is ignored). Use it ONLY
+ * when the hook actually changed something — an unconditional `allow` would
+ * skip the permission prompt for every call it touches.
+ *
+ * @param {object} updatedInput - the full replacement tool_input
+ * @param {string} eventName - 'PreToolUse'
+ * @param {string} [context] - optional additionalContext (what was changed)
+ */
+export function updatedInputResult(updatedInput, eventName, context) {
+  const out = { hookEventName: eventName, permissionDecision: 'allow', updatedInput };
+  if (context) out.additionalContext = context;
+  return { hookSpecificOutput: out };
+}

package/framework/hooks/shared/morph-cli.js

@@ -0,0 +1,134 @@
+/**
+ * morph-cli.js — run the morph-spec CLI from inside a hook.
+ *
+ * Hooks are installed STANDALONE into `.morph/framework/hooks/` and may never
+ * import from `src/`; the only way for a hook to reuse a CLI command (the
+ * WorktreeCreate hook needs `worktree setup`/`provision`, WorktreeRemove needs
+ * `worktree remove --if-clean`) is to spawn the CLI as a subprocess. This
+ * module is the ONE place that knows how to find it.
+ *
+ * Resolution order:
+ *   1. `MORPH_SPEC_BIN` — an explicit command, possibly with leading args and
+ *      quoted paths (`node "R:/my repo/bin/morph-spec.js"`). What tests and a
+ *      framework checkout use.
+ *   2. `morph-spec` on PATH — the npm-installed bin. On win32 the shim is
+ *      `morph-spec.cmd`, which Node refuses to spawn without a shell, so it is
+ *      located by scanning PATH ourselves and then run through the shell with
+ *      each arg quoted; on POSIX a plain `shell:false` spawn.
+ *   3. `npx --no-install morph-spec` — a project-local dependency.
+ *
+ * ENOENT (or the shell's "not recognized"/"could not determine executable")
+ * everywhere → `{ unavailable: true }`, never a throw: the caller decides what
+ * degraded behavior looks like.
+ *
+ * `json` is the LAST line of stdout that parses as a JSON object (the CLI's
+ * commands print exactly one JSON line; anything a stray console.log adds
+ * before it is skipped), or null.
+ */
+
+import { spawnSync } from 'child_process';
+import { existsSync } from 'fs';
+import { delimiter, join } from 'path';
+
+/** Split a command string into argv, honoring single and double quotes. */
+function splitCommand(command) {
+  const tokens = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let m;
+  while ((m = re.exec(command)) !== null) tokens.push(m[1] ?? m[2] ?? m[3]);
+  return tokens;
+}
+
+/** Quote one argument for cmd.exe (the only shell path this module uses). */
+function quoteForCmd(arg) {
+  if (arg === '') return '""';
+  if (!/[\s"&|<>^()]/.test(arg)) return arg;
+  return `"${arg.replace(/"/g, '""')}"`;
+}
+
+/** First PATH entry holding `file`, or null. */
+function findOnPath(file, env) {
+  const raw = env.PATH || env.Path || env.path || '';
+  for (const dir of raw.split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, file);
+    try { if (existsSync(candidate)) return candidate; } catch { /* unreadable entry */ }
+  }
+  return null;
+}
+
+/** Last stdout line that parses as a JSON object, or null. */
+export function lastJsonLine(stdout) {
+  const lines = String(stdout || '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i].startsWith('{')) continue;
+    try {
+      const parsed = JSON.parse(lines[i]);
+      if (parsed && typeof parsed === 'object') return parsed;
+    } catch { /* not this line */ }
+  }
+  return null;
+}
+
+/**
+ * The candidates to try, in order. Each is `{ file, args, shell }`.
+ * @param {NodeJS.ProcessEnv} env
+ */
+function candidates(env) {
+  const list = [];
+  const explicit = env.MORPH_SPEC_BIN && splitCommand(env.MORPH_SPEC_BIN);
+  if (explicit && explicit.length) {
+    list.push({ file: explicit[0], args: explicit.slice(1), shell: false, kind: 'env' });
+  }
+  if (process.platform === 'win32') {
+    const cmd = findOnPath('morph-spec.cmd', env);
+    if (cmd) list.push({ file: cmd, args: [], shell: true, kind: 'path' });
+    const npx = findOnPath('npx.cmd', env);
+    if (npx) list.push({ file: npx, args: ['--no-install', 'morph-spec'], shell: true, kind: 'npx' });
+  } else {
+    list.push({ file: 'morph-spec', args: [], shell: false, kind: 'path' });
+    list.push({ file: 'npx', args: ['--no-install', 'morph-spec'], shell: false, kind: 'npx' });
+  }
+  return list;
+}
+
+const NOT_FOUND_RE = /not recognized as an internal or external command|could not determine executable to run|command not found|ENOENT/i;
+
+/**
+ * Run `morph-spec <args>` and return its result.
+ *
+ * @param {string[]} args - CLI argv after the program name
+ * @param {{ cwd?: string, timeoutMs?: number, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ ok: boolean, code: number|null, stdout: string, stderr: string, json: object|null, unavailable: boolean }}
+ */
+export function runMorphSpec(args, { cwd, timeoutMs = 120000, env } = {}) {
+  const runEnv = env || process.env;
+  const argv = Array.isArray(args) ? args.map(String) : [];
+
+  for (const cand of candidates(runEnv)) {
+    let r;
+    try {
+      const full = [...cand.args, ...argv];
+      r = cand.shell
+        ? spawnSync(quoteForCmd(cand.file), full.map(quoteForCmd), { cwd, env: runEnv, encoding: 'utf8', timeout: timeoutMs, shell: true, stdio: ['ignore', 'pipe', 'pipe'] })
+        : spawnSync(cand.file, full, { cwd, env: runEnv, encoding: 'utf8', timeout: timeoutMs, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      if (err?.code === 'ENOENT') continue;
+      return { ok: false, code: null, stdout: '', stderr: String(err?.message || err), json: null, unavailable: false };
+    }
+    if (r.error) {
+      if (r.error.code === 'ENOENT') continue;
+      return { ok: false, code: null, stdout: r.stdout || '', stderr: String(r.error.message || r.error), json: null, unavailable: false };
+    }
+    const stdout = r.stdout || '';
+    const stderr = r.stderr || '';
+    // The npx/shell paths cannot surface ENOENT: the shell (or npx itself)
+    // reports "not found" as a non-zero exit with a message. Only those two
+    // kinds are read that way — a real morph-spec failure is never mistaken
+    // for absence.
+    if (cand.kind !== 'env' && r.status !== 0 && !stdout.trim() && NOT_FOUND_RE.test(stderr)) continue;
+    return { ok: r.status === 0, code: r.status, stdout, stderr, json: lastJsonLine(stdout), unavailable: false };
+  }
+
+  return { ok: false, code: null, stdout: '', stderr: 'morph-spec CLI not found (MORPH_SPEC_BIN, PATH, npx)', json: null, unavailable: true };
+}

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

@@ -17,7 +17,7 @@ stacks:
 @.morph/framework/standards/ai-agents/providers/model-registry.md
 @.morph/framework/standards/ai-agents/structured-output.md
 @.morph/framework/standards/ai-agents/multi-agent-patterns.md
-@.morph/framework/standards/ai-agents/prompts-in-db.md
+@.morph/framework/standards/ai-agents/prompt-sources.md
 @.morph/framework/standards/ai-agents/rag-custom-pgvector.md
 @.morph/framework/standards/ai-agents/middleware-patterns.md
 @.morph/framework/standards/ai-agents/observability-patterns.md
@@ -34,7 +34,9 @@ stacks:
 | Standard | Carregue quando a feature envolve |
 |----------|-----------------------------------|
 | `ai-agents/modalities-vision.md` | imagem → texto (OCR, análise de documento, visão) |
-| `ai-agents/modalities-image-gen.md` | texto → imagem (geração de mockups, posts, assets) |
+| `ai-agents/modalities-image-gen.md` | gerar/editar imagem em runtime: catálogo, marketing, variação de produto — aliases pinados, custo por chamada, deprecações |
+| `ai-agents/media-video.md` | gerar vídeo em runtime: Veo via `Google.GenAI`, provedores só-HTTP, custo por segundo, o arquivo que expira |
+| `ai-agents/media-pipeline.md` | **qualquer** feature que gere mídia: a regra dura (nunca no turno de conversa), estados, revisão humana, proveniência, marcação (AI Act art. 50) |
 | `ai-agents/modalities-speech-to-text.md` | áudio → texto (transcrição, legendagem) |
 | `ai-agents/modalities-text-to-speech.md` | texto → áudio (síntese de voz) |
 | `ai-agents/batching.md` | processar N prompts independentes em lote (Batch API) |
@@ -43,4 +45,14 @@ stacks:
 | `ai-agents/context-providers.md` | injeção dinâmica de contexto (`AIContextProvider`) |
 | `ai-agents/mcp-tools.md` | agente MAF consome um MCP server externo |
 | `ai-agents/mcp-server.md` | projeto expõe capacidades como MCP server |
+| `ai-agents/agent-archetypes.md` | escolher a FORMA do agente na fase de plano (conversa com fases, one-shot em lote, visão + structured output) |
+| `ai-agents/agent-spec.md` | o agente como DADO — um `AgentSpec` imutável por agente, catálogo e defaults |
+| `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/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 |
+| `ai-agents/durable-workflows-hitl.md` | workflow durável e human-in-the-loop — checkpoint, `RequestPort`, aprovação de tool |
+| `ai-agents/vector-data-extensions.md` | abstração `Microsoft.Extensions.VectorData` e conectores (pgvector, ingestão) |
 | `integration/mcp/mcp-tools.md` | integração MCP cross-domain (fora do escopo MAF) |

package/framework/rules/infrastructure-standards.md

@@ -11,6 +11,8 @@ stacks:
 # Infrastructure Standards
 
 @.morph/framework/standards/infrastructure/docker/coolify-deploy.md
+@.morph/framework/standards/infrastructure/docker/local-compose-isolation.md
+@.morph/framework/standards/infrastructure/docker/local-compose-isolation.md
 
 ## Infrastructure Templates
 
@@ -18,7 +20,7 @@ stacks:
 |----------|------|---------|
 | .NET API Dockerfile | `.morph/framework/templates/infrastructure/docker/dockerfile-api.dockerfile` | Multi-stage .NET |
 | Next.js Dockerfile | `.morph/framework/templates/infrastructure/docker/dockerfile-web.dockerfile` | Multi-stage Next.js |
-| Docker Compose | `.morph/framework/templates/infrastructure/docker/docker-compose.template.yml` | Local dev env |
+| Docker Compose | `.morph/framework/templates/infrastructure/docker/docker-compose.template.yml` | Local dev env — one isolated stack per worktree (ports from the block, no `container_name`) |
 | Coolify Config | `.morph/framework/templates/infrastructure/docker/coolify.template.json` | Deployment config |
 | .NET Build CI | `.morph/framework/templates/infrastructure/github/workflows/dotnet-build.yml.hbs` | CI workflow |
 | Docker Push CI | `.morph/framework/templates/infrastructure/github/workflows/docker-build-push.yml.hbs` | Build & push |

package/framework/schemas/ai-pin.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://polymorphism.com.br/morph-spec/schemas/ai-pin.schema.json",
+  "title": "morph-spec AI package pin",
+  "description": "Shape of framework/ai-pin.json — the single source of truth for the AI package versions the framework commits to. Written by a human after checking api.nuget.org; read by scripts/generate-ai-pin-props.js (Central Package Management + global.json) and by src/lib/standards/verified-against.js (age of ai-agents standards against pinnedAt). Every version is exact SemVer: a range here would restore floating versions in the generated .props, which is the defect this file exists to remove.",
+  "type": "object",
+  "required": ["pinnedAt", "source", "targetFramework", "sdk", "packages", "toolchain"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Relative path to this schema, so an editor validates the pin while it is edited."
+    },
+    "pinnedAt": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date on which a human checked these versions against the registry. It is the anchor of the ai-agents freshness window — NOT derived from `published`: `published` is a registry fact, `pinnedAt` is the framework's commitment. A date in the future is a pin error, never a fresh standard."
+    },
+    "source": {
+      "type": "string",
+      "pattern": "^https://",
+      "description": "The registry endpoint the versions were read from, so the check is reproducible."
+    },
+    "targetFramework": {
+      "type": "string",
+      "pattern": "^net\\d+\\.\\d+$",
+      "description": "TFM the kit compiles against — the TFM the pinned Microsoft.Agents.AI declares."
+    },
+    "sdk": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "SDK band written into the kit's global.json and read by actions/setup-dotnet."
+    },
+    "packages": {
+      "type": "object",
+      "description": "The AI packages the framework commits to. The SET is closed HERE, by `required` plus `maxProperties` — issue #92 pinned five, and issue #97 added the three Evaluation packages that make `verify` able to run evals from a committed response cache. `patternProperties` still carries the per-entry SHAPE, because JSON Schema cannot name a closed set of keys and repeat their shape without writing it once per key; test/framework/ai-pin.test.js reads THIS `required` list rather than a literal of its own, so the pin and its ruler can never name different sets.",
+      "required": [
+        "Microsoft.Agents.AI",
+        "Microsoft.Extensions.AI",
+        "OpenAI",
+        "Google.GenAI",
+        "ModelContextProtocol",
+        "Microsoft.Extensions.AI.Evaluation",
+        "Microsoft.Extensions.AI.Evaluation.Quality",
+        "Microsoft.Extensions.AI.Evaluation.Reporting"
+      ],
+      "minProperties": 8,
+      "maxProperties": 8,
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[A-Za-z0-9_.-]+$": {
+          "type": "object",
+          "required": ["version", "published", "role"],
+          "additionalProperties": false,
+          "properties": {
+            "version": {
+              "type": "string",
+              "pattern": "^\\d+\\.\\d+\\.\\d+$",
+              "description": "Exact SemVer. No range, no wildcard, no floating version."
+            },
+            "published": {
+              "type": "string",
+              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+              "description": "ISO publication date of that exact version in the registry."
+            },
+            "role": {
+              "type": "string",
+              "pattern": "^[a-z0-9-]+$",
+              "description": "Human-readable label (maf-core, provider, mcp, ...). Documentation, not code semantics."
+            }
+          }
+        }
+      }
+    },
+    "toolchain": {
+      "type": "object",
+      "description": "Build/test packages. They live in the SAME file because the generator writes a single Directory.Packages.props; splitting them would produce two version files and the very second-truth problem the pin removes.",
+      "minProperties": 3,
+      "maxProperties": 3,
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[A-Za-z0-9_.-]+$": {
+          "type": "object",
+          "required": ["version"],
+          "additionalProperties": false,
+          "properties": {
+            "version": {
+              "type": "string",
+              "pattern": "^\\d+\\.\\d+\\.\\d+$",
+              "description": "Exact SemVer, same rule as `packages`."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/framework/schemas/config.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MORPH-SPEC .morph/config/config.json",
+  "description": "Describes ONLY project.tests[] — the plural declaration of the project's test suites. 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 authority at runtime is validateTestNodes() in src/lib/tasks/test-nodes.js: a schema nothing calls is decoration.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "project": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "tests": {
+          "type": "array",
+          "description": "One entry per test suite. Absent (not empty) means the four-step fallback of resolveTestPlan() decides — every project created before this key existed keeps working. An empty array is an explicit declaration of 'no test suites'.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "command"],
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]*$",
+                "description": "Unique within the array. What `verify --filter` matches and the key of nodes.tests.runs[]. A duplicate id is a config error, not a silent tie."
+              },
+              "command": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Literal command, executed by the shell from `cwd`."
+              },
+              "cwd": {
+                "type": "string",
+                "minLength": 1,
+                "default": ".",
+                "description": "Relative to the project root. A path that resolves outside the root is refused: it addresses another tree."
+              },
+              "runner": {
+                "type": "string",
+                "enum": ["dotnet", "vitest", "jest", "node-test", "playwright", "none", "evals"],
+                "description": "Chooses the test-count extractor and whether a prebuild applies. Inferred from `command` when omitted; `none` means the count is UNKNOWN, never zero. `evals` is the ONLY value that is never inferred - it is a declaration that this suite reads a committed response cache, and it REQUIRES the `evals` block below."
+              },
+              "expectedCount": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Recorded baseline. Written ONLY by `morph-spec verify --record-baseline`, from a green run — never typed by hand."
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Ceiling for this node. Exists because the derived default (120s x chained projects) is shaped for `dotnet test` and is hostile to a Node suite that takes twelve minutes."
+              },
+              "build": {
+                "type": "array",
+                "items": { "type": "string", "minLength": 1 },
+                "description": "Test projects to compile before running (runner 'dotnet' only). Without it, `--no-build` in the command has no fresh binary behind it."
+              },
+              "e2e": {
+                "type": "boolean",
+                "default": false,
+                "description": "Requires the application stack to be up. Runs at feature scope only, never in the per-task loop."
+              },
+              "linuxImage": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Overrides the container image used by `verify --linux` for this node."
+              },
+              "evals": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["cachePath"],
+                "description": "Required by, and only valid for, runner evals. Declared on any other runner it would be a key the verifier silently ignores - the same fail-open shape as a typo in tests[].",
+                "properties": {
+                  "cachePath": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Root of the response-cache tree, relative to the project root, and COMMITTED. A path that resolves outside the root is refused, same rule as `cwd`. No default: a silent one would create a cache tree somewhere nobody declared."
+                  },
+                  "datasetPath": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Root of the versioned dataset, laid out as {agent}/{tenant}/{scenario}.json. Defaults to `eval-datasets` beside cachePath."
+                  },
+                  "envFile": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "GITIGNORED file holding the provider credential, read ONLY by --refresh-cache. Same pattern as e2e.auth.envFile; a credential never travels in the committed config. Defaults to `.env.evals`."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "evals": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Project-level eval settings, distinct from the per-node block above: this one describes the PROJECT (which paths count as prompt or model), not one suite.",
+          "properties": {
+            "watch": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "description": "Globs that mean 'this is a prompt or a model'. Matched against what the feature changed (git diff plus untracked) to decide whether Gate 3 should pause for a missing eval. Absent means the project declares no such paths - reported as a reason of its own, distinct from 'declared and nothing was touched'."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/framework/schemas/feature.schema.json

@@ -107,7 +107,8 @@
               "build": { "type": "string", "enum": ["pass", "fail", "skip"] },
               "tests": { "type": "string", "enum": ["pass", "fail", "skip"] },
               "validators": { "type": "string", "enum": ["pass", "fail", "skip"] },
-              "e2e": { "type": "string", "enum": ["pass", "fail", "skip"], "description": "Docker bring-up + Playwright specs against the running stack. Absent on entries written before the node existed — which is why it is NOT in `required`." }
+              "e2e": { "type": "string", "enum": ["pass", "fail", "skip"], "description": "Docker bring-up + Playwright specs against the running stack. Absent on entries written before the node existed — which is why it is NOT in `required`." },
+              "evals": { "type": ["string", "null"], "enum": ["pass", "fail", "skip", null], "description": "Eval suites, pulled out of the tests rollup. Written by the SAME function that writes the singular stamp (nodeStatuses in verify.js): the two shapes must stay identical, or a stamp would omit what the history records. null means the project declares no eval node at all — distinct from skip, which means it declares one and this run did not execute it. Absent on entries written before the field existed, which is why it is NOT in required." }
             },
             "additionalProperties": false
           },
@@ -134,7 +135,8 @@
                 "build": { "type": "string", "enum": ["pass", "fail", "skip"] },
                 "tests": { "type": "string", "enum": ["pass", "fail", "skip"] },
                 "validators": { "type": "string", "enum": ["pass", "fail", "skip"] },
-                "e2e": { "type": "string", "enum": ["pass", "fail", "skip"], "description": "Docker bring-up + Playwright specs against the running stack. Absent on entries written before the node existed — which is why it is NOT in `required`." }
+                "e2e": { "type": "string", "enum": ["pass", "fail", "skip"], "description": "Docker bring-up + Playwright specs against the running stack. Absent on entries written before the node existed — which is why it is NOT in `required`." },
+              "evals": { "type": ["string", "null"], "enum": ["pass", "fail", "skip", null], "description": "Eval suites, pulled out of the tests rollup. Written by the SAME function that writes the singular stamp (nodeStatuses in verify.js): the two shapes must stay identical, or a stamp would omit what the history records. null means the project declares no eval node at all — distinct from skip, which means it declares one and this run did not execute it. Absent on entries written before the field existed, which is why it is NOT in required." }
               },
               "additionalProperties": false
             },
@@ -149,13 +151,30 @@
     },
     "verification": {
       "type": "object",
-      "description": "The single latest deterministic verify stamp (any scope), written ONLY by `morph-spec verify`. Distinct from `verifications`/`taskVerifications` above (per-scope history with attempts/nodes): this is overwritten by every verify call regardless of scope, carrying just enough to correlate a pass/fail with the exact commit it covers. Primary consumer: `morph-spec gate-check`, which feeds `status` to shouldPauseGate as `verificationStatus` — a red verify pauses the gate (risk-detector.js). The remaining fields (sha/ts/scope, and the derived `verificationStale`) are audit context, not pause rules.",
+      "description": "The single latest deterministic verify stamp (any scope), written ONLY by `morph-spec verify`. Distinct from `verifications`/`taskVerifications` above (per-scope history with attempts/nodes): this is overwritten by every verify call regardless of scope, carrying just enough to correlate a pass/fail with the exact commit it covers. Primary consumer: `morph-spec gate-check`, which feeds `status` to shouldPauseGate as `verificationStatus` — a red verify pauses the gate (risk-detector.js) — and `nodes.e2e`/`e2eReason` as `e2eStatus`/`e2eReason`, the pair that decides whether an e2e SKIP is a recorded dispensation or an absence of proof (a skip never reddens `status`, so the rollup alone is blind to it). `scope` is the third pause input: a dispensation only counts from a feature-scoped stamp (see the field below). The rest (sha/ts, and the derived `verificationStale`) is audit context.",
       "required": ["status", "sha", "ts", "scope"],
       "properties": {
         "status": { "type": "string", "enum": ["pass", "fail"] },
+        "nodes": {
+          "type": "object",
+          "description": "Per-node status of the verify that wrote this stamp. NOT in `required`: stamps written before the field existed carry only the rollup. Same values as `verifications.feature.nodes`, repeated here because gate-check reads the stamp and nothing else.",
+          "properties": {
+            "build": { "type": "string", "enum": ["pass", "fail", "skip"] },
+            "tests": { "type": "string", "enum": ["pass", "fail", "skip"] },
+            "validators": { "type": "string", "enum": ["pass", "fail", "skip"] },
+            "e2e": { "type": "string", "enum": ["pass", "fail", "skip"] },
+            "evals": {
+              "type": ["string", "null"],
+              "enum": ["pass", "fail", "skip", null],
+              "description": "Status of the `runner: \"evals\"` entries of nodes.tests.runs[], pulled out of the rollup. The rollup cannot answer what Gate 3 asks: a red eval and a red unit test both read as tests:fail, and an eval SKIPPED at task scope leaves the rollup green. null means this project declares NO eval node - distinct from 'skip', which means it declares one and this run did not execute it; risk-detector.js pauses on the two for different reasons because they call for different actions. Absent on stamps written before this field existed."
+            }
+          },
+          "additionalProperties": false
+        },
+        "e2eReason": { "type": ["string", "null"], "description": "The LITERAL reason the e2e node skipped (e2e-check.js's own wording), or null when it did not skip. risk-detector.js's classifyE2eSkip() reads it: 'project does not containerize' / 'does not touch runtime' are legitimate dispensations and pass; 'docker is not available' / 'requested' (--skip-e2e) / anything unclassifiable — null included — are an absence of proof and pause Gate 3. A skip recorded WITHOUT a reason is refused on purpose: a nameless dispensation is a silent no-op." },
         "sha": { "type": ["string", "null"], "description": "HEAD commit SHA at verify time (git rev-parse HEAD); null when not in a git repo or no commits yet." },
         "ts": { "type": "string", "format": "date-time", "description": "Server-side timestamp, same instant as the corresponding verifications/taskVerifications entry's updatedAt." },
-        "scope": { "type": "string", "description": "'feature', or 'task:<id>' for a task-scoped verify." }
+        "scope": { "type": "string", "description": "'feature', or 'task:<id>' for a task-scoped verify. READ BY THE GATE, not just audit: this stamp is singular and any verify overwrites it, so a 'task:<id>' value at ship time means the last verify was NOT the feature's. risk-detector.js therefore accepts an e2e dispensation ('project'/'scope' in e2eReason) only from scope === 'feature' — a `morph-spec verify {f} {task}` of a task whose group does not touch runtime stamps exactly the legitimate-sounding reason that would otherwise buy Gate 3 for the whole feature (the last task of a feature is typically group: docs). Absent/unknown falls on the safe side, like an unclassifiable reason." }
       },
       "additionalProperties": false
     },

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.33.0"
+cliVersion: "8.35.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.33.0"
+cliVersion: "8.35.0"
 stacks:
   - umbraco
 ---