@polymorphism-tech/morph-spec 8.20.0 → 8.22.0

package/src/commands/e2e/e2e.js

@@ -0,0 +1,318 @@
+/**
+ * `morph-spec e2e up|status|down` — lifecycle of the verification stack.
+ *
+ * The stack is deliberately NOT torn down between verifies: cold-starting a
+ * .NET container per task is the difference between a loop people run and one
+ * they disable. `up` brings it (or reuses it), `status` says whether what is
+ * running still matches the working tree, and `down` releases it — which
+ * `morph-spec finish` also does as part of teardown.
+ *
+ * All the real logic lives in framework/hooks/shared/e2e-check.js, shared with
+ * the `verify` e2e node so the two can never drift.
+ *
+ * @module commands/e2e
+ */
+
+import chalk from 'chalk';
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+import {
+  bringUpStack,
+  composeProjectName,
+  computeSourceStamp,
+  defaultExec,
+  getStackStatus,
+  isDockerAvailable,
+  prepareAuth,
+  readStamp,
+  resolveComposeFile,
+  resolveSpecCommand,
+  tearDownStack,
+} from '../../../framework/hooks/shared/e2e-check.js';
+import { buildComposeEnv } from '../../lib/e2e/compose-env.js';
+
+/** Exit code for a usage error, matching `verify`'s convention. */
+const EXIT_USAGE = 2;
+
+// ============================================================================
+// Shared context
+// ============================================================================
+
+/**
+ * Everything the three subcommands need, resolved once.
+ * Returns null (after printing) when the project has no compose file — that is
+ * a usage error here, unlike in the verify node where it is a graded skip.
+ */
+function resolveContext(featureName, { json = false } = {}) {
+  const cwd = process.cwd();
+  const config = readConfig(cwd);
+  const composeFile = resolveComposeFile(cwd, config);
+
+  if (!composeFile) {
+    const message =
+      'No compose file found (compose.yaml, docker-compose.yml, …). ' +
+      'Set project.e2e.composeFile in .morph/config/config.json if it lives elsewhere.';
+    if (json) console.log(JSON.stringify({ error: message }, null, 2));
+    else console.error(chalk.red(`\n❌ ${message}\n`));
+    return null;
+  }
+
+  const projectName = composeProjectName(featureName);
+  const gitCommonDir = resolveGitCommonDir(cwd);
+
+  return {
+    cwd,
+    config,
+    composeFile,
+    projectName,
+    gitCommonDir,
+    env: buildEnv({ cwd, config, featureName, projectName, gitCommonDir }),
+  };
+}
+
+/**
+ * Compose environment: the port block this feature owns, plus any credentials
+ * from the gitignored auth env file.
+ *
+ * The port block comes from `buildComposeEnv` rather than being assembled here
+ * so this command and the `e2e` node inside `verify` agree by construction —
+ * isolation that exists only in the command nobody runs is no isolation at all.
+ * `COMPOSE_PROJECT_NAME` isolates container NAMES but not host ports; a compose
+ * that hardcodes ports instead of reading `${PORT:-3000}` cannot be isolated at
+ * all, which is surfaced as a warning rather than silently accepted.
+ */
+function buildEnv({ cwd, config, featureName, projectName, gitCommonDir }) {
+  return {
+    COMPOSE_PROJECT_NAME: projectName,
+    ...buildComposeEnv({ cwd, config, featureName, gitCommonDir }),
+  };
+}
+
+/**
+ * Warn once when the compose file publishes fixed host ports: with a hardcoded
+ * `"3000:3000"` the fleet port block cannot take effect, so two features
+ * running simultaneously will collide no matter what we inject.
+ */
+function warnOnFixedPorts(cwd, composeFile) {
+  try {
+    const raw = readFileSync(join(cwd, composeFile), 'utf8');
+    const publishesFixed = /^\s*-\s*["']?\d+:\d+["']?\s*$/m.test(raw);
+    if (publishesFixed) {
+      console.log(
+        chalk.yellow(
+          '⚠️  Compose publishes fixed host ports. Parallel worktrees will collide — ' +
+            'use ${PORT:-3000}:3000 so the fleet port block applies.'
+        )
+      );
+    }
+  } catch {
+    // Unreadable compose is the caller's problem, not this warning's.
+  }
+}
+
+// ============================================================================
+// up
+// ============================================================================
+
+/**
+ * `morph-spec e2e up <feature> [--fresh]`
+ *
+ * Exit codes: 0 = stack healthy · 1 = failed to come up (or auth broke) ·
+ * 2 = usage (no compose file / no docker).
+ */
+export async function e2eUpCommand(featureName, options = {}) {
+  const ctx = resolveContext(featureName, options);
+  if (!ctx) process.exit(EXIT_USAGE);
+
+  if (!isDockerAvailable(ctx.cwd)) {
+    console.error(chalk.red('\n❌ Docker is not available in this environment.\n'));
+    process.exit(EXIT_USAGE);
+  }
+
+  if (!options.json) warnOnFixedPorts(ctx.cwd, ctx.composeFile);
+
+  const result = bringUpStack(ctx.cwd, {
+    composeFile: ctx.composeFile,
+    projectName: ctx.projectName,
+    gitCommonDir: ctx.gitCommonDir,
+    env: ctx.env,
+    forceFresh: Boolean(options.fresh),
+  });
+
+  const auth =
+    result.status === 'pass'
+      ? prepareAuth(ctx.cwd, { config: ctx.config, env: ctx.env })
+      : { status: 'skip', reason: null };
+
+  const failed = result.status === 'fail' || auth.status === 'fail';
+  const payload = {
+    feature: featureName,
+    project: ctx.projectName,
+    composeFile: ctx.composeFile,
+    status: failed ? 'fail' : 'pass',
+    reused: result.reused,
+    reason: result.reason,
+    auth: { status: auth.status, reason: auth.reason },
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else if (failed) {
+    console.error(chalk.red(`\n✗ ${result.reason || auth.reason}\n`));
+    if (result.output) console.error(result.output);
+  } else {
+    const how = result.reused ? chalk.gray(`(${result.reason})`) : chalk.gray('(built)');
+    console.log(chalk.green(`\n✓ Stack up — ${ctx.projectName} ${how}`));
+    if (auth.reason) console.log(chalk.gray(`  auth: ${auth.reason}`));
+    console.log('');
+  }
+
+  process.exit(failed ? 1 : 0);
+}
+
+// ============================================================================
+// status
+// ============================================================================
+
+/**
+ * Where the app actually landed.
+ *
+ * The reviewer hands this to the evaluator instead of letting it guess
+ * `localhost:3000` — each feature owns a port block, so the default port is the
+ * one address most likely to be wrong. Mirrors what `playwright.config.ts` is
+ * asked to do, deliberately: one rule, two readers.
+ *
+ * @param {Record<string,string>} env
+ * @returns {string}
+ */
+export function resolveBaseUrl(env = {}) {
+  return env.PLAYWRIGHT_BASE_URL ?? `http://localhost:${env.PORT ?? 3000}`;
+}
+
+/**
+ * `morph-spec e2e status <feature> [--json]`
+ *
+ * Answers the question that matters before trusting a green run: is what is
+ * running still built from the code on disk? Exit 0 when up AND fresh, 1
+ * otherwise — so it can gate a script.
+ */
+export async function e2eStatusCommand(featureName, options = {}) {
+  const ctx = resolveContext(featureName, options);
+  if (!ctx) process.exit(EXIT_USAGE);
+
+  const status = getStackStatus(ctx.cwd, {
+    composeFile: ctx.composeFile,
+    projectName: ctx.projectName,
+    env: ctx.env,
+  });
+
+  const stamp = computeSourceStamp(ctx.cwd);
+  const previous = ctx.gitCommonDir ? readStamp(ctx.gitCommonDir, ctx.projectName) : null;
+  const fresh = Boolean(stamp && previous?.stamp === stamp);
+
+  const spec = resolveSpecCommand(ctx.cwd, ctx.config, ctx.config?.project?.frontendPath);
+
+  const payload = {
+    feature: featureName,
+    project: ctx.projectName,
+    composeFile: ctx.composeFile,
+    up: status.up,
+    healthy: status.healthy,
+    fresh,
+    baseUrl: resolveBaseUrl(ctx.env),
+    builtAt: previous?.builtAt ?? null,
+    specs: spec ? `${spec.command} ${spec.args.join(' ')}` : null,
+    services: status.services.map((s) => ({
+      name: s.Service ?? s.Name ?? null,
+      state: s.State ?? null,
+      health: s.Health || null,
+    })),
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log('');
+    console.log(chalk.bold(`E2E stack — ${ctx.projectName}`));
+    console.log(chalk.gray(`compose: ${ctx.composeFile}`));
+    console.log(chalk.gray(`url:     ${payload.baseUrl}`));
+    console.log('');
+    console.log(`  up       ${status.up ? chalk.green('yes') : chalk.gray('no')}`);
+    console.log(`  healthy  ${status.healthy ? chalk.green('yes') : chalk.gray('no')}`);
+    console.log(
+      `  fresh    ${fresh ? chalk.green('yes') : chalk.yellow('no — source changed since build')}`
+    );
+    console.log(`  specs    ${spec ? payload.specs : chalk.gray('none (smoke only)')}`);
+    for (const s of payload.services) {
+      console.log(chalk.gray(`    · ${s.name}: ${s.state}${s.health ? ` / ${s.health}` : ''}`));
+    }
+    console.log('');
+  }
+
+  process.exit(status.up && status.healthy && fresh ? 0 : 1);
+}
+
+// ============================================================================
+// down
+// ============================================================================
+
+/**
+ * `morph-spec e2e down <feature> [--volumes]`
+ *
+ * Teardown is best-effort by design — a stack that will not come down must
+ * never block `finish`.
+ */
+export async function e2eDownCommand(featureName, options = {}) {
+  const ctx = resolveContext(featureName, options);
+  if (!ctx) process.exit(EXIT_USAGE);
+
+  const result = tearDownStack(ctx.cwd, {
+    composeFile: ctx.composeFile,
+    projectName: ctx.projectName,
+    env: ctx.env,
+    volumes: Boolean(options.volumes),
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify({ feature: featureName, project: ctx.projectName, status: result.status }, null, 2));
+  } else if (result.status === 'pass') {
+    console.log(chalk.green(`\n✓ Stack down — ${ctx.projectName}\n`));
+  } else {
+    console.log(chalk.yellow(`\n⚠️  Teardown reported a problem (not fatal):\n${result.output}\n`));
+  }
+
+  process.exit(0);
+}
+
+// ============================================================================
+// Shared helpers
+// ============================================================================
+
+function readConfig(cwd) {
+  try {
+    const path = join(cwd, '.morph', 'config', 'config.json');
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8').replace(/^/, ''));
+  } catch {
+    return null;
+  }
+}
+
+/** Same resolution (and same fail-open) as verify-runner's. */
+function resolveGitCommonDir(cwd) {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      windowsHide: true,
+    }).trim();
+    return common ? resolve(cwd, common) : null;
+  } catch {
+    return null;
+  }
+}
+
+export { defaultExec };

package/src/commands/observability/cost.js

@@ -1,16 +1,26 @@
 /**
- * `morph-spec cost [feature] [--by task|phase] [--json]`
+ * `morph-spec cost [feature] [--by task|phase] [--all-trees] [--json]`
  *
  * A cost-facing view over the same harness event stream `telemetry` reads
  * (.morph/logs/events.jsonl): how much wall-clock time was spent inside
  * measured tasks (TaskStart→TaskEnd), how many context bytes were
  * re-ingested (grouped by kind: rubric/standard/skill/agents/plan-artifact/
  * code), and how many sub-agent dispatches happened (with total prompt
- * chars).
+ * chars). When the stream has `SessionUsage` events (real, hook-observed
+ * token counts), those are summed and shown too — see the sessionUsage
+ * caveat below.
  *
  * IMPORTANT: bytes re-ingested is a DETERMINISTIC PROXY for cost, not a
  * token count. Hooks only see what tools read off disk — never the model's
  * actual token usage — so this measures re-ingestion pressure, not spend.
+ * `sessionUsage` (when present) is the exception: real tokens, observed
+ * directly, not a proxy — see aggregateCost's docstring for the contract.
+ *
+ * `--all-trees` (Furo 3) widens the source from "just the current tree" to
+ * every git worktree that has its own events.jsonl — a fleet running N
+ * features in N worktrees otherwise only ever sees whichever tree `cost` was
+ * run from. Reuses the same worktree enumeration `doctor --worktrees`/`fleet`
+ * use (see loadTelemetryAllTrees in telemetry-reader.js).
  *
  * Read-only, always exits 0 on a normal (even empty) run — fail-open, an
  * empty stream is an answer, not an error. Only `--by` with an unknown value
@@ -18,7 +28,7 @@
  */
 
 import chalk from 'chalk';
-import { loadTelemetry, aggregateCost } from '../../lib/telemetry/telemetry-reader.js';
+import { loadTelemetry, loadTelemetryAllTrees, aggregateCost } from '../../lib/telemetry/telemetry-reader.js';
 
 const BYTES_CAVEAT =
   'Bytes re-ingeridos são um PROXY determinístico de custo (o que as ferramentas leram do disco) — NÃO são tokens reais. Hooks não enxergam o uso real de tokens do modelo.';
@@ -77,6 +87,19 @@ function printPhases(phases) {
   }
 }
 
+/**
+ * Real (hook-observed) token counts, when the stream has `SessionUsage`
+ * events — the non-proxy sibling of the bytes-re-ingested numbers above.
+ * No-op when absent (aggregateCost returns `null`, never a zeroed object).
+ */
+function printSessionUsage(sessionUsage) {
+  if (!sessionUsage) return;
+  console.log('\n' + chalk.white.bold('Tokens reais (sessões observadas)')
+    + chalk.gray(` · ${sessionUsage.sessions} SessionUsage`));
+  console.log(`  input=${sessionUsage.inputTokens}  output=${sessionUsage.outputTokens}  `
+    + `cacheRead=${sessionUsage.cacheReadTokens}  cacheCreation=${sessionUsage.cacheCreationTokens}`);
+}
+
 function printSummary(summary) {
   console.log(`\n  duração dentro de tasks medidas: ${fmtDuration(summary.taskDurationSeconds)}`);
   console.log(`  dispatches: ${summary.dispatches.count} (${summary.dispatches.promptChars} chars de prompt)`);
@@ -88,11 +111,67 @@ function printSummary(summary) {
     console.log('\n' + chalk.white.bold('Mix de tools'));
     for (const t of summary.tools) console.log(`  ${t.name.padEnd(16)} ${t.count}`);
   }
+
+  printSessionUsage(summary.sessionUsage);
+}
+
+/**
+ * `--all-trees` rendering: a short line per tree (so a fleet operator can
+ * spot which tree is expensive) followed by the COMBINED aggregate — full
+ * detail (task/phase breakdown honors `--by` here too, same as the
+ * single-tree path; a typeable flag combination is never a silent no-op).
+ *
+ * @param {string} [feature]
+ * @param {{ json?: boolean, by?: 'task'|'phase' }} options
+ * @param {string} cwd
+ */
+function printAllTrees(feature, options, cwd) {
+  const treesData = loadTelemetryAllTrees(cwd);
+  const perTree = treesData.map(({ tree, path, events }) => ({
+    tree,
+    path,
+    ...aggregateCost(events, { feature }),
+  }));
+  const combined = aggregateCost(treesData.flatMap((t) => t.events), { feature });
+
+  if (options.json) {
+    console.log(JSON.stringify({ allTrees: true, trees: perTree, combined }));
+    return;
+  }
+
+  if (combined.total === 0) {
+    const scope = feature ? ` para a feature "${feature}"` : '';
+    console.log(chalk.gray(`Telemetria vazia${scope} em todas as árvores — nenhuma tem eventos capturados ainda.`));
+    return;
+  }
+
+  console.log(chalk.white.bold(
+    `Custo do harness (proxy determinística) — todas as árvores (${perTree.length} com eventos, ${combined.total} eventos no total)`
+  ));
+  console.log(chalk.gray(`⚠ ${BYTES_CAVEAT}`));
+
+  for (const t of perTree) {
+    console.log('\n' + chalk.cyan.bold(`── Árvore: ${t.tree}`) + chalk.gray(` — ${t.path}`));
+    console.log(`   ${t.total} eventos · duração em tasks: ${fmtDuration(t.taskDurationSeconds)} · `
+      + `bytes: ${fmtBytes(t.bytesTotal)} · dispatches: ${t.dispatches.count}`);
+  }
+
+  console.log('\n' + chalk.white.bold('── Total agregado (todas as árvores)'));
+  if (combined.features.length) {
+    console.log(chalk.gray(`Features: ${combined.features.join(', ')}`));
+  }
+  if (options.by === 'task') {
+    printTasks(combined.tasks);
+  } else if (options.by === 'phase') {
+    printPhases(combined.phases);
+  } else {
+    printSummary(combined);
+  }
 }
 
 /**
  * @param {string} [feature] - narrow to a single feature
- * @param {{ json?: boolean, by?: 'task'|'phase', cwd?: string }} [options]
+ * @param {{ json?: boolean, by?: 'task'|'phase', allTrees?: boolean, cwd?: string }} [options]
  */
 export function costCommand(feature, options = {}) {
   if (options.by && !BY_MODES.includes(options.by)) {
@@ -102,7 +181,16 @@ export function costCommand(feature, options = {}) {
     return;
   }
 
-  const events = loadTelemetry(options.cwd || process.cwd());
+  const cwd = options.cwd || process.cwd();
+
+  if (options.allTrees) {
+    // Same fail-open + Windows-flush discipline as the single-tree path
+    // below — no forced process.exit(), --json included.
+    printAllTrees(feature, options, cwd);
+    return;
+  }
+
+  const events = loadTelemetry(cwd);
   const summary = aggregateCost(events, { feature });
 
   if (options.json) {

package/src/commands/project/update.js

@@ -24,8 +24,7 @@ import {
   checkProjectOutdated,
   saveProjectMorphVersion,
   getUpdateInstructions,
-  detectInstallMethod,
-  compareVersions
+  detectInstallMethod
 } from '../../utils/version-checker.js';
 import { installClaudeHooks, installGlobalStatusline } from '../../utils/claude-settings-manager.js';
 import { installSkills } from '../../utils/skills-installer.js';
@@ -33,6 +32,7 @@ import { installAgents, installDomainAgents } from '../../utils/agents-installer
 import { injectMorphImport } from '../../utils/claude-md-injector.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
 import { updateClaudeMdAgentsBlock, installRulesForStack } from '../../scripts/setup-infra.js';
+import { reconcileLegacyTemplatesCopy } from '../../lib/installers/templates-reconcile.js';
 
 /**
  * Backup user's config.json before cleaning
@@ -89,67 +89,6 @@ async function cleanFrameworkDirs(morphPath, targetPath) {
   }
 }
 
-/**
- * Last CLI version whose `update`/`setup-infra` still wrote
- * `.morph/framework/templates/` unconditionally, before Task 2 of the R3
- * perf plan removed that copy. Used as the decision boundary in
- * `reconcileLegacyTemplatesCopy` below — see its doc comment for why a
- * version check is used instead of diffing file content.
- */
-const LAST_VERSION_THAT_COPIED_TEMPLATES = '8.17.0';
-
-/**
- * Reconcile a pre-existing `.morph/framework/templates/` copy now that
- * `update` no longer writes it (Task 2, R3 perf plan — resolution falls
- * back to the npm package's own framework/templates/, see
- * template-registry.js / architecture-scanner.js's layered resolver).
- *
- * Decided from the project's PRIOR recorded CLI version (before THIS
- * update writes a new one), not by diffing content against the package.
- * A content diff can't tell "stale copy from an older CLI version" apart
- * from "deliberate user override" — and staleness is the dominant case for
- * anyone who actually runs `update`, since template content does change
- * between releases. The version boundary is unambiguous instead:
- *
- *   - No local copy → nothing to do.
- *   - Prior version is unrecorded, OR <= LAST_VERSION_THAT_COPIED_TEMPLATES
- *     → the copy could ONLY have been put there by the OLD installer:
- *     `.morph/framework/**` is Edit-denied to the agent (MORPH_DENY in
- *     hooks-installer.js — "installer-managed, immutable at runtime"),
- *     the directory is gitignored, and every `update` before this fix
- *     unconditionally wiped + recopied it. There is no path by which a
- *     project on an old version could have a genuine override sitting
- *     here. Safe to delete unconditionally — it is dead weight, not data.
- *   - Prior version > LAST_VERSION_THAT_COPIED_TEMPLATES → `update` and
- *     `setup-infra` have never written this directory for this project.
- *     Anything found here was placed deliberately (by the user or other
- *     tooling) — this is the forward-looking override use case the
- *     layered resolver exists for. Preserve untouched, unconditionally,
- *     with no diffing.
- *
- * @param {string} templatesDest - .morph/framework/templates (may not exist)
- * @param {string|null} priorProjectVersion - project's recorded morph-spec
- *   version BEFORE this update run (checkProjectOutdated().current)
- * @returns {'absent'|'removed-legacy'|'preserved-override'}
- */
-export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion) {
-  if (!existsSync(templatesDest)) return 'absent';
-
-  const isLegacy = !priorProjectVersion
-    || compareVersions(priorProjectVersion, LAST_VERSION_THAT_COPIED_TEMPLATES) <= 0;
-
-  if (!isLegacy) return 'preserved-override';
-
-  try {
-    fs.removeSync(templatesDest);
-    return 'removed-legacy';
-  } catch {
-    // Couldn't remove — don't risk a half-broken state; leave it and let
-    // the layered resolver's override-first check pick it up as before.
-    return 'preserved-override';
-  }
-}
-
 /**
  * Restore user's config.json after reinstallation
  * @param {string} morphPath - Path to .morph directory

package/src/commands/state/finish.js

@@ -13,6 +13,11 @@ import {
 } from '../project/worktree.js';
 import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
 import { releaseClaim } from '../../../framework/hooks/shared/claim-registry.js';
+import {
+  composeProjectName,
+  resolveComposeFile,
+  tearDownStack,
+} from '../../../framework/hooks/shared/e2e-check.js';
 import { runArchive } from './archive.js';
 
 /** workType → conventional-commit type. `hotfix` IS a fix; anything else is a chore. */
@@ -85,12 +90,20 @@ export async function finishCommand(feature, options = {}) {
   // working on it (B1). Released on EVERY success path — hooking it into emit
   // is the single point that covers merge/PR/--keep alike. Fail-open: a claim
   // that outlives its feature only expires on its own TTL.
+  //
+  // The e2e stack rides along for the same reason: `morph-spec verify` leaves it
+  // UP on purpose (cold-starting a container per task is what makes the loop
+  // unusable), so something has to be the one place that reclaims the
+  // containers and their ports when the feature closes. Best-effort by
+  // contract — a stack that refuses to come down must never fail a finish that
+  // already merged.
   const emit = (obj) => {
     if (obj?.finished === true) {
       try {
         const common = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: root, stdio: 'pipe' }).toString().trim();
         if (common) releaseClaim(feature, { gitCommonDir: resolve(root, common) });
       } catch { /* fail-open */ }
+      tearDownE2eStack(feature, root);
     }
     console.log(JSON.stringify(obj));
   };
@@ -502,6 +515,31 @@ function readFeatureJson(cwd, feature) {
   }
 }
 
+/**
+ * Reclaim the feature's verification stack, if the project has one.
+ *
+ * Runs from the ROOT rather than the worktree: by the time a finish emits
+ * success the worktree may already be gone, and the compose file is versioned
+ * so the root's copy is equivalent. Entirely fail-open — no compose, no docker,
+ * or a stubborn container are all non-events here.
+ */
+function tearDownE2eStack(feature, root) {
+  try {
+    const config = JSON.parse(
+      readFileSync(join(root, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, '')
+    );
+    const composeFile = resolveComposeFile(root, config);
+    if (!composeFile) return;
+
+    const projectName = composeProjectName(feature);
+    tearDownStack(root, {
+      composeFile,
+      projectName,
+      env: { COMPOSE_PROJECT_NAME: projectName },
+    });
+  } catch { /* fail-open — teardown must never fail a completed finish */ }
+}
+
 /** Drop a feature from the thin, gitignored root index (never via saveState). */
 function dropFromRootIndex(root, feature) {
   const rootPath = join(root, '.morph', 'state.json');

package/src/commands/state/gate-check.js

@@ -87,9 +87,12 @@ function evaluatorCompositeScore(cwd, featureName) {
  * never had (it shipped fully tested with zero callers; see the R4 report).
  *
  * `verificationStatus` feeds a real pause rule (verify vermelho pausa —
- * política adicionada em risk-detector.js no fecho do R4); `verification`
- * completo, verificationStale, diffstat e sha seguem como contexto de
- * auditoria persistido, sem regra própria.
+ * política adicionada em risk-detector.js no fecho do R4, qualquer gate).
+ * `verificationStale` também alimenta uma regra própria, mas só no ship
+ * (`gate === 'review'`) — sha do stamp divergindo do HEAD atual. `gate` em si
+ * é o que permite risk-detector.js diferenciar as duas. `verification`
+ * completo, diffstat e sha seguem como contexto de auditoria persistido, sem
+ * regra própria.
  *
  * @param {string} featureName
  * @param {object} feature
@@ -104,6 +107,10 @@ function collectSignals(featureName, feature, cwd, gateName) {
   const verification = feature.verification || null;
 
   const signals = {
+    // Furo 2: disk-derived, never in OVERRIDABLE_SIGNAL_KEYS — a caller
+    // cannot spoof which gate risk-detector.js thinks it is deciding, same
+    // anti-spoof rationale as workType (hotfix's forced pause).
+    gate: gateName,
     workType: feature.workType || 'feature',
     taskCount: tasks.length,
     standardsViolations: [],

package/src/commands/validation/validate-feature.js

@@ -80,7 +80,7 @@ const OUTPUT_SECTIONS = {
     ],
   },
   // morph-plan (mandate.md) emits: Stack, Standards obrigatórios,
-  // Patterns proibidos, Checklist de done.
+  // Patterns proibidos, Verificação de runtime, Checklist de done.
   'mandate.md': {
     required: [
       'Stack',
@@ -89,6 +89,12 @@ const OUTPUT_SECTIONS = {
     ],
     recommended: [
       ['Patterns proibidos', 'Padrões proibidos', 'Padroes proibidos', 'Forbidden Patterns', 'Forbidden', 'Proibido'],
+      // Recommended rather than required on purpose: mandate.md freezes after
+      // Gate 2 (protect-spec-files blocks Write AND Edit), so promoting this to
+      // `required` would fail every in-flight feature with no way to fix it.
+      // New mandates get the section from morph-plan §4; the enforcement that
+      // actually matters is verify's e2e node, not this heading check.
+      ['Verificação de runtime', 'Verificacao de runtime', 'Runtime', 'E2E'],
     ],
     optional: [
       ['Riscos', 'Risks'],

package/src/commands/validation/verify.js

@@ -37,6 +37,10 @@ function formatVerifyResult(result) {
       detail = node.reason || '';
     } else if (name === 'validators' && node.score != null) {
       detail = `score ${node.score}/10`;
+    } else if (node.reason) {
+      // A green e2e still carries meaning worth showing: smoke-only vs specs,
+      // warm reuse vs rebuild. Without it, "pass" hides how much was proven.
+      detail = `${node.durationMs}ms — ${node.reason}`;
     } else {
       detail = `${node.durationMs}ms`;
     }
@@ -149,6 +153,8 @@ export async function verifyCommand(featureName, taskId, options = {}) {
     timeout: options.timeout,
     skipTests: options.skipTests,
     skipBuild: options.skipBuild,
+    skipE2e: options.skipE2e,
+    freshE2e: options.freshE2e,
   });
 
   const scopeKey = taskId ? `taskVerifications.${taskId}` : 'verifications.feature';
@@ -168,6 +174,7 @@ export async function verifyCommand(featureName, taskId, options = {}) {
         build: result.nodes.build.status,
         tests: result.nodes.tests.status,
         validators: result.nodes.validators.status,
+        e2e: result.nodes.e2e.status,
       },
       score: result.nodes.validators.score ?? null,
       attempts: (prevEntry?.attempts ?? 0) + 1,