@polymorphism-tech/morph-spec 6.0.0 → 7.1.0

package/framework/hooks/claude-code/core/state-sync.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * state-sync.js — PostToolUse hook
+ *
+ * Keeps .morph/state.json in sync with the agent's actions, without requiring
+ * the agent to think about state. Fail-open: any error returns {} silently.
+ *
+ * Triggers:
+ *  - Write/Edit of .morph/features/{feature}/0-proposal/proposal.md  → register feature
+ *  - Write/Edit of .morph/features/{feature}/{phase}/{output}        → mark output created
+ *  - AskUserQuestion answered with option starting "aprovado"        → advance gate
+ */
+
+import { readFileSync, existsSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { loadState, stateExists } from '../../shared/state-reader.js';
+
+const STATE_FILE = '.morph/state.json';
+
+const PHASE_FOLDERS = {
+  '0-proposal': 'proposal',
+  '1-design': 'design',
+  '1-ui': 'uiux', // legacy alias — still recognized during folder transition
+  '2-plan': 'plan',
+  '3-implement': 'implement',
+  '4-review': 'review',
+  '5-implement': 'implement', // legacy alias
+};
+
+function exit(output = {}) {
+  process.stdout.write(JSON.stringify(output));
+  process.exit(0);
+}
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function projectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function extractFeatureName(filePath) {
+  if (!filePath) return null;
+  const normalized = String(filePath).replace(/\\/g, '/');
+  const match = normalized.match(/\.morph\/features\/([^/]+)\//);
+  return match ? match[1] : null;
+}
+
+function extractPhaseFolder(filePath) {
+  if (!filePath) return null;
+  const normalized = String(filePath).replace(/\\/g, '/');
+  const match = normalized.match(/\.morph\/features\/[^/]+\/([^/]+)\//);
+  if (!match) return null;
+  return PHASE_FOLDERS[match[1]] ?? null;
+}
+
+function extractFilename(filePath) {
+  const normalized = String(filePath).replace(/\\/g, '/');
+  return normalized.split('/').pop();
+}
+
+/**
+ * Atomic write — temp file then rename. Mirrors state-manager.js semantics.
+ */
+function writeStateAtomic(cwd, state) {
+  const path = join(cwd, STATE_FILE);
+  const tmpPath = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
+  renameSync(tmpPath, path);
+}
+
+function registerFeatureIfMissing(state, featureName) {
+  if (!state.features) state.features = {};
+  if (state.features[featureName]) return false;
+
+  const now = new Date().toISOString();
+  state.features[featureName] = {
+    status: 'in_progress',
+    createdAt: now,
+    updatedAt: now,
+    approvalGates: { proposal: false, plan: false, review: false },
+    outputs: {},
+  };
+
+  if (!state.metadata) state.metadata = {};
+  state.metadata.totalFeatures = Object.keys(state.features).length;
+  return true;
+}
+
+function trackOutput(state, featureName, filePath) {
+  const filename = extractFilename(filePath);
+  const feature = state.features[featureName];
+  if (!feature) return false;
+  feature.outputs ??= {};
+  const normalizedPath = String(filePath).replace(/\\/g, '/');
+  const wasMissing = !feature.outputs[filename]?.created;
+  feature.outputs[filename] = {
+    created: true,
+    path: normalizedPath,
+  };
+  feature.updatedAt = new Date().toISOString();
+  return wasMissing;
+}
+
+function findActiveFeature(state) {
+  if (!state.features) return null;
+  const entries = Object.entries(state.features);
+  const active = entries.find(([, f]) => f.status === 'in_progress');
+  if (active) return active[0];
+  return entries[0]?.[0] ?? null;
+}
+
+function isApprovalAnswer(answer) {
+  if (typeof answer !== 'string') return false;
+  const lower = answer.toLowerCase();
+  return (
+    lower.startsWith('aprovado') ||
+    lower.includes('pode avan') ||
+    lower.includes('pode implementar') ||
+    lower.includes('pode prosseguir')
+  );
+}
+
+function gateFromQuestion(question) {
+  if (typeof question !== 'string') return null;
+  const lower = question.toLowerCase();
+  if (lower.includes('gate 1') || lower.includes('proposta')) return 'proposal';
+  if (lower.includes('gate 2') || lower.includes('plano') || lower.includes('plan')) return 'plan';
+  if (lower.includes('gate 3') || lower.includes('review')) return 'review';
+  return null;
+}
+
+function handleWriteEdit(input, cwd) {
+  const filePath = input.tool_input?.file_path;
+  const featureName = extractFeatureName(filePath);
+  if (!featureName) return false;
+
+  const state = loadState(cwd);
+  if (!state) return false;
+
+  let changed = registerFeatureIfMissing(state, featureName);
+  const phase = extractPhaseFolder(filePath);
+  if (phase) {
+    const outputChanged = trackOutput(state, featureName, filePath);
+    changed = changed || outputChanged;
+  }
+
+  if (changed) {
+    writeStateAtomic(cwd, state);
+  }
+  return true;
+}
+
+function handleAskUserQuestion(input, cwd) {
+  const answers = input.tool_response?.answers ?? input.tool_response?.responses ?? {};
+  if (typeof answers !== 'object' || answers === null) return false;
+
+  const state = loadState(cwd);
+  if (!state) return false;
+
+  const featureName = findActiveFeature(state);
+  if (!featureName) return false;
+
+  let changed = false;
+  for (const [question, answer] of Object.entries(answers)) {
+    if (!isApprovalAnswer(answer)) continue;
+    const gate = gateFromQuestion(question);
+    if (!gate) continue;
+
+    state.features[featureName].approvalGates ??= {};
+    if (state.features[featureName].approvalGates[gate] !== true) {
+      state.features[featureName].approvalGates[gate] = true;
+      state.features[featureName].updatedAt = new Date().toISOString();
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    writeStateAtomic(cwd, state);
+  }
+  return true;
+}
+
+async function main() {
+  const cwd = projectDir();
+  if (!stateExists(cwd)) {
+    exit();
+    return;
+  }
+
+  const input = readStdin();
+  const toolName = input.tool_name;
+
+  try {
+    if (toolName === 'Write' || toolName === 'Edit') {
+      handleWriteEdit(input, cwd);
+    } else if (toolName === 'AskUserQuestion') {
+      handleAskUserQuestion(input, cwd);
+    }
+  } catch {
+    // fail-open
+  }
+
+  exit();
+}
+
+main().catch(() => exit());

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

@@ -8,15 +8,16 @@
  */
 
 /** Phase order */
-export const PHASE_ORDER = ["proposal","uiux","plan","implement","review"];
+export const PHASE_ORDER = ["proposal","uiux","plan","implement","review","sync"];
 
 /** Map phase → allowed output subdirectory */
 export const PHASE_DIRS = {
   proposal: '0-proposal',
-  uiux: '1-ui',
+  uiux: '1-design',
   plan: '2-plan',
   implement: '3-implement',
   review: '4-review',
+  sync: '3-implement',
 };
 
 /** Map output type (camelCase) → phase that produces it */
@@ -47,7 +48,7 @@ export const FILENAME_TO_OUTPUT = {
   'flows.md': 'uiFlows',
   'spec.md': 'spec',
   'mandate.md': 'mandate',
-  'tasks.md': 'tasks',
+  'tasks.json': 'tasks',
   'decisions.md': 'decisions',
   'recap.md': 'recap',
   'review-report.md': 'reviewReport',
@@ -61,7 +62,7 @@ export const PROTECTED_SPEC_FILES = {
   'flows.md': 'uiux',
   'spec.md': 'plan',
   'mandate.md': 'plan',
-  'tasks.md': 'plan',
+  'tasks.json': 'plan',
 };
 
 /**

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

@@ -110,7 +110,7 @@ export function derivePhaseForFeature(featureName, projectPath) {
     ['4-review', 'review'],
     ['3-implement', 'implement'],
     ['2-plan', 'plan'],
-    ['1-ui', 'uiux'],
+    ['1-design', 'uiux'],
     ['0-proposal', 'proposal'],
   ];
   for (const [folder, phase] of phaseMap) {

package/framework/phases.json

@@ -21,7 +21,7 @@
     "uiux": {
       "id": "uiux",
       "index": 1,
-      "folder": "1-ui",
+      "folder": "1-design",
       "displayName": "UI/UX Design",
       "optional": true,
       "goals": [

package/framework/rubrics/backend.json

@@ -1,36 +1,41 @@
-{
-  "id": "backend",
-  "version": "1.0.0",
-  "description": "Backend-focused rubric. Higher weight on architecture, security, and package health.",
-  "categories": {
-    "functionality": {
-      "weight": 0.30,
-      "validators": ["contract-compliance"],
-      "description": "Core feature correctness and contract compliance"
-    },
-    "code_quality": {
-      "weight": 0.30,
-      "validators": ["architecture"],
-      "description": "Architecture patterns, dependency direction, and code structure"
-    },
-    "design_ui": {
-      "weight": 0.05,
-      "validators": ["design-system", "css", "contrast", "nextjs-component"],
-      "description": "Design system compliance (minimal weight for backend projects)"
-    },
-    "security": {
-      "weight": 0.15,
-      "validators": [],
-      "description": "Security posture (agent-evaluated, no automated validator)"
-    },
-    "packages": {
-      "weight": 0.20,
-      "validators": ["packages"],
-      "description": "Dependency health, version compatibility, and deprecated packages"
-    }
-  },
-  "thresholds": {
-    "approve": 8.0,
-    "retry": 6.0
-  }
-}
+{
+  "id": "backend",
+  "version": "1.0.0",
+  "description": "Backend-focused rubric. Higher weight on architecture, security, and package health.",
+  "categories": {
+    "functionality": {
+      "weight": 0.25,
+      "validators": ["contract-compliance"],
+      "description": "Core feature correctness and contract compliance"
+    },
+    "code_quality": {
+      "weight": 0.25,
+      "validators": ["architecture"],
+      "description": "Architecture patterns, dependency direction, and code structure"
+    },
+    "design_ui": {
+      "weight": 0.05,
+      "validators": ["design-system", "css", "contrast", "nextjs-component"],
+      "description": "Design system compliance (minimal weight for backend projects)"
+    },
+    "security": {
+      "weight": 0.15,
+      "validators": [],
+      "description": "Security posture (agent-evaluated, no automated validator)"
+    },
+    "packages": {
+      "weight": 0.20,
+      "validators": ["packages"],
+      "description": "Dependency health, version compatibility, and deprecated packages"
+    },
+    "maf_compliance": {
+      "weight": 0.10,
+      "validators": [],
+      "description": "MAF agent compliance (agent-evaluated, applies only when the feature touches AI agents): Microsoft.Agents.AI GA packages used; Model Registry alias referenced not hardcoded models; structured output for pipelined agents; prompts from DB not hardcoded; no Semantic Kernel; no hosted agent services."
+    }
+  },
+  "thresholds": {
+    "approve": 8.0,
+    "retry": 6.0
+  }
+}

package/framework/rules/ai-agents-standards.md

@@ -1,15 +1,45 @@
----
-paths:
-  - "**/Agents/**"
-  - "**/agents/**"
-  - "**/*Agent*.cs"
-stacks:
-  - dotnet
----
-
-# Microsoft Agent Framework Standards
-
-@.morph/framework/standards/ai-agents/setup.md
-@.morph/framework/standards/ai-agents/workflows.md
-@.morph/framework/standards/ai-agents/production.md
-@.morph/framework/standards/integration/mcp/mcp-tools.md
+---
+paths:
+  - "**/Agents/**"
+  - "**/agents/**"
+  - "**/*Agent*.cs"
+stacks:
+  - dotnet
+---
+
+# Microsoft Agent Framework Standards
+
+> **Layer 0/1 — auto-carregados.** São os standards core: aplicam-se a praticamente todo
+> agente MAF. Carregue-os sempre que tocar código de agentes.
+
+@.morph/framework/standards/ai-agents/setup.md
+@.morph/framework/standards/ai-agents/sweet-spot.md
+@.morph/framework/standards/ai-agents/providers/model-registry.md
+@.morph/framework/standards/ai-agents/structured-output.md
+@.morph/framework/standards/ai-agents/multi-agent-patterns.md
+@.morph/framework/standards/ai-agents/prompts-in-db.md
+@.morph/framework/standards/ai-agents/rag-custom-pgvector.md
+@.morph/framework/standards/ai-agents/middleware-patterns.md
+@.morph/framework/standards/ai-agents/workflows.md
+@.morph/framework/standards/ai-agents/production.md
+
+---
+
+> **Layer 2 — sob demanda (NÃO auto-carregados).** São standards de modalidade, otimização e
+> MCP: relevantes apenas quando a feature usa especificamente esse recurso. Carregue via
+> `morph-standards` quando uma keyword corresponder — manter fora do auto-load preserva o
+> context window para o trabalho que importa.
+
+| Standard | Carregue quando a feature envolve |
+|----------|-----------------------------------|
+| `ai-agents/modalities-vision.md` | imagem → texto (OCR, análise de documento, visão) |
+| `ai-agents/modalities-image-gen.md` | texto → imagem (geração de mockups, posts, assets) |
+| `ai-agents/modalities-speech-to-text.md` | áudio → texto (transcrição, legendagem) |
+| `ai-agents/modalities-text-to-speech.md` | texto → áudio (síntese de voz) |
+| `ai-agents/batching.md` | processar N prompts independentes em lote (Batch API) |
+| `ai-agents/service-tier-flex.md` | otimização de custo em jobs assíncronos (tier flex) |
+| `ai-agents/agent-session.md` | agentes conversacionais com histórico/reducers |
+| `ai-agents/context-providers.md` | injeção dinâmica de contexto (`AIContextProvider`) |
+| `ai-agents/mcp-tools.md` | agente MAF consome um MCP server externo |
+| `ai-agents/mcp-server.md` | projeto expõe capacidades como MCP server |
+| `integration/mcp/mcp-tools.md` | integração MCP cross-domain (fora do escopo MAF) |

package/framework/rules/morph-workflow.md

@@ -13,20 +13,18 @@ stacks:
 
 **NEVER skip to code without a specification.** Every feature must progress through phases:
 
-1. **Proposal** — User story + acceptance criteria (`0-proposal/proposal.md`)
-2. **Design** — Technical spec + C# contracts + decisions (`2-design/`)
-3. **Plan** — Detailed implementation plan (`3-plan/plan.md`)
-4. **Tasks** — Atomic task list (`4-tasks/tasks.md`)
-5. **Implement** — Code + recap (`5-implement/recap.md`)
-
-UI-heavy features also include **UI/UX** phase (`1-ui/`) between Design and Tasks.
+1. **Proposal** — Problem statement + acceptance criteria (`0-proposal/proposal.md`)
+2. **Design** (optional, UI-heavy) — Design system + mockups + flows (`1-design/`)
+3. **Plan** — Technical spec + mandate + tasks (`2-plan/spec.md`, `mandate.md`, `tasks.json`)
+4. **Implement** — Code + recap (`3-implement/recap.md`)
+5. **Review** — Review report + Gate 3 (`4-review/review-report.md`)
 
 ---
 
 ## Phase Sequence
 
 ```
-proposal → [uiux] → design → plan → tasks → implement → [sync]
+proposal → [design] → plan → implement → review
 ```
 
 Use `morph-spec status {feature}` to see current phase and pending approval gates.
@@ -52,25 +50,11 @@ Use `morph-spec status {feature}` to see current phase and pending approval gate
 | `.morph/framework/` | **READ-ONLY** — framework files managed by morph-spec |
 | `.morph/config/config.json` | Project configuration (editable) |
 
-### mark-output types
-
-Use `morph-spec state mark-output <feature> <type>` with one of these exact type names:
+### output types
 
-| Type | Phase | kebab alias |
-|------|-------|-------------|
-| `proposal` | proposal | — |
-| `schemaAnalysis` | design | `schema-analysis` |
-| `spec` | design | — |
-| `contracts` | design | — |
-| `contractsVsa` | design | `contracts-vsa` |
-| `decisions` | design | — |
-| `plan` | plan | — |
-| `tasks` | tasks | — |
-| `uiDesignSystem` | uiux | `ui-design-system` |
-| `uiMockups` | uiux | `ui-mockups` |
-| `uiComponents` | uiux | `ui-components` |
-| `uiFlows` | uiux | `ui-flows` |
-| `recap` | implement | — |
+Output types are defined in `src/core/paths/output-schema.js`. State sync is
+handled automatically by the `state-sync.js` PostToolUse hook — the agent
+does not need to call mark-output explicitly.
 
 ---
 
@@ -80,14 +64,11 @@ All outputs go in `.morph/features/{feature}/`:
 
 | Phase | Path |
 |-------|------|
-| Proposal | `0-proposal/proposal.md` |
-| UI Design | `1-ui/design-system.md`, `mockups.md`, `components.md`, `flows.md` |
-| Spec | `2-design/spec.md` |
-| Contracts | `2-design/contracts.cs` |
-| Decisions | `2-design/decisions.md` |
-| Plan | `3-plan/plan.md` |
-| Tasks | `4-tasks/tasks.md` |
-| Recap | `5-implement/recap.md` |
+| Proposal | `0-proposal/proposal.md`, `stack-scan.md`, `migration-plan.md` (optional) |
+| Design (optional) | `1-design/design-system.md`, `mockups.md`, `components.md`, `flows.md` |
+| Plan | `2-plan/spec.md`, `mandate.md`, `tasks.json`, `decisions.md` |
+| Implement | `3-implement/recap.md` + source code |
+| Review | `4-review/review-report.md` |
 
 ---
 

package/framework/rules/neon-standards.md

@@ -1,26 +1,25 @@
----
-paths:
-  - "**/neon/**"
-  - "**/database/**"
-  - "**/*Migration*.sql"
-  - "**/*migration*.sql"
-stacks:
-  - neon
----
-
-# Neon PostgreSQL Standards
-
-@.morph/framework/standards/infrastructure/neon/neon-setup.md
-@.morph/framework/standards/infrastructure/neon/neon-pgvector.md
-@.morph/framework/standards/infrastructure/neon/neon-pgrag.md
-@.morph/framework/standards/infrastructure/neon/neon-semantic-kernel.md
-@.morph/framework/standards/backend/integrations/neon-auth/neon-auth.md
-
-## SQL Templates
-
-| Template | Path | Purpose |
-|----------|------|---------|
-| PostgreSQL Migration | `.morph/framework/templates/code/sql/postgresql-migration.sql` | Database migration |
-| PostgreSQL RLS Policy | `.morph/framework/templates/code/sql/postgresql-rls-policy.sql` | Row-level security |
-
-Read the template and adapt to your project structure.
+---
+paths:
+  - "**/neon/**"
+  - "**/database/**"
+  - "**/*Migration*.sql"
+  - "**/*migration*.sql"
+stacks:
+  - neon
+---
+
+# Neon PostgreSQL Standards
+
+@.morph/framework/standards/infrastructure/neon/neon-setup.md
+@.morph/framework/standards/infrastructure/neon/neon-pgvector.md
+@.morph/framework/standards/infrastructure/neon/neon-pgrag.md
+@.morph/framework/standards/backend/integrations/neon-auth/neon-auth.md
+
+## SQL Templates
+
+| Template | Path | Purpose |
+|----------|------|---------|
+| PostgreSQL Migration | `.morph/framework/templates/code/sql/postgresql-migration.sql` | Database migration |
+| PostgreSQL RLS Policy | `.morph/framework/templates/code/sql/postgresql-rls-policy.sql` | Row-level security |
+
+Read the template and adapt to your project structure.

package/framework/schemas/tasks.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MORPH-SPEC tasks.json",
+  "description": "Structured task list for a morph-spec feature. Replaces tasks.md.",
+  "type": "object",
+  "required": ["version", "feature", "tasks"],
+  "properties": {
+    "version": { "type": "string", "const": "1.0" },
+    "feature": { "type": "string", "minLength": 1 },
+    "tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "description", "dependencies", "effort", "doneCriteria", "status"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^T\\d+$" },
+          "title": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "dependencies": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^T\\d+$" }
+          },
+          "effort": { "type": "string", "enum": ["S", "M", "L", "XL"] },
+          "doneCriteria": { "type": "string", "minLength": 1 },
+          "status": { "type": "string", "enum": ["pending", "in_progress", "done", "skipped", "blocked"] },
+          "outputs": { "type": "array", "items": { "type": "string" } },
+          "notes": { "type": "string" },
+          "group": { "type": "string", "enum": ["backend", "frontend", "tests", "infra", "docs"] }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}