@polymorphism-tech/morph-spec 8.34.2 → 8.35.1

package/framework/hooks/shared/e2e-check.js

@@ -322,10 +322,29 @@ export function deleteStamp(gitCommonDir, projectName) {
 /**
  * Does this stack serve the working tree directly?
  *
- * A service that bind-mounts the project into the container reads source from
- * disk on every request, so a rebuild can never make it fresher — it is
- * already serving whatever is on disk. This is the ONE case where reuse is
- * unconditionally safe.
+ * The question is right; the answer used to be wrong. The predicate used to be
+ * "does ANY service mount ANYTHING under cwd" — which a Playwright sidecar
+ * mounting `./e2e` answers yes to. `decideReuse()` then short-circuited BEFORE
+ * the stamp comparison and printed "source is bind-mounted" about a stack whose
+ * application is a compiled image: a true statement about the sidecar, used as
+ * a false statement about the code under test, and the stamp — the only real
+ * proof of freshness — never got a say.
+ *
+ * The honest predicate looks only at services that are BUILT here, because only
+ * those carry code a rebuild could refresh:
+ *
+ *   - no service declares `build:`  → false. Nothing is compiled from this
+ *     tree, so "a rebuild cannot make it fresher" says nothing about it, and
+ *     the stamp decides.
+ *   - EVERY built service mounts the project ROOT → true. Each reads source
+ *     from disk on every request, so a running stack is current by
+ *     construction — the ONE case where reuse is unconditionally safe.
+ *   - anything else → false. One built service serving an image is one service
+ *     that can be stale.
+ *
+ * A subdirectory mount is deliberately not enough: a service that mounts only
+ * `./e2e` still runs whatever was baked into its image. Uncertainty answers
+ * false, which costs one cheap layer-cached rebuild — see bringUpStack().
  *
  * @param {object} composeConfig - parsed `docker compose config --format json`
  * @param {string} cwd
@@ -335,18 +354,46 @@ export function usesBindMount(composeConfig, cwd) {
   const services = composeConfig?.services;
   if (!services || typeof services !== 'object') return false;
 
-  const normalizedCwd = cwd.replace(/\\/g, '/').replace(/\/+$/, '');
-
-  return Object.values(services).some((service) => {
-    const volumes = Array.isArray(service?.volumes) ? service.volumes : [];
-    return volumes.some((vol) => {
-      // Long syntax: { type: 'bind', source: '...' }. Short syntax is a string
-      // "src:dst" that compose has already expanded to an absolute path.
-      const source = typeof vol === 'string' ? vol.split(':')[0] : vol?.source;
-      if (!source) return false;
-      const normalized = String(source).replace(/\\/g, '/').replace(/\/+$/, '');
-      return normalized === normalizedCwd || normalized.startsWith(`${normalizedCwd}/`);
-    });
+  const normalizedCwd = normalizeMountPath(cwd);
+  const built = Object.values(services).filter(
+    (service) => service && service.build !== undefined && service.build !== null,
+  );
+  if (built.length === 0) return false;
+
+  return built.every((service) => mountsProjectRoot(service, normalizedCwd));
+}
+
+/** One spelling per path, so two spellings of the same directory compare equal. */
+function normalizeMountPath(path) {
+  return String(path ?? '')
+    .replace(/\\/g, '/')
+    .replace(/\/+$/, '');
+}
+
+/**
+ * Source half of a short-syntax volume ("src:dst[:mode]").
+ *
+ * Splitting on the FIRST ':' loses on Windows, where compose expands the source
+ * to `C:\path`. The target is always an absolute container path, so anchoring on
+ * the ':' that precedes it is the split that survives both platforms.
+ */
+function shortVolumeSource(spec) {
+  const match = /^(.+):(\/[^:]*)(:[A-Za-z,]+)?$/.exec(spec);
+  return match ? match[1] : null;
+}
+
+/**
+ * Does this service bind-mount the project ROOT? A subdirectory does not count:
+ * only the root makes the whole service read its code from disk.
+ */
+function mountsProjectRoot(service, normalizedCwd) {
+  const volumes = Array.isArray(service?.volumes) ? service.volumes : [];
+  return volumes.some((vol) => {
+    // Long syntax: { type: 'bind', source: '...' }; short syntax is a string.
+    if (typeof vol !== 'string' && vol?.type && vol.type !== 'bind') return false;
+    const source = typeof vol === 'string' ? shortVolumeSource(vol) : vol?.source;
+    if (!source) return false;
+    return normalizeMountPath(source) === normalizedCwd;
   });
 }
 
@@ -513,6 +560,19 @@ export function bringUpStack(
     return { status: 'pass', reused: true, output: '', reason: decision.reason };
   }
 
+  // "Fresh" is a promise about the DATA, not only about the image. Adding
+  // `--build` alone rebuilds the container and leaves the postgres volume
+  // standing, so the next suite talks to the previous run's database — the
+  // stale rows survive the very flag asked to get rid of them. The named
+  // volumes go first, and the stamp goes with them: a stamp that outlives the
+  // stack it described would let the next `up` reuse something that no longer
+  // exists. Teardown is best-effort by construction (tearDownStack never
+  // throws), so a stack that was not up costs nothing here.
+  if (forceFresh) {
+    tearDownStack(cwd, { composeFile, projectName, env, volumes: true }, exec);
+    deleteStamp(gitCommonDir, projectName);
+  }
+
   const upArgs = [...base, 'up', '-d', '--wait'];
   if (decision.rebuild) upArgs.push('--build');
 
@@ -555,7 +615,11 @@ function decideReuse({ cwd, base, env, stamp, status, gitCommonDir, projectName,
   if (!status.up || !status.healthy) return { reuse: false, rebuild: true };
 
   // Bind-mounted source is served from disk, so a running stack is current by
-  // construction — the only unconditionally safe reuse.
+  // construction — the only unconditionally safe reuse. usesBindMount() answers
+  // this for the services that are BUILT here; when it says no, control falls
+  // through to the stamp, which is the real proof. The two reasons below stay
+  // distinct on purpose: whoever reads "reused warm stack" has to be able to
+  // tell which fact bought the reuse.
   const configJson = exec('docker', [...base, 'config', '--format', 'json'], { cwd, env });
   if (configJson.code === 0) {
     try {
@@ -666,13 +730,37 @@ export function loadEnvFile(path) {
  * screen would quietly end up with no e2e at all. Missing auth CONFIG is a
  * planning gap (Gate 2); broken auth at runtime is a real failure.
  *
- * @returns {{ status: 'pass'|'fail'|'skip', reason: string|null }}
+ * The same rule applied one level up is why `warning` exists: a config that
+ * declares `seedCommand` but leaves `mode` absent (or "none") used to return
+ * `skip` on the first line and run nothing at all. The seed was configured, the
+ * code knew how to execute it, and `mode` switched it off without a word — the
+ * silence is what made a working seedCommand look like dead configuration.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.forceSeed] - `--fresh-e2e`: the database was just
+ *   dropped, so a storageState captured against it is a session for rows that
+ *   no longer exist. Refuses the "file exists → reuse" shortcut.
+ * @returns {{ status: 'pass'|'fail'|'skip', reason: string|null, warning?: string }}
  */
-export function prepareAuth(cwd, { config, env, timeout = 60_000 } = {}, exec = defaultExec) {
+export function prepareAuth(
+  cwd,
+  { config, env, timeout = 60_000, forceSeed = false } = {},
+  exec = defaultExec,
+) {
   const auth = config?.e2e?.auth;
   const mode = auth?.mode ?? 'none';
 
   if (mode === 'none') {
+    if (auth?.seedCommand) {
+      const declared = auth.mode == null ? 'absent' : `"${auth.mode}"`;
+      return {
+        status: 'skip',
+        reason: null,
+        warning:
+          `e2e.auth.seedCommand is configured but e2e.auth.mode is ${declared} — ` +
+          'the seed never runs (set e2e.auth.mode to "seed" or "storageState")',
+      };
+    }
     return { status: 'skip', reason: null };
   }
 
@@ -685,10 +773,25 @@ export function prepareAuth(cwd, { config, env, timeout = 60_000 } = {}, exec =
     const statePath = auth.storageStatePath
       ? join(cwd, auth.storageStatePath)
       : null;
-    if (statePath && existsSync(statePath)) {
+    const stateExists = Boolean(statePath && existsSync(statePath));
+
+    // The file's existence is not its freshness. After `--fresh-e2e` dropped
+    // the volumes, a storageState captured against the old database
+    // authenticates a user that is no longer there: every request comes back
+    // 403 and the failure looks like a broken app. forceSeed refuses the
+    // shortcut and re-establishes the session against the new database.
+    if (stateExists && !forceSeed) {
       return { status: 'pass', reason: 'reused stored auth session' };
     }
     if (!auth.seedCommand) {
+      if (stateExists) {
+        // Nothing to refresh it with — reusing is the only option left, and
+        // saying so is the difference between a reuse and a silent one.
+        return {
+          status: 'pass',
+          reason: 'reused stored auth session (no e2e.auth.seedCommand to refresh it)',
+        };
+      }
       return {
         status: 'fail',
         reason:
@@ -715,7 +818,12 @@ export function prepareAuth(cwd, { config, env, timeout = 60_000 } = {}, exec =
       reason: `e2e auth setup failed (${auth.seedCommand}): ${firstLine(result.output)}`,
     };
   }
-  return { status: 'pass', reason: 'auth seeded for the e2e environment' };
+  return {
+    status: 'pass',
+    reason: forceSeed
+      ? 'auth re-seeded against the fresh stack'
+      : 'auth seeded for the e2e environment',
+  };
 }
 
 // ============================================================================
@@ -818,7 +926,12 @@ export function runE2eCheck(cwd, options = {}) {
   }
 
   try {
-    const auth = prepareAuth(cwd, { config, env: composeEnv }, exec);
+    // forceSeed rides on forceFresh: the same flag that dropped the database is
+    // the one that invalidates any session captured against it.
+    const auth = prepareAuth(cwd, { config, env: composeEnv, forceSeed: forceFresh }, exec);
+    // A configured seed that never runs is a finding, not a detail — it travels
+    // to warnings[] so verify turns it into a "[e2e] warning: …" feedback line.
+    if (auth.warning) warnings.push(auth.warning);
     if (auth.status === 'fail') {
       return { status: 'fail', command: null, output: '', reason: auth.reason, warnings };
     }

package/framework/hooks/shared/payload-utils.js

@@ -5,6 +5,7 @@
  * normalizing between Write (content, file_path) and Edit (new_string, old_string, file_path).
  */
 
+import { createHash } from 'crypto';
 import { existsSync } from 'fs';
 import { dirname, join, isAbsolute } from 'path';
 
@@ -165,7 +166,7 @@ const BASH_SIGNATURE_MAX = 120;
 
 /**
  * Build a normalized signature for loop detection.
- * - Edit/Write: "Edit:normalized/file/path"
+ * - Edit/Write: "Edit:normalized/file/path#<sha1[0:8] do conteúdo>" ("Edit:path" sem conteúdo)
  * - Bash: "Bash:<normalized command, truncated>"
  * - Every other tool WITH input: "Tool:<truncated JSON of tool_input>"
  * - No tool_input at all: just the tool name
@@ -201,7 +202,19 @@ export function getCommandSignature(payload) {
 
   if (tool === 'Edit' || tool === 'Write') {
     const path = (input.file_path || input.path || '').replace(/\\/g, '/');
-    return path ? `${tool}:${path}` : tool;
+    if (!path) return tool;
+    // O caminho sozinho confundia TRABALHO com LOOP: editar regiões diferentes
+    // de dois arquivos (a forma normal de uma correção que cruza teste e
+    // fonte) dava só duas assinaturas e disparava o aviso. O conteúdo da
+    // edição entra na assinatura; repetir a MESMA edição continua casando, e o
+    // ping-pong A→B / B→A continua dando duas assinaturas — loop de verdade.
+    const body = tool === 'Write'
+      ? input.content
+      : (input.old_string !== undefined || input.new_string !== undefined)
+        ? `${input.old_string ?? ''}\0${input.new_string ?? ''}\0${input.replace_all ? 1 : 0}`
+        : undefined;
+    if (body === undefined || body === null) return `${tool}:${path}`;
+    return `${tool}:${path}#${createHash('sha1').update(String(body)).digest('hex').slice(0, 8)}`;
   }
 
   if (tool === 'Bash') {

package/framework/hooks/shared/stdin-reader.js

@@ -1,26 +1,26 @@
-/**
- * Shared stdin reader for Claude Code hooks.
- *
- * Reads JSON payload from stdin (provided by Claude Code to hooks).
- * Returns parsed object or null on failure.
- */
-
-/**
- * Read and parse JSON from stdin
- * @returns {Promise<Object|null>} Parsed JSON or null
- */
-export function readStdin() {
-  return new Promise((resolve) => {
-    let input = '';
-    process.stdin.setEncoding('utf-8');
-    process.stdin.on('data', (chunk) => { input += chunk; });
-    process.stdin.on('end', () => {
-      try {
-        resolve(JSON.parse(input || '{}'));
-      } catch {
-        resolve(null);
-      }
-    });
-    process.stdin.on('error', () => resolve(null));
-  });
-}
+/**
+ * Shared stdin reader for Claude Code hooks.
+ *
+ * Reads JSON payload from stdin (provided by Claude Code to hooks).
+ * Returns parsed object or null on failure.
+ */
+
+/**
+ * Read and parse JSON from stdin
+ * @returns {Promise<Object|null>} Parsed JSON or null
+ */
+export function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(input || '{}'));
+      } catch {
+        resolve(null);
+      }
+    });
+    process.stdin.on('error', () => resolve(null));
+  });
+}

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/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.34.2"
+cliVersion: "8.35.1"
 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.34.2"
+cliVersion: "8.35.1"
 stacks:
   - umbraco
 ---