@polymorphism-tech/morph-spec 4.15.0 → 4.17.0

package/framework/workflows/README.md

@@ -649,7 +649,7 @@ Add stack-specific conditions in config:
       "blazor-azure": {
         "minFiles": 5
       },
-      "nextjs-supabase": {
+      "nextjs-neon": {
         "minFiles": 3
       }
     }

package/framework/workflows/docs/full-morph.md

@@ -1,69 +1,69 @@
-# Workflow: FULL (Alta Complexidade)
-
-> **Layer:** 1 | **Load:** on-keyword | **Keywords:** sistema, integração, arquitetura, migração, infraestrutura, plataforma
-
-## Critérios
-
-- > 10 arquivos, > 500 linhas, múltiplos componentes novos
-- Infraestrutura, decisões arquiteturais estratégicas, multi-domínio
-
-## Fases (TODAS obrigatórias)
-
-### FASE 0: PROPOSAL
-1. Analisar solicitação, identificar stack, estimar complexidade
-2. Gerar proposal.md, registrar agentes no state.json
-3. Avaliar complexidade → recomendar workflow full
-- **⛔ PAUSA:** Aprovar proposta?
-
-### FASE 1: UI/UX (condicional — se keywords UI detectadas)
-1. **Perguntar ao usuário:** layout, referências visuais, fluxo, imagens
-2. Analisar referências fornecidas
-3. Gerar deliverables (design-system, mockups, components, flows)
-4. Validar acessibilidade (WCAG 2.1) e responsividade
-- **⛔ PAUSA:** Aprovar UI/UX?
-
-### FASE 2: DESIGN (com clarificação integrada)
-1. Scan real do schema (Supabase MCP, EF Core, TypeScript)
-2. Validar schema com usuário (CHECKPOINT 1)
-3. Gerar blueprint arquitetural (CHECKPOINT 2)
-4. Gerar spec.md, contracts.cs/.ts, schema-analysis.md, decisions.md
-5. **Quality + Satisfaction scoring** (0-100):
-   - Quality: schema fidelity, functional coverage, blueprint, integrations, infra
-   - Satisfaction: functional completeness, failure coverage, edge cases, clarity, contracts
-6. Loop de refinamento: perguntas → atualizar spec.md direto → re-score
-7. Sai quando score ≥ 85 E usuário aprova
-- **⛔ PAUSA:** Aprovar design?
-
-### FASE 3: PLAN
-1. Ler spec + contracts + decisions
-2. Analisar codebase existente (Glob + Grep)
-3. Determinar estratégia de execução (single/subagents/agent-teams)
-4. Gerar plan.md com tasks cross-referenciando FRs
-- **⛔ PAUSA:** Aprovar plano?
-
-### FASE 4: TASKS
-1. Quebrar spec em tasks T001-TXXX com [FR refs]
-2. Definir ordem, checkpoints, dependências
-- **⛔ PAUSA:** Aprovar tasks?
-
-### FASE 5: IMPLEMENT
-1. Para cada task: ler spec FRs → ler contracts → implementar → verificar
-2. `morph-spec task done {feature} {task-id}` após cada task
-3. Checkpoints automáticos a cada 3 tasks
-4. Gerar recap.md ao final
-
-### FASE 6: SYNC
-1. Revisar decisions.md, categorizar
-2. Promover para `.morph/context/{category}.md`
-3. Gerar commit dedicado de sync
-- **⛔ PAUSA:** Aprovar promoção de decisões?
-
-## Outputs Completos
-proposal.md, design-system.md, mockups.md, components.md, flows.md, spec.md, contracts.cs/.ts, schema-analysis.md, decisions.md, plan.md, tasks.md, recap.md
-
-## Exemplos
-- "Sistema de relatórios com jobs agendados Hangfire"
-- "Autenticação completa com Clerk (login, signup, OAuth)"
-- "Dashboard com gráficos, tabelas e filtros complexos"
-- "RAG pipeline com AI Search e embeddings"
-- "Infraestrutura completa com Docker/Easypanel"
+# Workflow: FULL (Alta Complexidade)
+
+> **Layer:** 1 | **Load:** on-keyword | **Keywords:** sistema, integração, arquitetura, migração, infraestrutura, plataforma
+
+## Critérios
+
+- > 10 arquivos, > 500 linhas, múltiplos componentes novos
+- Infraestrutura, decisões arquiteturais estratégicas, multi-domínio
+
+## Fases (TODAS obrigatórias)
+
+### FASE 0: PROPOSAL
+1. Analisar solicitação, identificar stack, estimar complexidade
+2. Gerar proposal.md, registrar agentes no state.json
+3. Avaliar complexidade → recomendar workflow full
+- **⛔ PAUSA:** Aprovar proposta?
+
+### FASE 1: UI/UX (condicional — se keywords UI detectadas)
+1. **Perguntar ao usuário:** layout, referências visuais, fluxo, imagens
+2. Analisar referências fornecidas
+3. Gerar deliverables (design-system, mockups, components, flows)
+4. Validar acessibilidade (WCAG 2.1) e responsividade
+- **⛔ PAUSA:** Aprovar UI/UX?
+
+### FASE 2: DESIGN (com clarificação integrada)
+1. Scan real do schema (Neon/psql, EF Core, TypeScript)
+2. Validar schema com usuário (CHECKPOINT 1)
+3. Gerar blueprint arquitetural (CHECKPOINT 2)
+4. Gerar spec.md, contracts.cs/.ts, schema-analysis.md, decisions.md
+5. **Quality + Satisfaction scoring** (0-100):
+   - Quality: schema fidelity, functional coverage, blueprint, integrations, infra
+   - Satisfaction: functional completeness, failure coverage, edge cases, clarity, contracts
+6. Loop de refinamento: perguntas → atualizar spec.md direto → re-score
+7. Sai quando score ≥ 85 E usuário aprova
+- **⛔ PAUSA:** Aprovar design?
+
+### FASE 3: PLAN
+1. Ler spec + contracts + decisions
+2. Analisar codebase existente (Glob + Grep)
+3. Determinar estratégia de execução (single/subagents/agent-teams)
+4. Gerar plan.md com tasks cross-referenciando FRs
+- **⛔ PAUSA:** Aprovar plano?
+
+### FASE 4: TASKS
+1. Quebrar spec em tasks T001-TXXX com [FR refs]
+2. Definir ordem, checkpoints, dependências
+- **⛔ PAUSA:** Aprovar tasks?
+
+### FASE 5: IMPLEMENT
+1. Para cada task: ler spec FRs → ler contracts → implementar → verificar
+2. `morph-spec task done {feature} {task-id}` após cada task
+3. Checkpoints automáticos a cada 3 tasks
+4. Gerar recap.md ao final
+
+### FASE 6: SYNC
+1. Revisar decisions.md, categorizar
+2. Promover para `.morph/context/{category}.md`
+3. Gerar commit dedicado de sync
+- **⛔ PAUSA:** Aprovar promoção de decisões?
+
+## Outputs Completos
+proposal.md, design-system.md, mockups.md, components.md, flows.md, spec.md, contracts.cs/.ts, schema-analysis.md, decisions.md, plan.md, tasks.md, recap.md
+
+## Exemplos
+- "Sistema de relatórios com jobs agendados Hangfire"
+- "Autenticação completa com Clerk (login, signup, OAuth)"
+- "Dashboard com gráficos, tabelas e filtros complexos"
+- "RAG pipeline com AI Search e embeddings"
+- "Infraestrutura completa com Docker/Easypanel"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "4.15.0",
+  "version": "4.17.0",
   "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
   "keywords": [
     "claude-code",

package/src/commands/agents/dispatch-agents.js

@@ -40,7 +40,7 @@ const AGENTS_JSON_PATH = join(__dirname, '../../../framework/agents.json');
 const PHASES_JSON_PATH = join(__dirname, '../../../framework/phases.json');
 
 /** Phases where agent dispatch is meaningful */
-const DISPATCHABLE_PHASES = ['design', 'tasks', 'implement'];
+const DISPATCHABLE_PHASES = ['design', 'plan', 'tasks', 'implement'];
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Required Skills Injection
@@ -238,7 +238,7 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
   // Collect dispatchable agents
   const isValidateMode = opts.mode === 'validate';
   const processed = new Set();
-  const dispatchableAgents = [];
+  let dispatchableAgents = [];
 
   const candidateIds = [
     ...activeAgentIds,
@@ -304,6 +304,23 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
     return a.id.localeCompare(b.id);
   });
 
+  // Pre-flight: check agent files exist, skip missing (BUG-001)
+  const warnings = [];
+  const verifiedAgents = [];
+  for (const agent of dispatchableAgents) {
+    const agentFile = join(projectPath, '.claude', 'agents', `${agent.subagentType}.md`);
+    if (!existsSync(agentFile)) {
+      warnings.push({
+        agentId: agent.id,
+        subagentType: agent.subagentType,
+        message: `File .claude/agents/${agent.subagentType}.md not found — agent skipped from dispatch`,
+      });
+    } else {
+      verifiedAgents.push(agent);
+    }
+  }
+  dispatchableAgents = verifiedAgents;
+
   const shouldDispatch = dispatchableAgents.length >= 2;
 
   // ── Recommended agents by group ───────────────────────────────────────────
@@ -320,19 +337,6 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
     tasks = parseAndGroupTasks(tasksPath);
   }
 
-  // ── Pre-flight: check agent files exist ──────────────────────────────────
-  const warnings = [];
-  for (const agent of dispatchableAgents) {
-    const agentFile = join(projectPath, '.claude', 'agents', `${agent.subagentType}.md`);
-    if (!existsSync(agentFile)) {
-      warnings.push({
-        agentId: agent.id,
-        subagentType: agent.subagentType,
-        message: `File .claude/agents/${agent.subagentType}.md not found`,
-      });
-    }
-  }
-
   return {
     feature: featureName,
     phase,

package/src/commands/project/setup-infra-cmd.js

@@ -4,7 +4,7 @@ import { logger } from '../../utils/logger.js';
 export async function setupInfraCommand(options) {
   const targetPath = options.path || process.cwd();
   try {
-    await setupInfra(targetPath);
+    await setupInfra(targetPath, { reinstall: options.reinstall ?? false });
   } catch (err) {
     logger.error(`setup-infra failed: ${err.message}`);
     process.exit(1);

package/src/commands/state/advance-phase.js

@@ -128,6 +128,11 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
 
       // Skip uiux if no UI design agents are active
       if (candidate === 'uiux') {
+        if (feature.workflow === 'migration' || feature.workflow === 'refactor') {
+          console.log(chalk.gray(`  ⏩ Skipping ${candidate}: ${feature.workflow} workflow — no visual changes`));
+          skippedPhases.push(candidate);
+          continue;
+        }
         const hasUiDesignAgent = feature.activeAgents?.some(a => uiDesignAgents.includes(a));
         if (!hasUiDesignAgent && skipOptional !== false) {
           console.log(chalk.gray(`  ⏩ Skipping ${candidate}: no UI design agents active`));

package/src/commands/tasks/task.js

@@ -42,6 +42,7 @@ export async function taskDoneCommand(featureName, taskIds, options) {
   try {
     const args = ['done', featureName, ...taskIds];
     if (options.skipValidation) args.push('--skip-validation');
+    if (options.skipBuild) args.push('--skip-build');
     if (options.reason) args.push('--reason', options.reason);
     if (options.note) args.push('--note', options.note);
     if (options.dryRun) args.push('--dry-run');
@@ -76,6 +77,7 @@ export async function taskBulkDoneCommand(featureName, range, options) {
     if (options.from) args.push('--from', options.from);
     if (options.to) args.push('--to', options.to);
     if (options.skipValidation) args.push('--skip-validation');
+    if (options.skipBuild) args.push('--skip-build');
     if (options.reason) args.push('--reason', options.reason);
     if (options.note) args.push('--note', options.note);
     if (options.dryRun) args.push('--dry-run');
@@ -93,6 +95,7 @@ export async function taskAnnotateCommand(featureName, taskId, text, options) {
   try {
     const args = ['annotate', featureName, taskId, text];
     if (options.type) args.push('--type', options.type);
+    if (options.markDone) args.push('--mark-done');
     await executeTaskManager(args);
   } catch (error) {
     console.error(chalk.red(`Error: ${error.message}`));

package/src/core/state/state-manager.js

@@ -5,7 +5,7 @@
  * Used both by CLI commands and internal automation.
  */
 
-import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync, rmdirSync, statSync } from 'fs';
 import { join, dirname } from 'path';
 import { detectWorkflow } from '../workflows/workflow-detector.js';
 import { getAllOutputPaths, getOutputPath } from '../paths/output-schema.js';
@@ -163,6 +163,50 @@ export function saveState(state) {
   }
 }
 
+// ============================================================================
+// File Locking (BUG-002)
+// ============================================================================
+
+const LOCK_DIR_NAME = '.morph/state.json.lock';
+const LOCK_MAX_RETRIES = 5;
+const LOCK_BASE_MS = 100;
+const LOCK_STALE_MS = 30_000;
+
+/**
+ * Wrap a read-modify-write cycle on state.json with a mkdir-based mutex.
+ * @param {Function} fn - Async function to execute while holding the lock
+ * @returns {Promise<*>} Return value of fn
+ */
+export async function withStateLock(fn) {
+  const lockPath = join(process.cwd(), LOCK_DIR_NAME);
+
+  for (let attempt = 0; attempt <= LOCK_MAX_RETRIES; attempt++) {
+    try {
+      mkdirSync(lockPath);
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const lockStat = statSync(lockPath);
+        if (Date.now() - lockStat.mtimeMs > LOCK_STALE_MS) {
+          try { rmdirSync(lockPath); } catch { }
+          continue;
+        }
+      } catch { }
+      if (attempt === LOCK_MAX_RETRIES) {
+        throw new Error('Could not acquire state lock after retries');
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_BASE_MS * (2 ** attempt));
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    try { rmdirSync(lockPath); } catch { }
+  }
+}
+
 /**
  * Initialize new state file
  * @param {Object} options - Options

package/src/core/templates/template-registry.js

@@ -108,7 +108,7 @@ export function getTemplatesByPhase(phase, projectPath = null) {
 /**
  * Get templates by stack.
  *
- * @param {string} stackId - Stack identifier ('blazor-azure', 'nextjs-supabase')
+ * @param {string} stackId - Stack identifier ('blazor-azure', 'nextjs-neon')
  * @param {string} [projectPath] - Optional project path
  * @returns {Array} Filtered template array (includes universal + stack-specific)
  */
@@ -226,28 +226,6 @@ export function searchTemplates(keyword, projectPath = null) {
   });
 }
 
-/**
- * Get registry statistics.
- *
- * @param {string} [projectPath] - Optional project path
- * @returns {Object} Statistics object
- */
-export function getRegistryStats(projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.stats || {};
-}
-
-/**
- * Validate that a template exists in the registry.
- *
- * @param {string} templateId - Template identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {boolean} True if template exists
- */
-export function templateExists(templateId, projectPath = null) {
-  return getTemplateById(templateId, projectPath) !== null;
-}
-
 /**
  * Get template absolute path with fallback logic.
  *
@@ -276,46 +254,3 @@ export function resolveTemplatePathById(templateId, projectPath) {
   return existsSync(frameworkPath) ? frameworkPath : null;
 }
 
-/**
- * List all template IDs.
- *
- * @param {string} [projectPath] - Optional project path
- * @returns {string[]} Array of template IDs
- */
-export function listTemplateIds(projectPath = null) {
-  const templates = getAllTemplates(projectPath);
-  return templates.map(t => t.id);
-}
-
-/**
- * Get templates that use Handlebars engine.
- *
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Templates using Handlebars
- */
-export function getHandlebarsTemplates(projectPath = null) {
-  const templates = getAllTemplates(projectPath);
-  return templates.filter(t => t.engine === 'handlebars');
-}
-
-/**
- * Get templates that use custom engine (need migration).
- *
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Templates using custom engine
- */
-export function getCustomEngineTemplates(projectPath = null) {
-  const templates = getAllTemplates(projectPath);
-  return templates.filter(t => t.engine === 'custom');
-}
-
-/**
- * Get deprecated templates.
- *
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Deprecated templates
- */
-export function getDeprecatedTemplates(projectPath = null) {
-  const templates = getAllTemplates(projectPath);
-  return templates.filter(t => t.deprecated === true);
-}

package/src/lib/detectors/index.js

@@ -71,8 +71,8 @@ export function detectProject(targetPath, opts = {}) {
       }
 
       // Integrations
-      if (depNames.includes('@supabase/supabase-js') || depNames.includes('@supabase/ssr')) {
-        structure.integrations.push('supabase');
+      if (depNames.includes('@neondatabase/serverless') || depNames.includes('postgres') || depNames.includes('pg')) {
+        structure.integrations.push('neon');
       }
       if (depNames.includes('@clerk/nextjs') || depNames.includes('@clerk/clerk-sdk-node')) {
         structure.integrations.push('clerk');