@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

package/framework/evals/scenarios/nextjs-auth.yaml

@@ -0,0 +1,38 @@
+name: nextjs-auth
+description: OAuth2 authentication feature for Next.js + shadcn/ui application with Neon Auth
+stack: nextjs-neon
+
+request: |
+  Add user authentication to the Next.js application using Neon Auth (Better Auth).
+  Users should be able to sign in with Google OAuth, view their profile page
+  showing name, email, and avatar using shadcn/ui Card and Avatar components,
+  and sign out. Use TanStack Query for data fetching and cache management.
+  Protect authenticated routes with Next.js middleware.
+  Session data lives in the Neon PostgreSQL database.
+
+phases_to_eval:
+  - proposal
+  - spec
+  - tasks
+
+skip_implementation: true
+
+dimensions:
+  proposal:
+    completeness: "Covers sign-in, profile with shadcn/ui components, sign-out, Neon Auth session storage, middleware route protection"
+    scope: "Appropriately scoped — no admin dashboard, no multi-provider auth beyond Google"
+  spec:
+    specificity: "Each FR has testable acceptance criteria with specific status codes, Neon Auth config, TanStack Query hooks"
+    data_model: "User and Session entities defined with Prisma schema or Drizzle schema for Neon PostgreSQL"
+    architecture: "Next.js App Router structure, API routes, middleware, shadcn/ui component boundaries, TanStack Query patterns"
+    completeness: "OAuth flow via Neon Auth, token refresh, error handling, logout flow, loading states with Framer Motion"
+  tasks:
+    granularity: "Each task 15-60 minutes, no mega-tasks"
+    coverage: "All spec FRs mapped to at least one task"
+    ordering: "Dependencies respected — Neon Auth setup before routes, routes before UI, UI before tests"
+  cross_phase:
+    fr_coverage_threshold: 0.95
+    mandate_completeness: 0.9
+
+threshold: 8.0
+max_iterations: 3

package/framework/evals/suites/standard.yaml

@@ -0,0 +1,5 @@
+name: standard
+description: Core eval suite — one scenario per major stack
+scenarios:
+  - nextjs-auth
+  - dotnet-crud

package/framework/evals/trace-schema.md

@@ -0,0 +1,67 @@
+# Trace Schema — morph-spec NLH
+
+## Local de armazenamento
+
+`.morph/traces/YYYY-MM-DD-{feature}-{phase}.json`
+
+Um arquivo por fase. Se a fase for executada em múltiplas sessões, o mesmo arquivo é atualizado incrementalmente.
+
+## Formato JSON
+
+```json
+{
+  "schema_version": "1.0",
+  "session_id": "YYYY-MM-DD-HH-MM-SS",
+  "feature": "nome-da-feature",
+  "phase": "implement | plan | review",
+  "started_at": "ISO 8601",
+  "completed_at": "ISO 8601",
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "descrição da task",
+      "status": "completed | failed | skipped",
+      "standards_consulted": ["id-do-standard-1"],
+      "agent_persona": "dotnet-senior | nextjs-expert | etc",
+      "sub_agent_dispatched": false,
+      "eval_score": 8.5,
+      "eval_dimensions": {
+        "architecture": 9.0,
+        "contracts": 8.0,
+        "code_quality": 8.5,
+        "test_coverage": 8.5
+      },
+      "files_modified": ["path/relativo/arquivo.cs"],
+      "duration_seconds": null
+    }
+  ],
+  "phase_summary": {
+    "tasks_completed": 3,
+    "tasks_failed": 0,
+    "avg_eval_score": 8.3,
+    "standards_most_used": ["architecture-vertical-slice"],
+    "sub_agents_dispatched": 0
+  }
+}
+```
+
+## Quando escrever
+
+| Evento | O que logar |
+|--------|-------------|
+| Task completada | Adicionar entrada em `tasks[]` com todos os campos preenchidos |
+| Eval executada (`morph-eval`) | Preencher `eval_score` e `eval_dimensions` da task correspondente |
+| Fase concluída | Preencher `completed_at` e `phase_summary` |
+
+## Regras de escrita
+
+- O modelo escreve o trace como arquivo JSON ao final de cada task e ao final da fase.
+- Se um campo não tiver valor disponível, usar `null` — nunca omitir o campo.
+- Manter a estrutura completa para compatibilidade com análise de meta-harness.
+- `session_id` usa o formato `YYYY-MM-DD-HH-MM-SS` do início da sessão atual.
+- `standards_consulted` contém os `id`s do STANDARDS.json, não os paths.
+- `files_modified` usa paths relativos à raiz do repositório.
+
+## Motivação
+
+Raw traces preservam o sinal completo de execução. Summaries comprimem informação e perdem sinais que o meta-harness usa para otimização. Regra: logar o trace completo — nunca substituir por resumo.

package/framework/hooks/claude-code/core/README.md

@@ -0,0 +1,3 @@
+# hooks/claude-code/core
+Part of morph-spec NLH.
+See `framework/MORPH.md` for full documentation.

package/framework/hooks/claude-code/core/denylist.json

@@ -0,0 +1,14 @@
+{
+  "version": "1.0.0",
+  "patterns": [
+    "rm -rf /",
+    "rm -rf ~",
+    "DROP TABLE",
+    "DROP DATABASE",
+    "format c:",
+    "mkfs",
+    "> /dev/sda",
+    "dd if=/dev/zero",
+    ":(){:|:&};:"
+  ]
+}

package/framework/hooks/claude-code/{pre-tool-use → core}/enforce-phase-writes.js

@@ -8,9 +8,9 @@
  * Ensures writes to .morph/features/{feature}/ go to the current phase's subfolder:
  *   proposal → only 0-proposal/
  *   uiux → only 1-ui/
- *   design, clarify → only 2-design/
- *   tasks → only 4-tasks/
- *   implement → 5-implement/ + any source code (unrestricted)
+ *   plan → only 2-plan/
+ *   implement → 3-implement/ + any source code (unrestricted)
+ *   review → only 4-review/
  *
  * Files outside .morph/features/ are always allowed.
  *
@@ -77,8 +77,8 @@ try {
     block(
       `MORPH-SPEC: Writing to '${targetDir}/' is not allowed during ${phaseLabel} phase.\n` +
       `Current phase '${phase}' only permits writes to '${allowedDir}/'.\n\n` +
-      `To write to '${targetDir}/', first advance to the appropriate phase:\n` +
-      `  morph-spec phase advance ${featureName}`
+      `If you need to write to a different phase folder, ensure the feature\n` +
+      `has advanced to the appropriate phase first (check gates in state.json).`
     );
   }
 

package/framework/hooks/claude-code/core/post-edit-typecheck.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: TypeScript typecheck with debounce
+ *
+ * Event: PostToolUse | Matcher: Write|Edit
+ *
+ * Runs `npx tsc --noEmit` only for .ts/.tsx files, with a 3-second debounce
+ * so rapid sequential edits (e.g. multiple files in one task) don't each
+ * trigger a full typecheck. Silent on success — only injects on error.
+ *
+ * Debounce state: .morph/memory/typecheck-debounce.json
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { pass, injectContext } from '../../shared/hook-response.js';
+import { stateExists } from '../../shared/state-reader.js';
+
+const DEBOUNCE_MS = 3000;
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  const toolName = payload?.tool_name || '';
+  const filePath = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+
+  if (!['Write', 'Edit'].includes(toolName)) pass();
+  if (!filePath.match(/\.tsx?$/)) pass();
+
+  // Debounce: skip if a typecheck ran within the last 3 seconds
+  const cwd = process.cwd();
+  const memDir = join(cwd, '.morph', 'memory');
+  const debouncePath = join(memDir, 'typecheck-debounce.json');
+
+  try {
+    if (existsSync(debouncePath)) {
+      const { lastRun } = JSON.parse(readFileSync(debouncePath, 'utf-8'));
+      if (Date.now() - new Date(lastRun).getTime() < DEBOUNCE_MS) pass();
+    }
+  } catch { /* corrupt file — proceed */ }
+
+  try {
+    mkdirSync(memDir, { recursive: true });
+    writeFileSync(debouncePath, JSON.stringify({ lastRun: new Date().toISOString() }), 'utf-8');
+  } catch { /* non-blocking */ }
+
+  try {
+    execSync('npx tsc --noEmit', { cwd, stdio: 'pipe', timeout: 30000 });
+    pass();
+  } catch (err) {
+    const stderr = err.stderr?.toString() || '';
+    const stdout = err.stdout?.toString() || '';
+    const output = (stderr + stdout).trim();
+    const fileName = filePath.split(/[\\/]/).pop();
+    const relevant = output.split('\n')
+      .filter(l => l.includes(fileName) || l.includes('error TS'))
+      .slice(0, 10)
+      .join('\n');
+    injectContext(`TypeScript errors after editing ${fileName}:\n${relevant || output.split('\n').slice(0, 10).join('\n')}`);
+  }
+} catch {
+  pass();
+}

package/framework/hooks/claude-code/core/pre-bash-denylist.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { pass, block } from '../../shared/hook-response.js';
+import { stateExists } from '../../shared/state-reader.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  const command = payload?.tool_input?.command || '';
+  if (!command) pass();
+
+  const denylist = JSON.parse(readFileSync(join(__dirname, 'denylist.json'), 'utf-8'));
+
+  for (const pattern of denylist.patterns) {
+    if (command.includes(pattern)) {
+      block(`Comando bloqueado pela denylist: padrão '${pattern}' detectado.`);
+    }
+  }
+
+  pass();
+} catch {
+  pass();
+}

package/framework/hooks/claude-code/{pre-tool-use → core}/protect-spec-files.js

@@ -6,8 +6,7 @@
  * Event: PreToolUse | Matcher: Write|Edit
  *
  * Blocks Write/Edit to spec artifacts after their approval gate has passed:
- *   - 2-design/spec.md, contracts.cs, etc. → blocked if 'design' gate approved
- *   - 4-tasks/tasks.md → blocked if 'tasks' gate approved
+ *   - 2-plan/spec.md, contracts.cs, tasks.md, etc. → blocked if 'plan' gate approved
  *   - 1-ui/design-system.md, etc. → blocked if 'uiux' gate approved
  *
  * Fail-open: exits 0 on any error.
@@ -58,10 +57,9 @@ try {
     block(
       `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
       `Editing approved specs breaks the spec contract.\n\n` +
-      `If changes are truly needed:\n` +
-      `  1. Revoke approval: morph-spec unapprove ${featureName} ${requiredGate}\n` +
-      `  2. Make your edits\n` +
-      `  3. Re-approve: morph-spec approve ${featureName} ${requiredGate}`
+      `If changes are truly needed, ask the user to revoke the gate approval\n` +
+      `in .morph/state.json (set approvals.${requiredGate} to false), make\n` +
+      `your edits, then re-present the gate for approval.`
     );
   }
 

package/framework/hooks/claude-code/{stop → core}/validate-completion.js

@@ -1,19 +1,16 @@
 #!/usr/bin/env node
 
 /**
- * Stop Hook: Validate Completion + Phase Transition Alerts
+ * Stop Hook: Phase Transition Alert + Build Check + Session Snapshot
  *
  * Event: Stop
  *
- * 1. Detects transitions into the `implement` phase and recommends /compact
- *    before starting — ensures Claude has a clean context for writing code.
- * 2. Checks for incomplete work (tasks, missing outputs, pending gates).
+ * 1. Detects transitions into the `implement` phase and recommends /compact.
+ * 2. Runs stack-aware build check — warns only on failure (silent on pass).
+ * 3. Saves session snapshot for next-session orientation.
  *
  * Phase transition tracking: stores last-seen phase per feature in
- * .morph/memory/phase-watch.json so the alert fires exactly once,
- * the first Stop after the transition occurs.
- *
- * Uses stop_hook_active env check to prevent infinite loops.
+ * .morph/memory/phase-watch.json so the alert fires exactly once.
  *
  * Fail-open: exits 0 on any error.
  */
@@ -23,7 +20,7 @@ import { join } from 'path';
 import { runBuildCheck } from '../../shared/build-check.js';
 import { saveSessionSnapshot } from '../../shared/session-snapshot.js';
 import {
-  stateExists, getActiveFeature, getMostRecentFeature, getMissingOutputs, derivePhaseForFeature,
+  stateExists, getActiveFeature, getMostRecentFeature, derivePhaseForFeature,
 } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
@@ -31,8 +28,8 @@ import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
 // Phases where compaction is strongly recommended before starting
 const COMPACT_TRIGGER_PHASES = new Set(['implement']);
 
-// Phases where compaction is suggested when arriving from a heavy spec phase
-const HEAVY_SOURCE_PHASES = new Set(['tasks', 'design', 'uiux']);
+// Phases where compaction is suggested when arriving (heavy spec phases)
+const HEAVY_SOURCE_PHASES = new Set(['plan', 'uiux']);
 
 try {
   // Prevent infinite loop
@@ -76,11 +73,11 @@ try {
       `⚡ Phase advanced: ${lastPhase} → implement`,
       ``,
       `💡 Recommended before starting implementation:`,
-      `   Run /compact to free up context — the spec, design and task files`,
+      `   Run /compact to free up context — spec.md, mandate.md and tasks.md`,
       `   loaded during planning take significant space. A compact now gives`,
       `   Claude a clean slate focused on writing code.`,
       ``,
-      `   After /compact, resume with: morph-spec task start ${name} <next-task-id>`,
+      `   After /compact, resume with: /morph-apply ${name}`,
     );
   }
 
@@ -111,14 +108,10 @@ try {
   // Save session state for next session's "getting up to speed" routine.
   try {
     if (active) {
-      const { name, feature } = active;
-      const taskList = feature.taskList || [];
+      const { name } = active;
       saveSessionSnapshot({
         feature: name,
         phase: currentPhase,
-        tasksCompleted: taskList.filter(t => t.status === 'completed').map(t => t.id),
-        tasksRemaining: taskList.filter(t => t.status === 'pending').map(t => t.id),
-        tasksInProgress: taskList.filter(t => t.status === 'in_progress').map(t => t.id),
         buildStatus: 'skip',
         lastEditedFiles: [],
       }, cwd);
@@ -128,73 +121,11 @@ try {
   }
   // ────────────────────────────────────────────────────────────────────────
 
-  // ── Incomplete work checks ────────────────────────────────────────────────
-
-  // Incomplete tasks during implement phase
-  if (currentPhase === 'implement' && feature.tasks) {
-    const remaining = (feature.tasks.total || 0) - (feature.tasks.completed || 0);
-    if (remaining > 0) {
-      warnings.push(`${remaining} task(s) remaining for feature '${name}'`);
-      if (feature.tasks.inProgress > 0) {
-        warnings.push(`  ${feature.tasks.inProgress} task(s) still in progress`);
-      }
-    }
-  }
-
-  // Missing outputs in spec phases
-  if (['proposal', 'design', 'tasks', 'uiux'].includes(currentPhase)) {
-    const missing = getMissingOutputs(name);
-    if (missing.length > 0) {
-      warnings.push(`Missing outputs for '${name}' (${currentPhase} phase):`);
-      for (const output of missing.slice(0, 5)) {
-        warnings.push(`  - ${output.type}: ${output.path}`);
-      }
-      if (missing.length > 5) {
-        warnings.push(`  ... and ${missing.length - 5} more`);
-      }
-    }
-  }
-
-  // Pending approval gates
-  if (feature.approvalGates) {
-    const pendingGates = Object.entries(feature.approvalGates)
-      .filter(([, gate]) => !gate.approved && !gate.timestamp)
-      .map(([gateName]) => gateName);
-
-    const gatePhaseMap = { proposal: 'proposal', uiux: 'uiux', design: 'design', tasks: 'tasks' };
-    const relevant = pendingGates.filter(gate => gatePhaseMap[gate] !== undefined);
-
-    if (relevant.length > 0) {
-      warnings.push(`Pending approvals: ${relevant.join(', ')}`);
-    }
-  }
-
-  // ── MEMORY.md reminder ────────────────────────────────────────────────────
-  const WORK_PHASES = new Set(['design', 'tasks', 'implement']);
-  const memoryLines = [];
-  if (WORK_PHASES.has(currentPhase)) {
-    memoryLines.push('📝 Sessão encerrando. Considere salvar no MEMORY.md:');
-    memoryLines.push('  • Padrões de domínio descobertos (regras, invariants, edge cases)');
-    memoryLines.push('  • Decisões arquiteturais tomadas nesta sessão (e o motivo)');
-    memoryLines.push('  • Erros frequentes desta stack/projeto e como resolvê-los');
-    memoryLines.push('  • Nuances do projeto que diferem do padrão (convenções, libs específicas)');
-    memoryLines.push('  • Bugs encontrados e a causa raiz');
-    memoryLines.push('  Se nada relevante foi descoberto nesta sessão, ignore este lembrete.');
-  }
-
-  if (warnings.length === 0 && memoryLines.length === 0) pass();
-
-  const allLines = [...warnings];
-  if (memoryLines.length > 0) {
-    if (allLines.length > 0) allLines.push('');
-    allLines.push(...memoryLines);
-  }
+  if (warnings.length === 0) pass();
 
   const message = [
     'MORPH-SPEC:',
-    ...allLines.map(w => `  ${w}`),
-    '',
-    `Status: morph-spec status ${name}`,
+    ...warnings.map(w => `  ${w}`),
   ].join('\n');
 
   logHookActivity('validate-completion', 'Stop', `warnings(${warnings.length})`);

package/framework/hooks/shared/phase-utils.js

@@ -8,68 +8,60 @@
  */
 
 /** Phase order */
-export const PHASE_ORDER = ["proposal","uiux","design","plan","tasks","implement","sync"];
+export const PHASE_ORDER = ["proposal","uiux","plan","implement","review"];
 
 /** Map phase → allowed output subdirectory */
 export const PHASE_DIRS = {
   proposal: '0-proposal',
   uiux: '1-ui',
-  design: '2-design',
-  plan: '3-plan',
-  tasks: '4-tasks',
-  implement: '5-implement',
-  sync: '5-implement',
+  plan: '2-plan',
+  implement: '3-implement',
+  review: '4-review',
 };
 
 /** Map output type (camelCase) → phase that produces it */
 export const OUTPUT_PHASE_MAP = {
   proposal: 'proposal',
-  schemaAnalysis: 'design',
-  spec: 'design',
-  contracts: 'design',
-  contractsTs: 'design',
-  contractsVsa: 'design',
-  plan: 'plan',
-  tasks: 'tasks',
+  stackScan: 'proposal',
+  migrationPlan: 'proposal',
   uiDesignSystem: 'uiux',
   uiMockups: 'uiux',
   uiComponents: 'uiux',
   uiFlows: 'uiux',
-  decisions: 'design',
+  spec: 'plan',
+  mandate: 'plan',
+  tasks: 'plan',
+  decisions: 'plan',
   recap: 'implement',
+  reviewReport: 'review',
 };
 
 /** Map filename → output type (camelCase) */
 export const FILENAME_TO_OUTPUT = {
   'proposal.md': 'proposal',
-  'schema-analysis.md': 'schemaAnalysis',
-  'spec.md': 'spec',
-  'contracts.cs': 'contracts',
-  'contracts.ts': 'contractsTs',
-  'contracts-vsa.cs': 'contractsVsa',
-  'plan.md': 'plan',
-  'tasks.md': 'tasks',
+  'stack-scan.md': 'stackScan',
+  'migration-plan.md': 'migrationPlan',
   'design-system.md': 'uiDesignSystem',
   'mockups.md': 'uiMockups',
   'components.md': 'uiComponents',
   'flows.md': 'uiFlows',
+  'spec.md': 'spec',
+  'mandate.md': 'mandate',
+  'tasks.md': 'tasks',
   'decisions.md': 'decisions',
   'recap.md': 'recap',
+  'review-report.md': 'reviewReport',
 };
 
 /** Protected spec files and the approval gate that locks them */
 export const PROTECTED_SPEC_FILES = {
-  'schema-analysis.md': 'design',
-  'spec.md': 'design',
-  'contracts.cs': 'design',
-  'contracts.ts': 'design',
-  'contracts-vsa.cs': 'design',
-  'plan.md': 'plan',
-  'tasks.md': 'tasks',
   'design-system.md': 'uiux',
   'mockups.md': 'uiux',
   'components.md': 'uiux',
   'flows.md': 'uiux',
+  'spec.md': 'plan',
+  'mandate.md': 'plan',
+  'tasks.md': 'plan',
 };
 
 /**

package/framework/hooks/shared/state-reader.js

@@ -107,10 +107,9 @@ export function getFeature(featureName, projectPath) {
 export function derivePhaseForFeature(featureName, projectPath) {
   const basePath = join(projectPath || process.cwd(), '.morph/features', featureName);
   const phaseMap = [
-    ['5-implement', 'implement'],
-    ['4-tasks', 'tasks'],
-    ['3-plan', 'plan'],
-    ['2-design', 'design'],
+    ['4-review', 'review'],
+    ['3-implement', 'implement'],
+    ['2-plan', 'plan'],
     ['1-ui', 'uiux'],
     ['0-proposal', 'proposal'],
   ];
@@ -136,7 +135,7 @@ export function getFeaturePhase(featureName, projectPath) {
 /**
  * Get approval status for a gate.
  * @param {string} featureName
- * @param {string} gate - 'proposal'|'uiux'|'design'|'tasks'
+ * @param {string} gate - 'proposal'|'uiux'|'plan'|'review'
  * @param {string} [projectPath]
  * @returns {boolean}
  */