@polymorphism-tech/morph-spec 8.9.0 → 8.11.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.11.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.11.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.9.0",
+  "version": "8.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.0"
 ---
 
 # morph-standards

package/package.json

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

package/src/commands/mcp/mcp-setup.js

@@ -34,8 +34,13 @@ import { detectProject } from '../../lib/detectors/index.js';
 /**
  * Detect the current project's stack.
  * Prefers .morph/config/config.json (set during morph-spec init) over filesystem re-detection.
+ *
+ * Exported for testing: the stack decides which MCPs are relevant, and it is
+ * the one branch here worth pinning — `.morph/config/config.json` is the only
+ * place a compound stack (`dotnet-nextjs`) survives, since filesystem
+ * re-detection collapses it to whichever half it notices first.
  */
-async function detectStack(targetPath) {
+export async function detectStack(targetPath) {
   // 1. Prefer the authoritative config (handles compound stacks like nextjs+dotnet)
   try {
     const configPath = join(targetPath, '.morph', 'config', 'config.json');

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/core/templates/template-registry.js

@@ -151,65 +151,6 @@ export function getRequiredTemplates(stackId = null, projectPath = null) {
   return templates;
 }
 
-/**
- * Get infrastructure templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Infrastructure template array
- */
-export function getInfrastructureTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.infrastructureTemplates?.[stackId] || [];
-}
-
-/**
- * Get contract templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Contract template array
- */
-export function getContractTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.contractTemplates?.[stackId] || [];
-}
-
-/**
- * Get integration templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Integration template array
- */
-export function getIntegrationTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.integrationTemplates?.[stackId] || [];
-}
-
-/**
- * Get SaaS templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} SaaS template array
- */
-export function getSaasTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.saasTemplates?.[stackId] || [];
-}
-
-/**
- * Get example templates.
- *
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Example template array
- */
-export function getExampleTemplates(projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.exampleTemplates || [];
-}
-
 /**
  * Search templates by keyword (searches id, name, description).
  *

package/src/dashboard/scanner/hooks-scanner.js

@@ -1,5 +1,6 @@
 import { readFileSync, readdirSync, existsSync } from 'fs';
-import { join, basename, dirname } from 'path';
+import { join, basename } from 'path';
+import { getHookDefinitions } from '../../utils/hooks-installer.js';
 
 function findJsFiles(dir) {
   const results = [];
@@ -25,17 +26,74 @@ function extractImports(source) {
   return imports;
 }
 
+/**
+ * Claude Code event name → the kebab-case key the Hook Inspector groups by.
+ * `pre-compact` and `teammate-idle` have no MORPH hooks — those nodes render
+ * empty on purpose.
+ */
+const EVENT_KEYS = {
+  SessionStart: 'session-start',
+  UserPromptSubmit: 'user-prompt',
+  PreToolUse: 'pre-tool-use',
+  PostToolUse: 'post-tool-use',
+  Stop: 'stop',
+  SubagentStop: 'stop',
+  PreCompact: 'pre-compact',
+};
+
+/**
+ * Build filename → [{ event, matcher }] from the installer's MORPH_HOOKS.
+ *
+ * The event is NOT derivable from the path. Before the v4→v5 migration the
+ * hooks sat in per-event folders, so `basename(dirname(file))` produced the
+ * event key; the migration flattened everything into `core/`, and from then on
+ * every hook reported `event: 'core'`. Nothing crashed — the Inspector groups
+ * by event, found no key it knew, and rendered every node empty. Twelve hooks,
+ * zero shown.
+ *
+ * `getHookDefinitions()` is the single source of truth (the same array the
+ * installer writes into settings.local.json), so the registration and the
+ * drawing can no longer disagree.
+ */
+export function hookRegistrations(definitions = getHookDefinitions()) {
+  const byFile = new Map();
+  for (const def of definitions) {
+    const key = EVENT_KEYS[def.event];
+    if (!key) continue;
+    for (const h of def.hooks || []) {
+      const file = basename(String(h.command || '').trim());
+      if (!file.endsWith('.js')) continue;
+      if (!byFile.has(file)) byFile.set(file, []);
+      byFile.get(file).push({ event: key, rawEvent: def.event, matcher: def.matcher || null });
+    }
+  }
+  return byFile;
+}
+
 export function scanHooks(frameworkDir) {
   const hooksDir = join(frameworkDir, 'hooks', 'claude-code');
   if (!existsSync(hooksDir)) return [];
-  return findJsFiles(hooksDir).map(filePath => {
+
+  const registrations = hookRegistrations();
+
+  return findJsFiles(hooksDir).flatMap(filePath => {
     const source = readFileSync(filePath, 'utf8');
-    return {
-      event: basename(dirname(filePath)),
+    const filename = basename(filePath);
+    const base = {
       name: basename(filePath, '.js'),
-      filename: basename(filePath),
-      source, imports: extractImports(source),
+      filename,
+      source,
+      imports: extractImports(source),
       description: extractJsDocDescription(source),
     };
+
+    // One entry per (file × event): telemetry-log is registered on both
+    // PostToolUse and UserPromptSubmit, and must show under both.
+    const regs = registrations.get(filename);
+    if (!regs || regs.length === 0) {
+      // On disk but never registered — real dead weight, and worth seeing.
+      return [{ ...base, event: 'unregistered', matcher: null }];
+    }
+    return regs.map(r => ({ ...base, event: r.event, rawEvent: r.rawEvent, matcher: r.matcher }));
   });
 }

package/src/dashboard/scanner/standards-scanner.js

@@ -7,9 +7,21 @@ export function scanStandards(frameworkDir, agents) {
   const sJson = JSON.parse(readFileSync(standardsJsonPath, 'utf8'));
   const refMap = {};
   for (const agent of agents) {
-    for (const std of agent.standards) {
-      if (!refMap[std.id]) refMap[std.id] = [];
-      refMap[std.id].push({ agentId: agent.id, scope: std.scope, priority: std.priority });
+    for (const std of agent.standards || []) {
+      // agents.json stores standards as plain id STRINGS. Reading `std.id` off
+      // a string yields undefined, so every reference piled into refMap
+      // [undefined] and the lookup below missed all 60 — the Standards graph
+      // drew standards with no agent edge at all. The object form is the v4
+      // shape (`{ id, scope, priority }`); still accepted so a mixed or
+      // restored agents.json does not silently lose edges again.
+      const id = typeof std === 'string' ? std : std?.id;
+      if (!id) continue;
+      if (!refMap[id]) refMap[id] = [];
+      refMap[id].push({
+        agentId: agent.id,
+        scope: typeof std === 'string' ? null : (std.scope ?? null),
+        priority: typeof std === 'string' ? null : (std.priority ?? null),
+      });
     }
   }
   const list = sJson.standards.map(std => {

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/stack/stack-profile.js

@@ -9,7 +9,6 @@ import { join } from 'path';
  * @property {boolean} isDotnet
  * @property {boolean} isNextjs
  * @property {string[]} defaultValidators
- * @property {string[]} checkpointValidators
  * @property {string|null} buildCommand
  */
 
@@ -21,19 +20,16 @@ const PROFILES = {
   dotnet: {
     isDotnet: true, isNextjs: false,
     defaultValidators: ['architecture', 'packages'],
-    checkpointValidators: ['architecture', 'packages', 'design-system', 'security'],
     buildCommand: 'dotnet build --no-restore',
   },
   nextjs: {
     isDotnet: false, isNextjs: true,
     defaultValidators: ['nextjs-component'],
-    checkpointValidators: ['nextjs-component', 'css'],
     buildCommand: 'npx tsc --noEmit',
   },
   empty: {
     isDotnet: false, isNextjs: false,
     defaultValidators: [],
-    checkpointValidators: [],
     buildCommand: null,
   },
 };
@@ -57,7 +53,6 @@ function mergeProfiles(profiles) {
     isDotnet: profiles.some((p) => p.isDotnet),
     isNextjs: profiles.some((p) => p.isNextjs),
     defaultValidators: [...new Set(profiles.flatMap((p) => p.defaultValidators))],
-    checkpointValidators: [...new Set(profiles.flatMap((p) => p.checkpointValidators))],
     buildCommand: profiles.map((p) => p.buildCommand).find(Boolean) ?? null,
   };
 }

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

@@ -16,7 +16,11 @@ import { aggregateScores, loadRubric } from './score-aggregator.js';
 
 /**
  * Heavy validators skipped in 'light' mode (checkpoint-only).
- * Light mode runs only spec, content, and stack-specific lightweight validators.
+ *
+ * What light mode actually leaves behind is whatever the stack contributes that
+ * is NOT in this set — in practice `contrast` and `nextjs-component`. There are
+ * no `spec` or `content` validators; the switch in runSingleValidator has no
+ * case for either, and the old comment here promised both.
  */
 const HEAVY_VALIDATORS = new Set([
   'architecture', 'packages', 'contract-compliance',
@@ -49,27 +53,38 @@ export async function runValidation(projectPath, featureName, options = {}) {
     validators: {} // No validator-specific constraints
   };
 
-  // Determine which validators to run
-  const validatorIds = options.validators || detectValidators(projectPath);
+  // Determine which validators to run.
+  // COPY: the mode filter below used to splice in place, and when the caller
+  // passed `options.validators` that array WAS this array — so a light run
+  // emptied the caller's own list, and running the same list twice validated
+  // less the second time.
+  const detected = options.validators || detectValidators(projectPath);
+  let validatorIds = [...detected];
 
   // Filter by mode: 'light' skips heavy validators, 'full' (default) runs all
   const mode = options.mode || 'full';
+  const droppedByMode = [];
   if (mode === 'light') {
-    const beforeCount = validatorIds.length;
-    for (let i = validatorIds.length - 1; i >= 0; i--) {
-      if (HEAVY_VALIDATORS.has(validatorIds[i])) {
-        validatorIds.splice(i, 1);
-      }
-    }
+    validatorIds = validatorIds.filter(id => {
+      if (HEAVY_VALIDATORS.has(id)) { droppedByMode.push(id); return false; }
+      return true;
+    });
   }
 
   // Merge constraint-enabled validators
   validatorIds.push(...constraints.enabledValidators);
 
   if (validatorIds.length === 0) {
-    result.summary = 'No validators ran — no validators configured for this stack';
-    console.log(chalk.gray('\n  ℹ️  No validators configured for this stack'));
+    // Say which of the two it is. On a pure `dotnet` project every default
+    // validator is heavy, so a light run legitimately runs none — but the old
+    // message blamed the stack ("no validators configured"), which reads as
+    // "your stack has nothing to check" when the full run has two.
+    result.summary = droppedByMode.length > 0
+      ? `No validators ran — light mode skipped ${droppedByMode.length} heavy validator(s): ${droppedByMode.join(', ')}`
+      : 'No validators ran — no validators configured for this stack';
+    console.log(chalk.gray(`\n  ℹ️  ${result.summary.replace('No validators ran — ', '')}`));
     result._skipReason = result.summary;
+    result._droppedByMode = droppedByMode;
     return result;
   }
 
@@ -87,7 +102,12 @@ export async function runValidation(projectPath, featureName, options = {}) {
     // Positive check on isDotnet (contract-compliance is a VSA/.NET concern) —
     // NOT `!isNextjs`, which used to wrongly suppress it for a compound
     // "dotnet-nextjs" stack that has a .NET backend but is ALSO isNextjs.
-    if (existsSync(contractsPath) && _profileForContracts.isDotnet) {
+    // `mode: 'light'` has to hold here too. This push sits AFTER the mode
+    // filter, so contract-compliance — which is in HEAVY_VALIDATORS — used to
+    // slip into every light run that had a contracts file, making light mode
+    // heavier than declared on exactly the compound stacks it matters for.
+    const contractsIsHeavyAndSkipped = mode === 'light' && HEAVY_VALIDATORS.has('contract-compliance');
+    if (existsSync(contractsPath) && _profileForContracts.isDotnet && !contractsIsHeavyAndSkipped) {
       validatorIds.push('contract-compliance');
     }
   }
@@ -107,27 +127,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 +187,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 +270,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 +292,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().',
+        }],
+      };
   }
 }
 

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

@@ -1,89 +0,0 @@
-import { readFileSync, existsSync } from 'fs';
-
-/**
- * Content Validator - Validates structure and content of output files
- *
- * Ensures spec.md, tasks.json, and other outputs have required sections
- * and proper structure before allowing phase transitions.
- */
-
-/**
- * Validate spec.md structure
- * @param {string} specPath - Path to spec.md file
- * @returns {Object} Validation result
- */
-export function validateSpecContent(specPath) {
-  if (!existsSync(specPath)) {
-    return {
-      valid: false,
-      missing: ['File does not exist'],
-      errors: ['Spec file not found at: ' + specPath]
-    };
-  }
-
-  const content = readFileSync(specPath, 'utf8');
-
-  // Required sections (flexible regex handles numbered variants like '## 1. Overview')
-  const requiredSections = [
-    { label: '## Overview',                pattern: /^##\s+(?:\d+\.?\s+)?Overview/i },
-    { label: '## Functional Requirements', pattern: /^##\s+(?:\d+\.?\s+)?Functional Requirements/i },
-    { label: '## Technical',              pattern: /^##\s+(?:\d+\.?\s+)?Technical/i },
-    { label: '## Data Model',             pattern: /^##\s+(?:\d+\.?\s+)?Data Model/i },
-  ];
-
-  const lines = content.split('\n');
-  const missing = requiredSections.filter(s =>
-    !lines.some(line => s.pattern.test(line))
-  );
-
-  // Additional quality checks
-  const errors = [];
-  const warnings = [];
-
-  // Missing sections are warnings, not errors — not every spec needs all sections
-  // (e.g., frontend-only features may not have Data Model, CLI tools may not have Technical Architecture)
-  if (missing.length > 0) {
-    missing.forEach(s => {
-      warnings.push(`Missing recommended section: ${s.label}`);
-    });
-  }
-
-  // Check minimum content length
-  if (content.length < 500) {
-    warnings.push('Spec seems very short (< 500 characters). Consider adding more detail.');
-  }
-
-  // Check for placeholder text that should be replaced
-  const placeholders = ['TODO', 'TBD', 'PLACEHOLDER', '{{'];
-  placeholders.forEach(placeholder => {
-    if (content.includes(placeholder)) {
-      warnings.push(`Spec contains "${placeholder}" - ensure all placeholders are replaced`);
-    }
-  });
-
-  // Check for anti-patterns mentioned in the plan
-  if (content.toLowerCase().includes('manual azure portal')) {
-    errors.push(
-      'Spec mentions manual Azure portal creation. ' +
-      'All infrastructure must be defined in Bicep (Infrastructure as Code).'
-    );
-  }
-
-  if (content.toLowerCase().includes('create resource manually')) {
-    errors.push(
-      'Spec mentions manual resource creation. ' +
-      'Use IaC (Bicep) for all infrastructure resources.'
-    );
-  }
-
-  return {
-    valid: errors.length === 0,
-    missing,
-    errors,
-    warnings,
-    sections: {
-      required: requiredSections.length,
-      found: requiredSections.length - missing.length
-    }
-  };
-}

package/src/lib/validators/content/index.js

@@ -1,7 +0,0 @@
-/**
- * Content Validators
- *
- * Content and spec validation.
- */
-
-export * from './content-validator.js';