@polymorphism-tech/morph-spec 8.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.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.9.0"
+cliVersion: "8.10.0"
 ---
 
 # morph-standards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.9.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

@@ -647,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();

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/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().',
+        }],
+      };
   }
 }