@polymorphism-tech/morph-spec 8.8.0 → 8.10.0

package/README.md

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

package/claude-plugin.json

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

package/docs/CHEATSHEET.md

@@ -185,4 +185,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v8.8.0 by Polymorphism Tech*
+*morph-spec v8.10.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.8.0 by Polymorphism Tech*
+*morph-spec v8.10.0 by Polymorphism Tech*

package/framework/mcp/registry.json

@@ -3,7 +3,7 @@
   "description": "Centralized MCP registry with phase relevance and install configuration for morph-spec workflows",
   "mcps": {
     "context7": {
-      "phases": ["proposal", "design", "tasks", "implement"],
+      "phases": ["proposal", "plan", "implement"],
       "tools": ["resolve-library-id", "query-docs"],
       "detection": "enabledPlugins includes context7 or mcpServers includes context7",
       "fallback": "WebSearch + WebFetch for library documentation",
@@ -86,7 +86,7 @@
       }
     },
     "asaas": {
-      "phases": ["design", "implement"],
+      "phases": ["plan", "implement"],
       "tools": ["enumerate_endpoints", "get_endpoint_schema", "generate_code_example", "execute_api_call", "search_docs"],
       "detection": "mcpServers includes asaas",
       "fallback": "WebFetch https://docs.asaas.com for API documentation",
@@ -201,11 +201,12 @@
       }
     }
   },
+  "_phaseMatrixNote": "Keys must be the v5 phases from framework/phases.json. The v4 keys 'design' and 'tasks' both collapsed into 'plan'; 'review' was absent entirely, so a project in review resolved to undefined. Stack-scoped MCPs (asaas) stay out of this matrix on purpose — only universal ones are listed.",
   "phaseMatrix": {
     "proposal": ["context7"],
     "uiux": ["playwright", "context7", "stitch", "gemini-image"],
-    "design": ["context7"],
-    "tasks": ["context7"],
-    "implement": ["context7", "playwright", "vercel", "gemini-image"]
+    "plan": ["context7"],
+    "implement": ["context7", "playwright", "vercel", "gemini-image"],
+    "review": ["playwright", "context7"]
   }
 }

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.8.0"
+cliVersion: "8.10.0"
 ---
 
 # create-umbraco-lp

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.8.0"
+cliVersion: "8.10.0"
 ---
 
 # migrate-lp-to-umbraco

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

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.8.0"
+cliVersion: "8.10.0"
 ---
 
 # morph-apply

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

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.8.0"
+cliVersion: "8.10.0"
 ---
 
 # morph-brainstorming

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

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.8.0"
+cliVersion: "8.10.0"
 ---
 
 # morph-eval

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

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.8.0"
+cliVersion: "8.10.0"
 ---
 
 # morph-hotfix

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

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.8.0"
+cliVersion: "8.10.0"
 ---
 
 # morph-implement

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

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.8.0"
+cliVersion: "8.10.0"
 ---
 
 # morph-plan

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

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.8.0"
+cliVersion: "8.10.0"
 ---
 
 # morph-proposal

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

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.8.0"
+cliVersion: "8.10.0"
 ---
 
 # morph-review

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.8.0"
+cliVersion: "8.10.0"
 ---
 
 # morph-stack-scan

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

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.8.0"
+cliVersion: "8.10.0"
 ---
 
 # morph-standards

package/package.json

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

package/src/commands/project/doctor.js

@@ -88,15 +88,109 @@ const REQUIRED_COMMAND_FILES = [
   'src/commands/context/context-refresh.js',
 ];
 
-// framework standards (stack-relevant only)
+/**
+ * Validate a parsed `agents.json` against the v5 contract.
+ *
+ * Exported, and pure, so the tests can exercise the REAL rules. They used to
+ * re-implement this logic inline "because doctorCommand doesn't export
+ * individual check functions" — and the two promptly disagreed: the tests
+ * asserted a v4 document (version 4.x, `tier` and `active_phases` required)
+ * while this code treats exactly those fields as deprecated. Both stayed green
+ * because they never met. A canary that destroyed this whole check left the
+ * suite at 18/18.
+ *
+ * @param {Object} agentsData - parsed agents.json
+ * @returns {Array<{name: string, status: 'ok'|'warn'|'error', msg?: string}>}
+ */
+export function validateAgentsJson(agentsData) {
+  const checks = [];
+  const agentEntries = Object.entries(agentsData.agents || {})
+    .filter(([k]) => !k.startsWith('_comment'));
+  const actualCount = agentEntries.length;
+  const declaredCount = agentsData.total_agents;
+
+  // 1: total_agents matches actual count
+  if (actualCount !== declaredCount) {
+    checks.push({
+      name: 'agents.json count',
+      status: 'warn',
+      msg: `total_agents declares ${declaredCount} but found ${actualCount} agents`
+    });
+  } else {
+    checks.push({ name: 'agents.json count', status: 'ok', msg: `${actualCount} agents` });
+  }
+
+  // 2: required v5 personas present
+  const missingPersonas = REQUIRED_AGENTS.filter(id => !(agentsData.agents || {})[id]);
+  if (missingPersonas.length > 0) {
+    checks.push({
+      name: 'agents.json required personas',
+      status: 'error',
+      msg: `Missing required personas: ${missingPersonas.join(', ')}`
+    });
+  } else {
+    checks.push({ name: 'agents.json required personas', status: 'ok' });
+  }
+
+  // 3: v5 schema (flat personas, no tiers)
+  const version = agentsData.version || 'unknown';
+  const isV5 = version.startsWith('5.');
+  const v4Fields = [];
+  const missingV5Fields = [];
+
+  for (const [id, data] of agentEntries) {
+    if (data.tier !== undefined) v4Fields.push(`${id}.tier`);
+    if (data.active_phases !== undefined) v4Fields.push(`${id}.active_phases`);
+    if (data.reports_to !== undefined) v4Fields.push(`${id}.reports_to`);
+    if (data.teammate !== undefined) v4Fields.push(`${id}.teammate`);
+    if (!data.title) missingV5Fields.push(`${id}.title`);
+    if (!Array.isArray(data.domains)) missingV5Fields.push(`${id}.domains`);
+    if (typeof data.persona !== 'string' || !data.persona) missingV5Fields.push(`${id}.persona`);
+  }
+
+  if (isV5) {
+    checks.push({ name: `agents.json schema (v${version})`, status: 'ok' });
+  } else {
+    checks.push({
+      name: `agents.json schema (v${version})`,
+      status: 'warn',
+      msg: 'expected v5.x — run agents migration'
+    });
+  }
+
+  if (v4Fields.length > 0) {
+    const sample = v4Fields.slice(0, 3).join(', ');
+    checks.push({
+      name: 'agents.json deprecated v4 fields',
+      status: 'warn',
+      msg: `${v4Fields.length} v4 field(s) found: ${sample}${v4Fields.length > 3 ? '...' : ''}`
+    });
+  }
+
+  if (missingV5Fields.length > 0 && isV5) {
+    const sample = missingV5Fields.slice(0, 3).join(', ');
+    checks.push({
+      name: 'agents.json v5 required fields',
+      status: 'warn',
+      msg: `${missingV5Fields.length} missing: ${sample}${missingV5Fields.length > 3 ? '...' : ''}`
+    });
+  }
+
+  return checks;
+}
+
+// framework standards (stack-relevant only).
+// Keep every entry pointing at a file that exists: a check that can never pass
+// carries the same information as one that can never fail — none. This list
+// still named two standards from a `workflows/` directory that no longer
+// exists, which pinned `doctor --full` at a permanent 3/6 and made a real
+// regression indistinguishable from the usual red.
 const FRAMEWORK_STANDARDS = [
   'framework/standards/architecture/vertical-slice/vertical-slice.md',
   'framework/standards/data/nosql/cosmos-db.md',
   'framework/standards/data/nosql/cache/redis.md',
   'framework/standards/data/vector-search/rag-chunking.md',
-  'framework/standards/integration/mcp/mcp-tools.md',
-  'framework/standards/workflows/thread-management.md',
-  'framework/standards/workflows/parallel-execution.md'
+  'framework/standards/integration/mcp/mcp-tools.md'
 ];
 
 // required personas expected in agents.json (v5 — the universal, stack-agnostic
@@ -127,39 +221,61 @@ async function doctorFullCommand(frameworkRoot) {
     }
   };
 
-  // ── 1. Core Libraries ───────────────────────────────────────────────────
-  console.log(chalk.cyan(`\n  src/lib/ — Core Libraries (${REQUIRED_LIB_FILES.length} files)`));
-  const missingLibs = [];
-  for (const f of REQUIRED_LIB_FILES) {
-    if (!(await pathExists(join(frameworkRoot, f)))) missingLibs.push(f.split('/').pop());
-  }
-  check(`Core Libraries (${REQUIRED_LIB_FILES.length - missingLibs.length}/${REQUIRED_LIB_FILES.length})`,
-    missingLibs.length === 0, false,
-    missingLibs.length > 0 ? `missing: ${missingLibs.join(', ')}` : '');
-
-  // ── 2. Command Files ─────────────────────────────────────────────────────
-  console.log(chalk.cyan(`\n  src/commands/ — Command Files (${REQUIRED_COMMAND_FILES.length} files)`));
-  const missingCmds = [];
-  for (const f of REQUIRED_COMMAND_FILES) {
-    if (!(await pathExists(join(frameworkRoot, f)))) missingCmds.push(f.split('/').pop());
+  // Two layouts reach this command and they disagree on where everything is.
+  //
+  //   framework repo     src/, framework/, no .morph/ at all
+  //   installed project  .morph/framework/, and the CLI in node_modules
+  //
+  // Half the checks assumed one layout and half the other, so `--full` could
+  // not pass anywhere: red in the repo (no .morph/) and red in a project (no
+  // src/). A check that can never pass reports exactly as much as one that can
+  // never fail. Each check now runs only where it means something.
+  const installedAgentsPath = join(frameworkRoot, '.morph/framework/agents.json');
+  const canonicalAgentsPath = join(frameworkRoot, 'framework/agents.json');
+  const inFrameworkRepo = !(await pathExists(installedAgentsPath))
+    && await pathExists(canonicalAgentsPath);
+  const agentsPath = inFrameworkRepo ? canonicalAgentsPath : installedAgentsPath;
+
+  console.log(chalk.gray(`\n  Contexto: ${inFrameworkRepo ? 'repo do framework' : 'projeto instalado'}`));
+
+  // ── 1-2. Source tree (framework repo only) ──────────────────────────────
+  // An installed project has no src/ — the CLI lives in node_modules, and its
+  // integrity is npm's job, not the doctor's.
+  if (inFrameworkRepo) {
+    console.log(chalk.cyan(`\n  src/lib/ — Core Libraries (${REQUIRED_LIB_FILES.length} files)`));
+    const missingLibs = [];
+    for (const f of REQUIRED_LIB_FILES) {
+      if (!(await pathExists(join(frameworkRoot, f)))) missingLibs.push(f.split('/').pop());
+    }
+    check(`Core Libraries (${REQUIRED_LIB_FILES.length - missingLibs.length}/${REQUIRED_LIB_FILES.length})`,
+      missingLibs.length === 0, false,
+      missingLibs.length > 0 ? `missing: ${missingLibs.join(', ')}` : '');
+
+    console.log(chalk.cyan(`\n  src/commands/ — Command Files (${REQUIRED_COMMAND_FILES.length} files)`));
+    const missingCmds = [];
+    for (const f of REQUIRED_COMMAND_FILES) {
+      if (!(await pathExists(join(frameworkRoot, f)))) missingCmds.push(f.split('/').pop());
+    }
+    check(`Command Files (${REQUIRED_COMMAND_FILES.length - missingCmds.length}/${REQUIRED_COMMAND_FILES.length})`,
+      missingCmds.length === 0, false,
+      missingCmds.length > 0 ? `missing: ${missingCmds.join(', ')}` : '');
   }
-  check(`Command Files (${REQUIRED_COMMAND_FILES.length - missingCmds.length}/${REQUIRED_COMMAND_FILES.length})`,
-    missingCmds.length === 0, false,
-    missingCmds.length > 0 ? `missing: ${missingCmds.join(', ')}` : '');
 
   // ── 3. Framework Standards ───────────────────────────────────────────────
-  console.log(chalk.cyan(`\n  framework/standards/ — Framework Standards (${FRAMEWORK_STANDARDS.length} files)`));
+  // Same files, different root: the repo holds them at framework/standards/,
+  // an installed project at .morph/framework/standards/.
+  const stdsRoot = inFrameworkRepo ? frameworkRoot : join(frameworkRoot, '.morph');
+  console.log(chalk.cyan(`\n  ${inFrameworkRepo ? '' : '.morph/'}framework/standards/ — Framework Standards (${FRAMEWORK_STANDARDS.length} files)`));
   const missingStds = [];
   for (const f of FRAMEWORK_STANDARDS) {
-    if (!(await pathExists(join(frameworkRoot, f)))) missingStds.push(f.replace('framework/standards/', ''));
+    if (!(await pathExists(join(stdsRoot, f)))) missingStds.push(f.replace('framework/standards/', ''));
   }
   check(`Framework Standards (${FRAMEWORK_STANDARDS.length - missingStds.length}/${FRAMEWORK_STANDARDS.length})`,
     missingStds.length === 0, false,
     missingStds.length > 0 ? `missing: ${missingStds.join(', ')}` : '');
 
   // ── 5. Required Agents in agents.json ───────────────────────────────────
-  console.log(chalk.cyan(`\n  .morph/framework/agents.json — Required Agents (${REQUIRED_AGENTS.length})`));
-  const agentsPath = join(frameworkRoot, '.morph/framework/agents.json');
+  console.log(chalk.cyan(`\n  ${inFrameworkRepo ? 'framework' : '.morph/framework'}/agents.json — Required Agents (${REQUIRED_AGENTS.length})`));
   if (await pathExists(agentsPath)) {
     try {
       const agentsConfig = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
@@ -176,8 +292,10 @@ async function doctorFullCommand(frameworkRoot) {
   }
 
   // ── 6. agents.json version freshness ──────────────────────────────────
-  const canonicalAgentsPath = join(frameworkRoot, 'framework/agents.json');
-  if (await pathExists(agentsPath) && await pathExists(canonicalAgentsPath)) {
+  // Only meaningful for an installed project: it compares what was installed
+  // against the canonical source. In the framework repo the two are the same
+  // file, so the comparison is vacuous and is skipped.
+  if (!inFrameworkRepo && await pathExists(agentsPath) && await pathExists(canonicalAgentsPath)) {
     try {
       const installed = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
       const canonical = JSON.parse(await fs.readFile(canonicalAgentsPath, 'utf8'));
@@ -193,7 +311,9 @@ async function doctorFullCommand(frameworkRoot) {
   // agents.json is the single source of truth; the .claude/agents/morph-*.md
   // files are derived artifacts (ADR-001). Missing = broken dispatch (error);
   // stale/hand-edited or orphan = drift (warning).
-  if (await pathExists(agentsPath)) {
+  // Skipped in the framework repo: the generated `.claude/agents/morph-*.md`
+  // are an artifact of installing into a project, not of the source tree.
+  if (!inFrameworkRepo && await pathExists(agentsPath)) {
     console.log(chalk.cyan('\n  .claude/agents/ — Generated personas (drift vs agents.json)'));
     try {
       let projectTags = [];
@@ -527,7 +647,16 @@ export async function doctorCommand(options = {}) {
 
   // Worktree reconciliation mode (C2)
   if (options.worktrees) {
-    return doctorWorktreesCommand(process.cwd(), options);
+    const clean = await doctorWorktreesCommand(process.cwd(), options);
+    // The audit result has to reach the exit code, not just the terminal.
+    // Commander discards an action's return value, so this reported success to
+    // every script while printing "⚠ 5 inconsistência(s)" to the human — a
+    // `doctor --worktrees || echo falhou` in CI or a pre-commit hook saw a
+    // clean run with orphaned worktrees piling up. The flag-misuse branch
+    // above already treats the exit code as this command's signal channel;
+    // only the audit itself was left out of it.
+    if (!clean) process.exitCode = 1;
+    return clean;
   }
 
   const targetPath = process.cwd();
@@ -661,82 +790,10 @@ export async function doctorCommand(options = {}) {
   if (await pathExists(agentsPath)) {
     try {
       const agentsData = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
-      const agentEntries = Object.entries(agentsData.agents || {})
-        .filter(([k]) => !k.startsWith('_comment'));
-      const actualCount = agentEntries.length;
-      const declaredCount = agentsData.total_agents;
-
-      // Check 1: total_agents matches actual count
-      if (actualCount !== declaredCount) {
-        checks.push({
-          name: 'agents.json count',
-          status: 'warn',
-          msg: `total_agents declares ${declaredCount} but found ${actualCount} agents`
-        });
-        hasWarnings = true;
-      } else {
-        checks.push({ name: 'agents.json count', status: 'ok', msg: `${actualCount} agents` });
-      }
-
-      // Check 2: required v5 personas present
-      const requiredPersonas = REQUIRED_AGENTS;
-      const missingPersonas = requiredPersonas.filter(id => !agentsData.agents[id]);
-      if (missingPersonas.length > 0) {
-        checks.push({
-          name: 'agents.json required personas',
-          status: 'error',
-          msg: `Missing required personas: ${missingPersonas.join(', ')}`
-        });
-        hasErrors = true;
-      } else {
-        checks.push({ name: 'agents.json required personas', status: 'ok' });
-      }
-
-      // Check 3: v5 schema validation (flat personas, no tiers)
-      const version = agentsData.version || 'unknown';
-      const isV5 = version.startsWith('5.');
-      const v4Fields = [];
-      const missingV5Fields = [];
-
-      for (const [id, data] of agentEntries) {
-        if (data.tier !== undefined) v4Fields.push(`${id}.tier`);
-        if (data.active_phases !== undefined) v4Fields.push(`${id}.active_phases`);
-        if (data.reports_to !== undefined) v4Fields.push(`${id}.reports_to`);
-        if (data.teammate !== undefined) v4Fields.push(`${id}.teammate`);
-        if (!data.title) missingV5Fields.push(`${id}.title`);
-        if (!Array.isArray(data.domains)) missingV5Fields.push(`${id}.domains`);
-        if (typeof data.persona !== 'string' || !data.persona) missingV5Fields.push(`${id}.persona`);
-      }
-
-      if (isV5) {
-        checks.push({ name: `agents.json schema (v${version})`, status: 'ok' });
-      } else {
-        checks.push({
-          name: `agents.json schema (v${version})`,
-          status: 'warn',
-          msg: 'expected v5.x — run agents migration'
-        });
-        hasWarnings = true;
-      }
-
-      if (v4Fields.length > 0) {
-        const sample = v4Fields.slice(0, 3).join(', ');
-        checks.push({
-          name: 'agents.json deprecated v4 fields',
-          status: 'warn',
-          msg: `${v4Fields.length} v4 field(s) found: ${sample}${v4Fields.length > 3 ? '...' : ''}`
-        });
-        hasWarnings = true;
-      }
-
-      if (missingV5Fields.length > 0 && isV5) {
-        const sample = missingV5Fields.slice(0, 3).join(', ');
-        checks.push({
-          name: 'agents.json v5 required fields',
-          status: 'warn',
-          msg: `${missingV5Fields.length} missing: ${sample}${missingV5Fields.length > 3 ? '...' : ''}`
-        });
-        hasWarnings = true;
+      for (const c of validateAgentsJson(agentsData)) {
+        checks.push(c);
+        if (c.status === 'error') hasErrors = true;
+        else if (c.status === 'warn') hasWarnings = true;
       }
     } catch {
       checks.push({ name: 'agents.json', status: 'error', msg: 'invalid JSON' });

package/src/commands/project/init.js

@@ -15,7 +15,7 @@ import { getInstalledCLIVersion, checkProjectOutdated } from '../../utils/versio
 import { installClaudeHooks } from '../../utils/claude-settings-manager.js';
 import inquirer from 'inquirer';
 import { detectProject } from '../../lib/detectors/index.js';
-import { detectClaudeConfig, mapMcpsToPhases, formatConfigSummary } from '../../lib/detectors/claude-config-detector.js';
+import { detectClaudeConfig, mcpAvailabilityByPhase, formatConfigSummary } from '../../lib/detectors/claude-config-detector.js';
 import { generateSettings, saveIntegrations } from '../../lib/generators/settings-generator.js';
 import {
   orchestrateMcpSetup,
@@ -25,7 +25,8 @@ import {
   generateSetupInstructions,
   formatMcpStatusTable,
   isRemoteMcp,
-  setupStitch
+  setupStitch,
+  loadMcpRegistry
 } from '../../lib/installers/mcp-installer.js';
 import { setupInfra, installRulesForStack } from '../../scripts/setup-infra.js';
 import { installSkills } from '../../utils/skills-installer.js';
@@ -147,14 +148,24 @@ export async function initCommand(options) {
           logger.info(summary);
         }
 
-        // Show MCP-to-phase mapping
+        // Show MCP-to-phase mapping.
+        //
+        // This called mapMcpsToPhases with one argument where it takes three,
+        // so `phaseMatrix[currentPhase]` threw a TypeError on every project
+        // that had any MCP configured. The outer catch reported it as
+        // "Claude config detection skipped" — which reads like "nothing to
+        // detect" — and everything below it never ran: integrations.json was
+        // never written and the optimized settings were never generated.
         if (claudeConfigDetected.mcpServers.length > 0) {
-          const phaseMap = mapMcpsToPhases(claudeConfigDetected.mcpServers);
-          logger.blank();
-          logger.dim('MCP usage by phase:');
-          for (const [phase, mcps] of Object.entries(phaseMap)) {
-            if (mcps.length > 0) {
-              logger.dim(`  ${phase}: ${mcps.map(m => m.name).join(', ')}`);
+          const byPhase = mcpAvailabilityByPhase(
+            claudeConfigDetected.mcpServers,
+            loadMcpRegistry().phaseMatrix || {}
+          );
+          if (byPhase.length > 0) {
+            logger.blank();
+            logger.dim('MCP usage by phase:');
+            for (const { phase, available } of byPhase) {
+              logger.dim(`  ${phase}: ${available.join(', ')}`);
             }
           }
         }

package/src/commands/state/approve.js

@@ -256,6 +256,31 @@ export async function approveCommand(featureName, gateName, options = {}) {
       }
     }
 
+    // Skipped-pause backstop: a gate whose recorded decision demanded a human
+    // pause (gateDecisions[gate].pause === true) cannot then be stamped by a
+    // non-human signature. The detection already existed — in gate-guard.js —
+    // but that hook is registered for `Write|Edit|AskUserQuestion`, and a Bash
+    // tool call fires no hook at all. Since MORPH.md requires gate approval to
+    // go through THIS command and forbids hand-editing the state, the only path
+    // the hook could ever see was the one the charter bans. The check belongs
+    // where the stamp is applied, not beside it.
+    //
+    // Gated on the RESOLVED `approvedBy`, matching the hotfix backstop above:
+    // an omitted --mode in a headless context also resolves to "auto" and must
+    // not slip through. `--force` does NOT bypass this either — it is the
+    // out-of-order recovery flag, a different concern. The way out is a human
+    // signature, or rewriting the decision that asked for the pause.
+    const decision = feature.gateDecisions?.[gateName];
+    if (decision?.pause === true && approvedBy === 'auto') {
+      console.error(chalk.red(`\n❌ O Gate "${gateName}" registrou pause:true — auto-aprovação não se aplica.`));
+      console.error(chalk.gray(`   Sinal: ${decision.reason || 'risco detectado'}`));
+      console.error(chalk.gray('   A decisão gravada exigia pausa humana. Aprove com --approver <nome>, num'));
+      console.error(chalk.gray('   terminal interativo, ou pela resposta humana via AskUserQuestion (state-sync).'));
+      console.error(chalk.gray('   Se o sinal de risco já não vale, regrave a decisão:'));
+      console.error(chalk.gray(`   morph-spec gate-decision ${featureName} ${gateName} --pause false --reason "<motivo>"\n`));
+      process.exit(1);
+    }
+
     let selfAssessed = false;
     if (gateName === 'review') {
       const evaluatorReport = join(process.cwd(), '.morph', 'features', featureName, '4-review', 'evaluator-report.md');

package/src/core/paths/output-schema.js

@@ -120,24 +120,6 @@ export function getAbsoluteOutputPath(projectRoot, featureName, outputType) {
   return join(projectRoot, '.morph', 'features', featureName, entry.phaseDir, leafSegment(entry));
 }
 
-/**
- * Human-readable path of a schema entry, relative to the feature directory.
- *
- * SINGLE source for the `morph-outputs` tables: `scripts/generate-refs.js`
- * writes them and `test/framework/refs.test.js` verifies them, and if the two
- * rebuilt the string independently they would drift apart the first time the
- * schema grew a new shape. Multi-file types render the filename PATTERN, so a
- * reader sees it's a folder of N files.
- *
- * @param {Object} entry - an OUTPUT_SCHEMA value
- * @returns {string} e.g. "2-plan/spec.md" or "2-plan/usecases/UC-{nn}-{slug}.md"
- */
-export function getSchemaDisplayPath(entry) {
-  return entry.multi
-    ? `${entry.phaseDir}/${entry.dirname}/${entry.displayFilename}`
-    : `${entry.phaseDir}/${entry.filename}`;
-}
-
 /**
  * Get the feature base directory (morph-relative, forward slashes).
  */

package/src/lib/detectors/claude-config-detector.js

@@ -115,14 +115,24 @@ export function detectClaudeConfig(targetPath) {
 /**
  * Cross-reference configured MCPs with the MCP registry's phase matrix.
  *
+ * `phaseMatrix` and `currentPhase` default rather than being required: the
+ * `init` caller passed only `mcpServers`, so `phaseMatrix[currentPhase]` threw
+ * a TypeError that `init`'s outer catch swallowed as
+ * "Claude config detection skipped" — taking `saveIntegrations` and
+ * `generateSettings` down with it, since both run after this line.
+ *
  * @param {Array<{name: string}>} mcpServers - Detected MCP server list
- * @param {Object} phaseMatrix - From mcp-registry.json → phaseMatrix
- * @param {string} currentPhase - Current morph-spec phase
+ * @param {Object} [phaseMatrix] - From framework/mcp/registry.json → phaseMatrix
+ * @param {string} [currentPhase] - Phase to look up; omit for every phase
  * @returns {{ available: string[], recommended: string[], missing: string[] }}
  */
-export function mapMcpsToPhases(mcpServers, phaseMatrix, currentPhase) {
-  const configuredNames = new Set(mcpServers.map(m => m.name.toLowerCase()));
-  const recommended = (phaseMatrix[currentPhase] || []);
+export function mapMcpsToPhases(mcpServers, phaseMatrix = {}, currentPhase = null) {
+  const configuredNames = new Set((mcpServers || []).map(m => m.name.toLowerCase()));
+  // No phase asked for → the union across every phase, deduped. That is what a
+  // caller showing "which of my MCPs this framework uses" wants.
+  const recommended = currentPhase
+    ? (phaseMatrix[currentPhase] || [])
+    : [...new Set(Object.values(phaseMatrix).flat())];
 
   return {
     available: recommended.filter(name => configuredNames.has(name)),
@@ -131,6 +141,28 @@ export function mapMcpsToPhases(mcpServers, phaseMatrix, currentPhase) {
   };
 }
 
+/**
+ * The MCP-by-phase table `init` prints: every phase that recommends at least
+ * one of the MCPs this machine actually has configured.
+ *
+ * Separate from `mapMcpsToPhases` because the caller wants a per-phase
+ * breakdown, not one phase's slice — reaching for the wrong one is what
+ * produced `Object.entries()` over `{available, recommended, missing}` and a
+ * `.map(m => m.name)` over plain strings.
+ *
+ * @param {Array<{name: string}>} mcpServers
+ * @param {Object} phaseMatrix
+ * @returns {Array<{phase: string, available: string[]}>} phases with ≥1 match
+ */
+export function mcpAvailabilityByPhase(mcpServers, phaseMatrix = {}) {
+  return Object.keys(phaseMatrix)
+    .map(phase => ({
+      phase,
+      available: mapMcpsToPhases(mcpServers, phaseMatrix, phase).available,
+    }))
+    .filter(({ available }) => available.length > 0);
+}
+
 /**
  * Format a human-readable one-liner summary of detected config.
  *

package/src/lib/generators/architecture-scanner.js

@@ -16,6 +16,7 @@
 
 import fs from 'fs/promises';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import { existsSync, readFileSync } from 'fs';
 import { renderTemplate } from '../../core/templates/template-renderer.js';
 
@@ -469,14 +470,29 @@ function resolveTemplatePath(projectPath, templateRelPath) {
 
   // 2. CLI package framework/ (for running from source or during init)
   const cliFramework = path.join(
-    path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')),
-    '..', '..', '..', 'framework', 'templates', templateRelPath
+    cliRootDir(), 'framework', 'templates', templateRelPath
   );
   if (existsSync(cliFramework)) return cliFramework;
 
   return null;
 }
 
+/**
+ * The CLI package root, as a real filesystem path.
+ *
+ * fileURLToPath, not `new URL(...).pathname`: the latter leaves the path
+ * percent-encoded, so an install under a directory with a space resolved to
+ * ".../Program%20Files/..." — a path that never exists. `resolveTemplatePath`
+ * then returned null and the caller fell through to its plain-text fallback
+ * WITHOUT any warning. The first lines of that fallback are identical to the
+ * template's, which is why nobody noticed the tables were gone. On Windows a
+ * global npm install lives under a spaced path by default, so this was the
+ * common case, not the edge one.
+ */
+function cliRootDir() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+}
+
 /**
  * Render architecture context to .morph/context/README.md
  *
@@ -509,10 +525,7 @@ export async function renderArchitectureContext(projectPath, scanResult, options
   // Get morph-spec version
   let morphVersion = 'unknown';
   try {
-    const pkgPath = path.join(
-      path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')),
-      '..', '..', '..', 'package.json'
-    );
+    const pkgPath = path.join(cliRootDir(), 'package.json');
     if (existsSync(pkgPath)) {
       morphVersion = JSON.parse(readFileSync(pkgPath, 'utf8')).version;
     }

package/src/lib/validators/architecture/architecture-validator.js

@@ -8,6 +8,7 @@
  */
 
 import { readFileSync } from 'fs';
+import { join } from 'path';
 import chalk from 'chalk';
 
 /**
@@ -76,6 +77,11 @@ export class ArchitectureValidator {
       totalIssues: allIssues.length,
       errors: allIssues.filter(i => i.level === 'error').length,
       warnings: allIssues.filter(i => i.level === 'warning').length,
+      // Top-level too, not only nested under `results`: the runner reports
+      // "❌ 2 error(s)" from the counts but prints the issue list, and reading
+      // only the top level meant a failure arrived with no file, no line and
+      // no fix — impossible to act on.
+      issues: allIssues,
       results
     };
   }
@@ -84,7 +90,12 @@ export class ArchitectureValidator {
    * Validate Program.cs
    */
   async validateProgramCs() {
-    const programCsPath = 'Program.cs';
+    // Resolved against `projectPath`, not the cwd. The constructor stored
+    // `projectPath` and nothing ever read it, so this validator inspected
+    // whatever directory the process happened to be in — in a worktree or a
+    // fleet run that is a different project, and reporting "no Program.cs,
+    // nothing to check" reads exactly like a pass.
+    const programCsPath = join(this.projectPath, 'Program.cs');
 
     try {
       const content = readFileSync(programCsPath, 'utf-8');

package/src/lib/validators/contracts/contract-compliance-validator.js

@@ -11,7 +11,7 @@ import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { glob } from 'glob';
 import chalk from 'chalk';
-import { getAbsoluteOutputPath } from '../../../core/paths/output-schema.js';
+import { getAbsoluteOutputPath, resolveContractsOutputType } from '../../../core/paths/output-schema.js';
 
 /**
  * Validate that contracts.cs interfaces are implemented in project code
@@ -22,7 +22,12 @@ import { getAbsoluteOutputPath } from '../../../core/paths/output-schema.js';
  * @returns {Object} { status, errors, warnings, issues, coverage }
  */
 export async function validateContracts(projectPath, featureName, options = {}) {
-  const contractsPath = getAbsoluteOutputPath(projectPath, featureName, 'contracts');
+  // `'contracts'` is not an output type — `getAbsoluteOutputPath` threw
+  // "Unknown output type" on every call. The runner already resolves this the
+  // right way before deciding to schedule this validator
+  // (`resolveContractsOutputType()`); using the same resolver here is what
+  // keeps the two from disagreeing again.
+  const contractsPath = getAbsoluteOutputPath(projectPath, featureName, resolveContractsOutputType());
 
   if (!existsSync(contractsPath)) {
     return {

package/src/lib/validators/packages/package-validator.js

@@ -8,6 +8,7 @@
  */
 
 import { readFileSync } from 'fs';
+import { join } from 'path';
 import { glob } from 'glob';
 import chalk from 'chalk';
 
@@ -82,11 +83,17 @@ export class PackageValidator {
     }
 
     const results = [];
+    const allIssues = [];
 
     for (const file of csprojFiles) {
-      const result = await this.validateFile(file);
+      // glob returns paths relative to `cwd: this.projectPath`, so they only
+      // resolve against projectPath — reading them relative to process.cwd()
+      // raised ENOENT whenever the two differed (worktree, fleet, a verify
+      // launched from the primary root), and the throw read as a clean pass.
+      const result = await this.validateFile(join(this.projectPath, file));
       if (result.issues.length > 0) {
         results.push({ file, ...result });
+        allIssues.push(...result.issues.map(i => ({ ...i, file })));
       }
     }
 
@@ -94,6 +101,12 @@ export class PackageValidator {
       status: results.length === 0 ? 'ok' : 'error',
       totalFiles: csprojFiles.length,
       filesWithIssues: results.length,
+      // The runner's contract. Without these three the findings below were
+      // read as `errors: 0` and the run reported "✅ All validations passed"
+      // while holding a list of NuGet packages that do not build on .NET 10.
+      errors: allIssues.filter(i => i.level === 'error').length,
+      warnings: allIssues.filter(i => i.level === 'warning').length,
+      issues: allIssues,
       results
     };
   }

package/src/lib/validators/validation-runner.js

@@ -107,27 +107,34 @@ export async function runValidation(projectPath, featureName, options = {}) {
       const validatorResult = await runSingleValidator(validatorId, projectPath, featureName, validatorOptions);
 
       if (validatorResult) {
-        result.errors += validatorResult.errors || 0;
-        result.warnings += validatorResult.warnings || 0;
-
-        if (validatorResult.issues) {
-          result.issues.push(...validatorResult.issues);
-        }
+        const { errors, warnings, issues } = normalizeValidatorResult(validatorId, validatorResult);
+        result.errors += errors;
+        result.warnings += warnings;
+        result.issues.push(...issues);
 
         // Store per-validator results for hooks
-        result.results[validatorId] = {
-          passed: (validatorResult.errors || 0) === 0,
-          issues: validatorResult.issues || []
-        };
+        result.results[validatorId] = { passed: errors === 0, issues };
       }
     } catch (err) {
+      // A validator that throws is a FAILED validation, not a silent skip.
+      // This used to record `passed: false` in `results` and stop there —
+      // `result.errors` never moved, so `result.passed = errors === 0` stayed
+      // true and the run reported "✅ All validations passed". The only trace
+      // was a console line, and `verify` silences stdout. That is how a broken
+      // import (`css`) and a path bug (`packages` under a different cwd) went
+      // unnoticed: both threw, both read as clean.
       if (options.verbose) {
         console.log(chalk.yellow(`  ⚠ Validator '${validatorId}' failed: ${err.message}`));
       }
-      result.results[validatorId] = {
-        passed: false,
-        error: err.message
+      result.errors += 1;
+      const issue = {
+        level: 'error',
+        validator: validatorId,
+        message: `Validator '${validatorId}' crashed: ${err.message}`,
+        fix: 'This is a bug in the validator itself — the code under test was never checked.'
       };
+      result.issues.push(issue);
+      result.results[validatorId] = { passed: false, error: err.message, issues: [issue] };
     }
   }
 
@@ -160,6 +167,68 @@ function detectValidators(projectPath = '.') {
   return [...profile.defaultValidators];
 }
 
+/**
+ * Reduce any validator's return value to the runner's contract:
+ * `{ errors, warnings, issues }`.
+ *
+ * Validators were written at different times and return different shapes. The
+ * runner used to read `errors`/`warnings`/`issues` off the raw object, so a
+ * validator that reports through any other shape contributed ZERO — and since
+ * `passed = errors === 0`, its findings were recorded as a pass. Measured: of
+ * seven validators only two returned all three keys. `packages` — one of the
+ * two defaults for the `dotnet` stack — returned
+ * `{status, totalFiles, filesWithIssues, results}` and had every NuGet
+ * incompatibility it found thrown away, while `verify` reported 10/10.
+ *
+ * Reading the nested `results` shape here keeps that contract in ONE place
+ * instead of asking every validator to remember it.
+ *
+ * @param {string} validatorId
+ * @param {Object} raw - whatever the validator returned
+ * @returns {{errors: number, warnings: number, issues: Array}}
+ */
+export function normalizeValidatorResult(validatorId, raw) {
+  if (!raw || typeof raw !== 'object') return { errors: 0, warnings: 0, issues: [] };
+
+  // Issues can be top-level, or nested one level under `results` — either as
+  // an array of `{issues}` (packages: one entry per .csproj) or an object of
+  // them (architecture: keyed by check name). The nested read is a FALLBACK,
+  // never additive: validators that expose both would otherwise report every
+  // finding twice.
+  const topLevel = Array.isArray(raw.issues) ? raw.issues : [];
+  const nested = raw.results && typeof raw.results === 'object'
+    ? (Array.isArray(raw.results) ? raw.results : Object.values(raw.results))
+        .flatMap(r => (r && Array.isArray(r.issues)) ? r.issues : [])
+    : [];
+  const issues = (topLevel.length ? topLevel : nested)
+    .map(i => ({ validator: validatorId, ...i }));
+
+  // Prefer the validator's own counts when it reports them — it may weigh
+  // issues differently than one-each. Otherwise derive from the issue levels.
+  const counted = {
+    errors: issues.filter(i => i.level === 'error').length,
+    warnings: issues.filter(i => i.level === 'warning').length,
+  };
+  const errors = Number.isFinite(raw.errors) ? raw.errors : counted.errors;
+  const warnings = Number.isFinite(raw.warnings) ? raw.warnings : counted.warnings;
+
+  // Last resort: a validator that says `status: 'error'` but exposes no
+  // countable detail still must not read as a pass.
+  if (errors === 0 && raw.status === 'error') {
+    return {
+      errors: 1,
+      warnings,
+      issues: issues.length ? issues : [{
+        level: 'error',
+        validator: validatorId,
+        message: raw.message || `${validatorId} reported status "error" without detail`,
+      }],
+    };
+  }
+
+  return { errors, warnings, issues };
+}
+
 /**
  * Run a single validator by ID
  */
@@ -181,8 +250,10 @@ async function runSingleValidator(validatorId, projectPath, featureName, options
     }
 
     case 'css': {
-      const { validateCss } = await import('./css/css-validator.js');
-      return await validateCss(projectPath, options);
+      // The module exports `validateCssClasses`; this asked for `validateCss`,
+      // which is undefined — the call threw on every invocation.
+      const { validateCssClasses } = await import('./css/css-validator.js');
+      return await validateCssClasses(projectPath, options);
     }
 
     case 'contract-compliance': {
@@ -201,10 +272,24 @@ async function runSingleValidator(validatorId, projectPath, featureName, options
     }
 
     default:
+      // A warning, not silence: an id with no case runs nothing, and returning
+      // a bare null made that indistinguishable from a validator that ran and
+      // found nothing. A typo in a validator list would have read as a clean
+      // pass. Not an error — an unknown id is a configuration mistake, not a
+      // defect in the code under validation.
       if (options.verbose) {
         console.log(chalk.gray(`  Unknown validator: ${validatorId}`));
       }
-      return null;
+      return {
+        status: 'ok',
+        errors: 0,
+        warnings: 1,
+        issues: [{
+          level: 'warning',
+          message: `Unknown validator '${validatorId}' — nothing was run for it`,
+          fix: 'Check the validator id against the cases in runSingleValidator().',
+        }],
+      };
   }
 }