@polymorphism-tech/morph-spec 4.12.0 → 4.14.0

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

@@ -1,76 +1,69 @@
-# Workflow: FULL MORPH (Alta Complexidade)
-
-> **Layer:** 1 | **Load:** on-keyword | **Keywords:** sistema, autenticação, integração, pattern, cqrs, subsistema
-
-## Critérios
-
-- > 10 arquivos, > 500 linhas, múltiplos componentes novos
-- Infraestrutura Azure (Bicep), decisões arquiteturais estratégicas
-
-## Fases (TODAS obrigatórias)
-
-### FASE 0.5: CONTEXT (automática)
-1. Detectar framework MORPH (`@polymorphism-tech/morph-spec`)
-2. Detectar/criar estrutura `.morph/`
-3. Análise automática: stack (glob patterns), arquitetura (pastas), configs, UI library
-4. Analisar histórico: decisions.md passados, preferências do usuário
-5. Gerar/atualizar `.morph/context/inferred.md`
-6. Ativar agentes baseado em stack + keywords
-
-### FASE 0: PROPOSAL
-1. `morph-spec detect "{user-request}"`
-2. Analisar solicitação, identificar stack, estimar complexidade
-3. Gerar proposal.md, registrar agentes no state.json
-- **⛔ PAUSA:** 3 itens (1 ação + 1 pergunta + 1 sugestão)
-
-### FASE 1: SETUP
-1. Ler `.morph/config.json`
-2. Confirmar stack, ativar agentes, criar pasta outputs
-3. Carregar padrões (framework/standards/ > project/standards/)
-
-### FASE 1.5: 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 AGNÓSTICOS de biblioteca (ui-mockups, ui-components, ui-flows)
-4. Validar acessibilidade (WCAG 2.1) e responsividade
-- **⛔ PAUSA:** Aprovar / Ajustar wireframes / Adicionar fluxos
-
-### FASE 2: DESIGN
-1. Gerar spec.md com requisitos completos
-2. **DECISION POINTS** (cada um requer aprovação):
-   - Biblioteca UI (Fluent UI vs MudBlazor)
-   - Padrões Arquiteturais (CQRS vs simples, Repository vs EF direto)
-   - Estrutura de Dados (entidades, relacionamentos)
-   - Infraestrutura Azure (recursos, SKUs, custos)
-   - Bibliotecas/SDKs (NuGet packages)
-3. Gerar contracts.cs, documentar decisões em decisions.md
-- **⛔ PAUSA:** Aprovar / Ajustar escopo / Modificar contracts
-
-### FASE 3: CLARIFY
-1. Identificar ambiguidades, fazer perguntas, documentar em spec.md, validar edge cases
-
-### FASE 4: TASKS
-1. Quebrar spec em tasks T001-TXXX, definir ordem, checkpoints, dependências
-- **⛔ PAUSA:** Aprovar / Repriorizar / Adicionar-remover tasks
-
-### FASE 5: IMPLEMENT
-1. Implementar task por task
-2. `morph-spec task done {feature} {task-id}` após cada task
-3. Framework gerencia checkpoints automaticamente (a cada 3 tasks)
-4. Gerar recap.md ao final
-
-### FASE 6: SYNC (condicional - se complexidade média/alta)
-1. Revisar decisions.md, categorizar (coding, architecture, azure, integrations, ui-ux)
-2. Promover para `.morph/context/{category}.md`
-3. Gerar commit dedicado de sync
-- **⛔ PAUSA:** Aprovar promoção de decisões para standards
-
-## Outputs Completos
-proposal.md, ui-design-system.md, ui-mockups.md, ui-components.md, ui-flows.md, spec.md, contracts.cs, tasks.json, decisions.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 Azure AI Search e embeddings"
-- "Infraestrutura Azure completa com Bicep"
+# 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"

package/framework/workflows/docs/standard.md

@@ -1,44 +1,49 @@
-# Workflow: STANDARD (Média Complexidade)
-
-> **Layer:** 1 | **Load:** on-keyword | **Keywords:** paginação, filtro, refatorar, performance, exportar
-
-## Critérios
-
-- 3-10 arquivos, 50-500 linhas, 1-2 componentes simples
-- Sem infraestrutura complexa, decisões táticas (não estratégicas)
-
-## Fases
-
-### 1. FASE 0: PROPOSAL (simplificada)
-- Análise inicial em 1 parágrafo
-- Detecta agentes relevantes
-- **PAUSA:** Aprovar?
-
-### 2. FASE 2: DESIGN (apenas spec.md)
-- Spec técnico conciso (1-2 páginas)
-- Sem contracts.cs se trivial
-- Decisões táticas em decisions.md
-- **PAUSA:** Aprovar?
-
-### 3. FASE 4: TASKS (se > 5 tasks)
-- Breakdown em tasks
-- **PAUSA:** Aprovar?
-
-### 4. FASE 5: IMPLEMENT
-- Implementa task por task
-- Gera recap.md ao final
-
-## Outputs
-proposal.md, spec.md, recap.md (mínimo necessário)
-
-## Fases Puladas
-- FASE 1 (SETUP) - contexto já carregado
-- FASE 1.5 (UI/UX) - se não tiver front-end significativo
-- FASE 3 (CLARIFY) - se spec for claro
-- FASE 6 (SYNC) - decisões não são estratégicas
-
-## Exemplos
-- "Adicionar paginação na tabela de usuários"
-- "Criar filtro por data no relatório"
-- "Refatorar serviço de email para async"
-- "Adicionar botão de exportar CSV"
+# Workflow: STANDARD (Média Complexidade)
+
+> **Layer:** 1 | **Load:** on-keyword | **Keywords:** paginação, filtro, refatorar, performance, exportar
+
+## Critérios
+
+- 3-10 arquivos, 50-500 linhas, 1-2 componentes simples
+- Sem infraestrutura complexa, decisões táticas (não estratégicas)
+
+## Fases
+
+### 1. FASE 0: PROPOSAL (simplificada)
+- Análise inicial em 1 parágrafo
+- Detecta agentes relevantes
+- Avalia complexidade e recomenda workflow
+- **PAUSA:** Aprovar?
+
+### 2. FASE 2: DESIGN (spec.md + clarificação integrada)
+- Spec técnico conciso (1-2 páginas)
+- Quality loop com scoring (0-100) + clarificação embutida
+- Spec editável até aprovação final
+- Decisões táticas em decisions.md
+- **PAUSA:** Aprovar?
+
+### 3. FASE 3: PLAN
+- Plano de implementação com paths exatos e TDD
+- Tasks com cross-references para FRs do spec
+- **PAUSA:** Aprovar?
+
+### 4. FASE 4: TASKS
+- Breakdown em tasks com [FR001, FR003] refs
+- **PAUSA:** Aprovar? (se > 5 tasks)
+
+### 5. FASE 5: IMPLEMENT
+- Implementa task por task consultando spec por FR
+- Gera recap.md ao final
+
+## Outputs
+proposal.md, spec.md, plan.md, tasks.md, recap.md
+
+## Fases Puladas
+- UI/UX — se não tiver front-end significativo (skipIfCondition: !hasUIAgents)
+- Sync — decisões não são estratégicas
+
+## Exemplos
+- "Adicionar paginação na tabela de usuários"
+- "Criar filtro por data no relatório"
+- "Refatorar serviço de email para async"
+- "Adicionar botão de exportar CSV"

package/framework/workflows/docs/ui-refresh.md

@@ -16,7 +16,7 @@
 - Se protótipo existir: ler e extrair padrões
 - **PAUSA:** Escolher direção estética
 
-### 2. DESIGN SYSTEM (FASE 1.5 simplificada)
+### 2. DESIGN SYSTEM (FASE 2 simplificada)
 - Definir variáveis CSS novas
 - Listar componentes CSS a criar (checklist)
 - Gerar/atualizar design-system.css

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "4.12.0",
+  "version": "4.14.0",
   "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
   "keywords": [
     "claude-code",
@@ -10,9 +10,9 @@
     "spec-driven",
     "dotnet",
     "dotnet10",
-    "blazor",
+    "nextjs",
     "agent-framework",
-    "fluent-ui",
+    "vsa",
     "framework",
     "developer-tools",
     "morph",

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

@@ -1,8 +1,10 @@
 /**
- * dispatch-agents — Build dispatch config for parallel agent orchestration
+ * dispatch-agents — Advisor for native Claude Code agent dispatch
  *
- * Reads activeAgents from state.json + spawn_prompts from agents.json and
- * outputs a JSON dispatch config that phase skills use to spawn parallel subagents.
+ * Reads activeAgents from state.json + agents.json and outputs a
+ * recommendation of which agents to use and which tasks they handle.
+ * Agent .md files in .claude/agents/ are self-contained — dispatch
+ * does NOT compose prompts (except for tier-4 validators).
  *
  * Usage:
  *   morph-spec dispatch-agents <feature> <phase>
@@ -11,8 +13,10 @@
  * Output (JSON):
  * {
  *   feature, phase, shouldDispatch, reason,
- *   agents: [{ id, title, tier, icon, role, parallelGroup, canRunParallel, taskPrompt }],
- *   taskGroups: { [group]: { agentId, description, tasks, canRunParallel, taskPrompt } }
+ *   recommended: { [group]: subagentType[] },
+ *   tasks: { [group]: taskId[] },
+ *   agents: [{ id, subagentType, title, tier, icon, group }],
+ *   warnings: []
  * }
  */
 
@@ -20,7 +24,7 @@ import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { loadState, stateExists, logDispatch } from '../../core/state/state-manager.js';
-import { buildAgentBriefing, buildValidatorPrompt } from '../../lib/standards/digest-builder.js';
+import { buildValidatorPrompt } from '../../lib/standards/digest-builder.js';
 import { agentIdToSubagentType } from '../../utils/agent-id-mapper.js';
 import { shouldInstall, getProjectTags } from '../../lib/stack-filter.js';
 import { parseAndGroupTasks } from '../../lib/tasks/task-parser.js';
@@ -179,8 +183,10 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
     return {
       shouldDispatch: false,
       reason: 'state.json not found — run morph-spec state init',
+      recommended: {},
+      tasks: {},
       agents: [],
-      taskGroups: {},
+      warnings: [],
     };
   }
 
@@ -191,8 +197,10 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
       phase,
       shouldDispatch: false,
       reason: `Feature '${featureName}' not found in state.json`,
+      recommended: {},
+      tasks: {},
       agents: [],
-      taskGroups: {},
+      warnings: [],
     };
   }
 
@@ -204,25 +212,16 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
       phase,
       shouldDispatch: false,
       reason: 'framework/agents.json not found',
+      recommended: {},
+      tasks: {},
       agents: [],
-      taskGroups: {},
+      warnings: [],
     };
   }
 
   const agentsData = JSON.parse(readFileSync(agentsPath, 'utf8'));
   const allAgents = agentsData.agents || {};
 
-  // Load phases.json for required skills injection (opts.phasesJsonPath allows override for testing)
-  const phasesPath = opts.phasesJsonPath || PHASES_JSON_PATH;
-  let phasesData = null;
-  try {
-    if (existsSync(phasesPath)) {
-      phasesData = JSON.parse(readFileSync(phasesPath, 'utf8'));
-    }
-  } catch {
-    // Non-blocking — fail silent, skills block will be omitted
-  }
-
   // Load project config for stack filtering
   const configPath = join(projectPath, '.morph', 'config.json');
   let projectTags = [];
@@ -278,44 +277,28 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
 
     const group = getAgentGroup(agentId, agentData);
 
-    // Build task prompt: validator prompt for tier-4 in validate mode, else spawn_prompt
-    let rawPrompt;
-    if (isValidateMode && isTier4) {
-      rawPrompt = buildValidatorPrompt(agentId) || agentData.teammate?.spawn_prompt || '';
-    } else {
-      rawPrompt = agentData.teammate.spawn_prompt;
-    }
-
-    // Append standards digest as Constraints block, then skills block, then MCP block
-    const briefing = buildAgentBriefing(agentId, phase);
-    const skillsBlock = buildSkillsBlock(phase, phasesData);
-    const mcpBlock = buildMcpBlock(phase, phasesData);
-    const fullTaskPrompt = [
-      rawPrompt,
-      briefing    ? `\n\nConstraints:\n${briefing}` : '',
-      skillsBlock ? `\n\n${skillsBlock}`            : '',
-      mcpBlock    ? `\n\n${mcpBlock}`               : '',
-    ].join('');
-
-    dispatchableAgents.push({
+    // Tier-4 validators in validate mode still get taskPrompt (dynamically generated)
+    const agentEntry = {
       id: agentId,
       subagentType: agentIdToSubagentType(agentId, agentData.tier),
       title: agentData.title,
       tier: agentData.tier,
       icon: agentData.teammate?.icon || '🤖',
-      role: agentData.teammate?.role || agentData.description || '',
-      parallelGroup: group,
-      canRunParallel: true,
-      canWrite: !isTier4,
-      taskPrompt: fullTaskPrompt,
-    });
+      group,
+    };
+
+    if (isValidateMode && isTier4) {
+      agentEntry.taskPrompt = buildValidatorPrompt(agentId) || agentData.teammate?.spawn_prompt || '';
+    }
+
+    dispatchableAgents.push(agentEntry);
   }
 
   // Sort: domain-analysis first, then by tier (ascending), then alphabetically
   const groupOrder = ['domain-analysis', 'backend', 'frontend', 'infra', 'tests', 'docs', 'support'];
   dispatchableAgents.sort((a, b) => {
-    const gi = groupOrder.indexOf(a.parallelGroup);
-    const gj = groupOrder.indexOf(b.parallelGroup);
+    const gi = groupOrder.indexOf(a.group);
+    const gj = groupOrder.indexOf(b.group);
     if (gi !== gj) return gi - gj;
     if (a.tier !== b.tier) return a.tier - b.tier;
     return a.id.localeCompare(b.id);
@@ -323,56 +306,18 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
 
   const shouldDispatch = dispatchableAgents.length >= 2;
 
-  // ── Execution mode recommendation ─────────────────────────────────────────
-  // Derive recommended mode from agent composition:
-  // - 'agent-teams' : 2+ distinct parallel groups AND 5+ total agents (critical multi-domain)
-  // - 'subagents'   : shouldDispatch=true but below agent-teams threshold
-  // - 'single'      : no dispatch benefit
-  const distinctGroups = new Set(dispatchableAgents.map(a => a.parallelGroup)).size;
-  let mode;
-  if (shouldDispatch && distinctGroups >= 2 && dispatchableAgents.length >= 5) {
-    mode = 'agent-teams';
-  } else if (shouldDispatch) {
-    mode = 'subagents';
-  } else {
-    mode = 'single';
+  // ── Recommended agents by group ───────────────────────────────────────────
+  const recommended = {};
+  for (const agent of dispatchableAgents) {
+    if (!recommended[agent.group]) recommended[agent.group] = [];
+    recommended[agent.group].push(agent.subagentType);
   }
 
-  // ── Task groups ────────────────────────────────────────────────────────────
-  const taskGroups = {};
-
+  // ── Tasks by group (implement phase only) ─────────────────────────────────
+  let tasks = {};
   if (phase === 'implement') {
-    // Group tasks from tasks.md by domain category
     const tasksPath = join(projectPath, `.morph/features/${featureName}/4-tasks/tasks.md`);
-    const tasksByGroup = parseAndGroupTasks(tasksPath);
-
-    for (const [group, taskIds] of Object.entries(tasksByGroup)) {
-      const groupAgent = dispatchableAgents.find(a => a.parallelGroup === group);
-      taskGroups[group] = {
-        agentId: groupAgent?.id ?? null,
-        subagentType: groupAgent?.subagentType ?? null,
-        description: `${group} implementation tasks for feature '${featureName}'`,
-        tasks: taskIds,
-        canRunParallel: true,
-        taskPrompt: groupAgent?.taskPrompt ?? null,
-      };
-    }
-  } else {
-    // For design/tasks: one group per parallel group, no task IDs yet
-    const seenGroups = new Set();
-    for (const agent of dispatchableAgents) {
-      if (seenGroups.has(agent.parallelGroup)) continue;
-      seenGroups.add(agent.parallelGroup);
-
-      taskGroups[agent.parallelGroup] = {
-        agentId: agent.id,
-        subagentType: agent.subagentType,
-        description: agent.role,
-        tasks: [],
-        canRunParallel: true,
-        taskPrompt: agent.taskPrompt,
-      };
-    }
+    tasks = parseAndGroupTasks(tasksPath);
   }
 
   // ── Pre-flight: check agent files exist ──────────────────────────────────
@@ -391,15 +336,15 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
   return {
     feature: featureName,
     phase,
-    mode,
     shouldDispatch,
     reason: shouldDispatch
       ? `${dispatchableAgents.length} dispatchable agents for phase '${phase}'`
       : dispatchableAgents.length === 1
         ? `Only 1 dispatchable agent — sequential execution preferred`
         : `No dispatchable agents found for phase '${phase}'`,
+    recommended,
+    tasks,
     agents: dispatchableAgents,
-    taskGroups,
     warnings,
   };
 }
@@ -440,18 +385,12 @@ export async function dispatchAgentsCommand(featureName, phase, options = {}) {
         logDispatch(featureName, {
           timestamp: new Date().toISOString(),
           phase: normalizedPhase,
-          mode: config.mode,
-          agents: config.agents.map(a => {
-            const groupEntry = Object.entries(config.taskGroups || {}).find(
-              ([, g]) => g.agentId === a.id
-            );
-            return {
-              id: a.id,
-              subagentType: a.subagentType,
-              group: a.parallelGroup,
-              tasks: groupEntry ? groupEntry[1].tasks : [],
-            };
-          }),
+          agents: config.agents.map(a => ({
+            id: a.id,
+            subagentType: a.subagentType,
+            group: a.group,
+            tasks: config.tasks?.[a.group] || [],
+          })),
         });
       } catch {
         // Non-blocking — dispatch output still succeeds even if log fails
@@ -474,7 +413,7 @@ export async function dispatchAgentsCommand(featureName, phase, options = {}) {
         for (const agent of config.agents) {
           console.log(
             `  ${(agent.icon + ' ' + agent.id).padEnd(28)} ` +
-            `${chalk.cyan(agent.parallelGroup.padEnd(16))} ` +
+            `${chalk.cyan(agent.group.padEnd(16))} ` +
             `${agent.tier}`
           );
         }
@@ -482,17 +421,17 @@ export async function dispatchAgentsCommand(featureName, phase, options = {}) {
         console.log(chalk.gray('\n  No dispatchable agents.'));
       }
 
-      const groupEntries = Object.entries(config.taskGroups || {});
-      if (groupEntries.length > 0) {
-        console.log(`\n  Task Groups:`);
-        console.log(`  ${'Group'.padEnd(20)} ${'Tasks'.padEnd(8)} Agent`);
+      const recEntries = Object.entries(config.recommended || {});
+      if (recEntries.length > 0) {
+        console.log(`\n  Recommended:`);
+        console.log(`  ${'Group'.padEnd(20)} ${'Tasks'.padEnd(8)} Agents`);
         console.log('  ' + '─'.repeat(50));
-        for (const [group, data] of groupEntries) {
-          const taskCount = data.tasks?.length || 0;
+        for (const [group, agentTypes] of recEntries) {
+          const taskCount = config.tasks?.[group]?.length || 0;
           console.log(
             `  ${group.padEnd(20)} ` +
             `${String(taskCount).padEnd(8)} ` +
-            `${data.agentId || chalk.gray('none')}`
+            `${agentTypes.join(', ')}`
           );
         }
       }

package/src/commands/context/context-refresh.js

@@ -0,0 +1,79 @@
+/**
+ * CLI handler for `morph-spec context refresh`
+ *
+ * Scans the project filesystem for architectural patterns and generates
+ * a rich .morph/context/README.md that Claude reads at session start.
+ *
+ * @module context-refresh
+ */
+
+import { scanArchitecture, renderArchitectureContext } from '../../lib/generators/architecture-scanner.js';
+import { logger } from '../../utils/logger.js';
+
+/**
+ * @param {Object} options - Commander options
+ * @param {string} [options.path] - Target project path
+ * @param {boolean} [options.verbose] - Show detailed output
+ * @param {boolean} [options.json] - Output raw JSON
+ * @param {boolean} [options.quiet] - Suppress output (for programmatic use)
+ */
+export async function contextRefreshCommand(options = {}) {
+  const projectPath = options.path || process.cwd();
+
+  if (!options.quiet) {
+    logger.header('Architecture Context Refresh');
+    logger.dim(`Scanning: ${projectPath}`);
+    logger.blank();
+  }
+
+  try {
+    const scanResult = await scanArchitecture(projectPath);
+
+    if (options.json) {
+      console.log(JSON.stringify(scanResult, null, 2));
+      return;
+    }
+
+    const outputPath = await renderArchitectureContext(projectPath, scanResult);
+
+    if (!options.quiet) {
+      const counts = [];
+      if (scanResult.entities.length > 0) counts.push(`${scanResult.entities.length} entities`);
+      if (scanResult.endpoints.length > 0) counts.push(`${scanResult.endpoints.length} endpoints`);
+      if (scanResult.nextjs.pages.length > 0) counts.push(`${scanResult.nextjs.pages.length} pages`);
+      if (scanResult.nextjs.components.length > 0) counts.push(`${scanResult.nextjs.components.length} components`);
+      if (scanResult.integrations.length > 0) counts.push(`${scanResult.integrations.length} integrations`);
+      if (scanResult.database.length > 0) counts.push(`${scanResult.database.length} tables`);
+      if (scanResult.stack.dotnet.length > 0) counts.push(`${scanResult.stack.dotnet.length} .NET packages`);
+      if (scanResult.stack.npm.length > 0) counts.push(`${scanResult.stack.npm.length} npm packages`);
+
+      if (counts.length > 0) {
+        logger.success(`Found: ${counts.join(', ')}`);
+      } else {
+        logger.warn('No architectural patterns detected (empty project?)');
+      }
+
+      logger.success(`Written to: ${outputPath}`);
+
+      if (options.verbose) {
+        logger.blank();
+        if (scanResult.entities.length > 0) {
+          logger.info('Entities:');
+          for (const e of scanResult.entities) logger.dim(`  ${e.name} (${e.type}) — ${e.path}`);
+        }
+        if (scanResult.endpoints.length > 0) {
+          logger.info('Endpoints:');
+          for (const ep of scanResult.endpoints) logger.dim(`  ${ep.method || '???'} ${ep.route} — ${ep.name}`);
+        }
+        if (scanResult.nextjs.pages.length > 0) {
+          logger.info('Pages:');
+          for (const p of scanResult.nextjs.pages) logger.dim(`  ${p.route} — ${p.path}`);
+        }
+      }
+    }
+  } catch (err) {
+    if (options.quiet) throw err;
+    logger.error(`Scan failed: ${err.message}`);
+    process.exitCode = 1;
+  }
+}

package/src/commands/phase/phase-reset.js

@@ -12,7 +12,7 @@ import chalk from 'chalk';
 import { loadState, saveState, derivePhase } from '../../core/state/state-manager.js';
 import { join } from 'path';
 
-const VALID_PHASES = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'plan', 'tasks', 'implement', 'sync'];
+const VALID_PHASES = ['proposal', 'uiux', 'design', 'plan', 'tasks', 'implement', 'sync'];
 
 /**
  * Core reset logic — exported for testing.