@polymorphism-tech/morph-spec 1.0.2 → 2.0.0

package/content/.morph/docs/STORY-DRIVEN-DEVELOPMENT.md

@@ -0,0 +1,392 @@
+# Story-Driven Development - Guia do Usuário
+
+> **O que você faz quando implementa uma feature usando MORPH-SPEC**
+
+---
+
+## 📋 Você Está Aqui
+
+Você acabou de terminar as fases 0-4 do MORPH:
+- ✅ Criou `spec.md` (especificação técnica)
+- ✅ Criou `contracts.cs` (interfaces/DTOs)
+- ✅ Criou `tasks.json` (lista de tasks)
+- ✅ Aprovou tudo
+
+**Agora você vai implementar. Este guia mostra como.**
+
+---
+
+## 🚀 Passo a Passo Completo
+
+### Cenário: Feature "scheduled-reports" com 10 tasks
+
+```bash
+# ============================================================================
+# ETAPA 1: PREPARAÇÃO (1x por feature)
+# ============================================================================
+
+# 1.1 - Dividir spec.md em partes menores (opcional, mas recomendado)
+morph-spec story shard scheduled-reports
+
+# Isso cria:
+# .morph/project/outputs/scheduled-reports/spec/
+# ├── index.md
+# ├── entity-design.md
+# ├── service-layer.md
+# └── ui-components.md
+
+# 1.2 - Criar primeira story
+morph-spec story create scheduled-reports SR-001 \
+  --title "Create ScheduledReport entity" \
+  --tasks "Create entity,Configure EF mapping,Create migration,Write tests"
+
+# Isso cria:
+# .morph/project/outputs/scheduled-reports/stories/SR-001.md
+# (arquivo com TODO o contexto que você precisa)
+
+# 1.3 - Criar demais stories
+morph-spec story create scheduled-reports SR-002 \
+  --title "Implement ReportService" \
+  --tasks "Create interface,Implement service,Add DI,Write tests"
+
+morph-spec story create scheduled-reports SR-003 \
+  --title "Create report UI component" \
+  --tasks "Create razor component,Add to router,Style with Fluent UI"
+
+# ... criar SR-004, SR-005, etc.
+
+# 1.4 - Ver todas as stories criadas
+morph-spec story status scheduled-reports show
+
+# Output:
+# 📊 Sprint Status: scheduled-reports
+# Progress: 0% (0/10 stories done)
+# Stories:
+#   ✅ SR-001: Create ScheduledReport entity (ready)
+#   ✅ SR-002: Implement ReportService (ready)
+#   ✅ SR-003: Create report UI component (ready)
+#   ...
+
+
+# ============================================================================
+# ETAPA 2: IMPLEMENTAR STORY SR-001 (repetir para cada story)
+# ============================================================================
+
+# 2.1 - Marcar que você vai começar a trabalhar nela
+morph-spec story status scheduled-reports start SR-001
+
+# 2.2 - Abrir a story
+cat .morph/project/outputs/scheduled-reports/stories/SR-001.md
+
+# Você vai ver:
+# - Context (resumo do que fazer)
+# - Dev Notes (dicas automáticas tipo "use Primary Constructor")
+# - Tasks (lista de tarefas)
+# - Acceptance Criteria (como validar se tá certo)
+
+# 2.3 - Ler SÓ a parte relevante do spec (não o spec inteiro)
+cat .morph/project/outputs/scheduled-reports/spec/entity-design.md
+
+# 2.4 - Implementar o código
+# (você vai escrever o código da entity, testes, etc.)
+
+# 2.5 - Editar a story para adicionar suas notas
+nano .morph/project/outputs/scheduled-reports/stories/SR-001.md
+
+# Procurar a seção "### Dev Notes (Added by Dev Agent)"
+# Adicionar algo tipo:
+### Dev Notes (Added by Dev Agent)
+```
+✅ Implementado ScheduledReport.cs (linha 12)
+✅ EF mapping em ReportDbContext.cs (linha 45)
+✅ Migration: 20251209_AddScheduledReports.cs
+✅ Testes: ScheduledReportTests.cs (12 tests)
+⚠️  RecurrencePattern usa regex complexo
+```
+
+# 2.6 - Marcar que terminou e está pronto para revisar
+morph-spec story status scheduled-reports qa SR-001
+
+# 2.7 - Commitar código
+git add .
+git commit -m "feat(SR-001): create ScheduledReport entity"
+
+
+# ============================================================================
+# ETAPA 3: REVISAR STORY SR-001 (QA)
+# ============================================================================
+
+# 3.1 - Ver status
+morph-spec story status scheduled-reports show
+
+# Output:
+# 👀 SR-001: Create ScheduledReport entity (ready_for_qa)
+
+# 3.2 - Abrir a story (agora com as notas do Dev)
+cat .morph/project/outputs/scheduled-reports/stories/SR-001.md
+
+# Você vai ver as Dev Notes que foram adicionadas:
+# "✅ Implementado ScheduledReport.cs (linha 12)"
+# "⚠️ RecurrencePattern usa regex complexo"
+
+# 3.3 - Revisar o código
+cat src/Domain/Entities/ScheduledReport.cs
+cat tests/Unit/ScheduledReportTests.cs
+
+# 3.4 - Se precisar refatorar, refatore
+
+# 3.5 - Editar a story para adicionar notas de revisão
+nano .morph/project/outputs/scheduled-reports/stories/SR-001.md
+
+# Procurar a seção "### QA Notes (Added by QA Agent)"
+# Adicionar algo tipo:
+### QA Notes (Added by QA Agent)
+```
+✅ Código OK, segue padrões
+✅ Refatorei ValidateRecurrence() (linha 89)
+✅ Adicionei 3 testes de edge cases
+✅ Todos os acceptance criteria validados
+```
+
+# 3.6 - Marcar como concluída
+morph-spec story status scheduled-reports done SR-001
+
+# Output:
+# ✅ Story SR-001 marked as DONE
+# 📋 Next Story: SR-002
+
+# 3.7 - Commitar mudanças (se fez refactoring)
+git add .
+git commit -m "refactor(SR-001): extract ValidateRecurrence method"
+
+
+# ============================================================================
+# ETAPA 4: PRÓXIMA STORY (SR-002)
+# ============================================================================
+
+# Repetir ETAPA 2 e 3 para SR-002:
+morph-spec story status scheduled-reports start SR-002
+cat .morph/project/outputs/scheduled-reports/stories/SR-002.md
+cat .morph/project/outputs/scheduled-reports/spec/service-layer.md
+# ... implementar ...
+# ... adicionar Dev Notes ...
+morph-spec story status scheduled-reports qa SR-002
+# ... revisar ...
+# ... adicionar QA Notes ...
+morph-spec story status scheduled-reports done SR-002
+
+# Repetir para SR-003, SR-004, ..., SR-010
+
+
+# ============================================================================
+# ETAPA 5: FINALIZAÇÃO
+# ============================================================================
+
+# Ver progresso geral
+morph-spec story status scheduled-reports show
+
+# Output:
+# 📊 Sprint Status: scheduled-reports
+# Progress: 100% (10/10 stories done)
+# 🎉 All stories completed!
+
+# Pronto! Feature implementada.
+```
+
+---
+
+## 📝 Comandos que Você Usa
+
+### Criar stories (início da feature)
+```bash
+morph-spec story shard <feature-name>
+morph-spec story create <feature-name> <story-id> --title "..." --tasks "..."
+```
+
+### Ver status
+```bash
+morph-spec story status <feature-name> show
+```
+
+### Marcar que vai começar
+```bash
+morph-spec story status <feature-name> start <story-id>
+```
+
+### Marcar que terminou (vai para QA)
+```bash
+morph-spec story status <feature-name> qa <story-id>
+```
+
+### Marcar como concluída
+```bash
+morph-spec story status <feature-name> done <story-id>
+```
+
+### Ver próxima story
+```bash
+morph-spec story status <feature-name> next
+```
+
+---
+
+## 🔄 Seu Dia a Dia
+
+### Segunda-feira: Criar as stories
+```bash
+morph-spec story shard my-feature
+morph-spec story create my-feature MF-001 --title "..." --tasks "..."
+morph-spec story create my-feature MF-002 --title "..." --tasks "..."
+morph-spec story create my-feature MF-003 --title "..." --tasks "..."
+```
+
+### Terça-feira: Implementar MF-001
+```bash
+morph-spec story status my-feature start MF-001
+cat .morph/project/outputs/my-feature/stories/MF-001.md
+cat .morph/project/outputs/my-feature/spec/entity-design.md
+# [implementar código]
+# [adicionar Dev Notes na story]
+morph-spec story status my-feature qa MF-001
+git commit ...
+```
+
+### Terça à tarde: Revisar MF-001
+```bash
+cat .morph/project/outputs/my-feature/stories/MF-001.md  # ver Dev Notes
+# [revisar código]
+# [adicionar QA Notes na story]
+morph-spec story status my-feature done MF-001
+git commit ...
+```
+
+### Quarta-feira: Implementar MF-002
+```bash
+morph-spec story status my-feature start MF-002
+# ... repetir workflow
+```
+
+---
+
+## ❓ Perguntas Comuns
+
+### "Preciso shardar o spec?"
+**Não é obrigatório.** Só recomendado se seu `spec.md` for grande (5+ seções).
+
+Se for pequeno, pule o `shard-spec.js` e vá direto para `create-story.js`.
+
+---
+
+### "Quantas tasks por story?"
+**4-8 tasks** é ideal. Se tiver mais, quebre em sub-stories.
+
+Exemplo:
+- ❌ Ruim: Story com 20 tasks (muito grande)
+- ✅ Bom: Story com 5 tasks (1 dia de trabalho)
+
+---
+
+### "O que são Dev Notes e QA Notes?"
+**Dev Notes:** Você (Dev) escreve o que implementou, para o QA saber.
+
+**QA Notes:** Você (QA) escreve o que revisou/refatorou.
+
+**Exemplo:**
+```markdown
+### Dev Notes (Added by Dev Agent)
+```
+✅ Implementei X.cs na pasta Domain/
+⚠️  Cuidado: usa regex complexo na linha 67
+```
+
+### QA Notes (Added by QA Agent)
+```
+✅ Revisei e está OK
+✅ Refatorei método ValidateX() para ficar mais claro
+```
+```
+
+---
+
+### "Onde adiciono Dev/QA Notes?"
+**No arquivo da story.**
+
+1. Abra: `.morph/project/outputs/my-feature/stories/MF-001.md`
+2. Procure a seção `### Dev Notes (Added by Dev Agent)`
+3. Substitua `[VOCÊ VAI PREENCHER AQUI APÓS IMPLEMENTAR]` pelas suas notas
+4. Salve
+
+---
+
+### "E se eu esquecer de adicionar Dev Notes?"
+Sem problema. Edite a story manualmente:
+
+```bash
+nano .morph/project/outputs/my-feature/stories/MF-001.md
+# Adicione as notas na seção correta
+# Salve
+```
+
+---
+
+### "Posso implementar várias stories na mesma sessão?"
+**Não recomendado.**
+
+Cada story = nova sessão do Claude (se usar Claude Code).
+
+Por quê? Evita confusão e economiza tokens.
+
+---
+
+## ✅ Checklist Rápido
+
+**No início da feature:**
+- [ ] Roda `shard-spec.js` (opcional)
+- [ ] Roda `create-story.js` para cada story
+- [ ] Roda `show` para ver todas criadas
+
+**Para cada story:**
+- [ ] `start` → Marcar que vai começar
+- [ ] Ler story file (`.morph/project/outputs/.../stories/XX.md`)
+- [ ] Ler spec shard (`.morph/project/outputs/.../spec/xxx.md`)
+- [ ] Implementar código
+- [ ] Adicionar Dev Notes na story
+- [ ] `qa` → Marcar que terminou
+- [ ] Commit código
+- [ ] Revisar código
+- [ ] Adicionar QA Notes na story
+- [ ] `done` → Marcar como concluída
+- [ ] Commit mudanças
+
+**No final:**
+- [ ] `show` → Ver que 100% completo
+- [ ] Todas stories têm Dev Notes e QA Notes preenchidas
+
+---
+
+## 📚 Referência Rápida
+
+```bash
+# Ver ajuda de qualquer comando
+morph-spec story --help
+morph-spec story shard --help
+morph-spec story create --help
+morph-spec story status --help
+
+# Estrutura de pastas (após criar stories)
+.morph/project/outputs/my-feature/
+├── spec/               # Spec dividido em partes
+│   ├── index.md
+│   ├── entity-design.md
+│   └── service-layer.md
+├── stories/            # Stories auto-contidas
+│   ├── MF-001.md
+│   ├── MF-002.md
+│   └── MF-003.md
+└── sprint-status.yaml  # Progresso automático
+```
+
+---
+
+*MORPH-SPEC Framework - Guia do Usuário*
+*Use este guia como referência rápida durante o desenvolvimento*

package/content/.morph/hooks/README.md

@@ -0,0 +1,239 @@
+# MORPH-SPEC Git Hooks
+
+Pre-commit hooks for automatic validation before committing.
+
+## Available Hooks
+
+| Hook | Description | Action |
+|------|-------------|--------|
+| `pre-commit-agents.sh` | Validates agents.json with JSON Schema | ❌ Blocks commit |
+| `pre-commit-costs.sh` | Validates Azure costs don't exceed limits | ❌ Blocks commit |
+| `pre-commit-specs.sh` | Validates spec.md has required sections | ❌ Blocks commit |
+| `pre-commit-tests.sh` | Checks if new code has tests | ⚠️ Warns only |
+| `pre-commit-all.sh` | Runs all hooks in sequence | ❌ Blocks if any fail |
+
+## Installation
+
+### Option 1: Install Individual Hooks
+
+```bash
+# Install cost validation
+ln -s ../../content/.morph/hooks/pre-commit-costs.sh .git/hooks/pre-commit
+
+# Or symlink all at once
+ln -s ../../content/.morph/hooks/pre-commit-all.sh .git/hooks/pre-commit
+```
+
+### Option 2: Copy Hooks
+
+```bash
+# Copy master hook
+cp content/.morph/hooks/pre-commit-all.sh .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+### Option 3: Use Existing Hooks
+
+If you already have `.git/hooks/pre-commit`, add this to the end:
+
+```bash
+# Run MORPH-SPEC validations
+bash content/.morph/hooks/pre-commit-all.sh || exit 1
+```
+
+## What Each Hook Does
+
+### pre-commit-agents.sh
+
+**Validates:** `agents.json` configuration
+
+**Checks:**
+- JSON Schema compliance
+- Required fields (id, name, emoji, type, etc.)
+- Keyword patterns (alphanumeric + hyphens/underscores)
+- No duplicate keywords
+- autoActivation for specialist agents
+
+**Example Output:**
+```
+🤖 Validating agent configuration...
+Detected changes to agents.json
+
+=== MORPH-SPEC Agent Validator ===
+
+Version: 1.0.0
+Core Agents: 6
+Specialist Agents: 4
+
+✓ Validation PASSED
+```
+
+### pre-commit-costs.sh
+
+**Validates:** Bicep files for Azure costs
+
+**Checks:**
+- Parses modified `.bicep` files
+- Calculates monthly costs
+- Blocks if > `requiresADR` limit (default: $10)
+- Checks if ADR exists in decisions.md
+
+**Example Output:**
+```
+💰 Calculating Azure costs...
+
+╔════════════════════════════════════════════════╗
+║ sqlDatabase (Basic)              $4.99/mo     ║
+║ containerApp (Consumption)       $0.00/mo     ║
+╠════════════════════════════════════════════════╣
+║ Total: $4.99                                   ║
+║ Requires ADR: NO                               ║
+╚════════════════════════════════════════════════╝
+
+✓ Cost validation passed
+```
+
+### pre-commit-specs.sh
+
+**Validates:** `spec.md` files have required sections
+
+**Checks:**
+- `## 📋 Metadata`
+- `## 🎯 Overview`
+- `## 🏗️ Technical Design`
+- `## ✅ Acceptance Criteria`
+- Warns if no user stories found
+
+**Example Output:**
+```
+🔍 Validating spec files...
+Checking: .morph/outputs/my-feature/spec.md
+  ✓ All required sections found
+✓ All spec files are valid
+```
+
+### pre-commit-tests.sh
+
+**Validates:** New C# code has corresponding tests
+
+**Checks:**
+- Finds modified `.cs` files (excluding tests)
+- Looks for `*Tests.cs` or `Test*.cs`
+- Skips trivial files (DTOs, records, models)
+- **Warns only, doesn't block**
+
+**Example Output:**
+```
+🧪 Checking test coverage...
+  ✓ Test found for: Services/UserService.cs
+  ⚠️  No test found for: Services/PaymentService.cs
+
+⚠️  WARNING: Some files don't have tests
+   Override with: git commit --no-verify
+```
+
+### pre-commit-all.sh (Master Hook)
+
+**Runs:** All hooks in sequence
+
+**Output:**
+```
+╔════════════════════════════════════════════════╗
+║     MORPH-SPEC PRE-COMMIT VALIDATION           ║
+╚════════════════════════════════════════════════╝
+
+─────────────────────────────────────────────────
+🤖 Validating agent configuration...
+✓ No changes to agents.json
+
+─────────────────────────────────────────────────
+💰 Calculating Azure costs...
+✓ No Bicep files modified
+
+─────────────────────────────────────────────────
+🔍 Validating spec files...
+✓ No spec files modified
+
+─────────────────────────────────────────────────
+🧪 Checking test coverage...
+  ✓ Test found for: Services/UserService.cs
+
+═════════════════════════════════════════════════
+✅ ALL PRE-COMMIT VALIDATIONS PASSED
+```
+
+## Bypassing Hooks
+
+If you need to commit without validation (e.g., WIP commit):
+
+```bash
+git commit --no-verify -m "WIP: work in progress"
+```
+
+**⚠️ Use sparingly** - hooks exist to prevent errors.
+
+## Customizing Hooks
+
+### Adjust Cost Limits
+
+Edit `content/.morph/config/config.json`:
+
+```json
+{
+  "costs": {
+    "limits": {
+      "requiresADR": 15  // Change from $10 to $15
+    }
+  }
+}
+```
+
+### Disable Specific Hooks
+
+Edit `.git/hooks/pre-commit` and comment out unwanted hooks:
+
+```bash
+HOOKS=(
+  "pre-commit-agents.sh"
+  # "pre-commit-costs.sh"  # Disabled
+  "pre-commit-specs.sh"
+  "pre-commit-tests.sh"
+)
+```
+
+## Troubleshooting
+
+### Hook Not Running
+
+```bash
+# Check if hook exists
+ls -la .git/hooks/pre-commit
+
+# Check if executable
+chmod +x .git/hooks/pre-commit
+
+# Test manually
+bash .git/hooks/pre-commit
+```
+
+### Hook Fails Unexpectedly
+
+```bash
+# Run individual hook for debugging
+bash content/.morph/hooks/pre-commit-costs.sh
+
+# Check hook output
+bash -x content/.morph/hooks/pre-commit-costs.sh
+```
+
+## Benefits
+
+- ✅ **Prevents Errors:** Catches issues before commit
+- ✅ **Enforces Quality:** Requires tests, specs, ADRs
+- ✅ **Cost Control:** Blocks expensive infrastructure
+- ✅ **Fast Feedback:** Fails early in dev workflow
+- ✅ **Consistent:** Same validation for entire team
+
+---
+
+*MORPH-SPEC Framework - Git Hooks*

package/content/.morph/hooks/pre-commit-agents.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# MORPH-SPEC Pre-Commit Hook: Agent Configuration Validation
+# Uses validate-agents.js to check agents.json
+
+echo "🤖 Validating agent configuration..."
+
+# Check if agents.json is being modified
+if git diff --cached --name-only | grep -q 'agents\.json$'; then
+  echo "Detected changes to agents.json"
+
+  # Run validator
+  if ! node bin/validate-agents.js; then
+    echo ""
+    echo "❌ COMMIT BLOCKED: agents.json validation failed"
+    echo "   Fix errors above before committing"
+    exit 1
+  fi
+
+  echo "✓ agents.json is valid"
+else
+  echo "✓ No changes to agents.json"
+fi
+
+exit 0

package/content/.morph/hooks/pre-commit-all.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# MORPH-SPEC Master Pre-Commit Hook
+# Runs all validation hooks in sequence
+
+echo "╔════════════════════════════════════════════════╗"
+echo "║     MORPH-SPEC PRE-COMMIT VALIDATION           ║"
+echo "╚════════════════════════════════════════════════╝"
+echo ""
+
+HOOKS_DIR="$(dirname "$0")"
+
+# Run all hooks in order
+HOOKS=(
+  "pre-commit-agents.sh"
+  "pre-commit-costs.sh"
+  "pre-commit-specs.sh"
+  "pre-commit-tests.sh"
+)
+
+HAS_FAILURES=false
+
+for hook in "${HOOKS[@]}"; do
+  HOOK_PATH="$HOOKS_DIR/$hook"
+
+  if [ ! -f "$HOOK_PATH" ]; then
+    echo "⚠️  Hook not found: $hook (skipping)"
+    continue
+  fi
+
+  echo "─────────────────────────────────────────────────"
+  if ! bash "$HOOK_PATH"; then
+    HAS_FAILURES=true
+    echo "❌ Hook failed: $hook"
+  fi
+  echo ""
+done
+
+echo "═════════════════════════════════════════════════"
+
+if [ "$HAS_FAILURES" = true ]; then
+  echo "❌ PRE-COMMIT VALIDATION FAILED"
+  echo "   Fix errors above before committing"
+  echo "   Or use: git commit --no-verify to skip"
+  exit 1
+fi
+
+echo "✅ ALL PRE-COMMIT VALIDATIONS PASSED"
+exit 0