chore: ignora graphify-out gerado

2026-10-28 15:59:30 +00:00
parent 0ff519f554
commit 75041136d2
26 changed files with 3023 additions and 1 deletions
@@ -0,0 +1,347 @@
+---
+layer: wiki
+type: Document
+tags: [projecto, modelo, organizacao, proc]
+title: 2026 05 16 Proc Dev Standard Design
+description: >-
+  Design do PROC-DEV-STANDARD (D7-SIS-006) — standard de procedimentos de desenvolvimento, aprovado 2026-05-16.
+timestamp: 2026-05-16T16:40:14.554151+00:00
+---
+# Design — PROC-DEV-STANDARD (D7-SIS-006)
+
+**Data:** 2026-05-16
+**Status:** Aprovado
+**Autor:** Emanuel Almeida + Claude Code
+**Baseado em:** WhatSMS v2 (`/media/ealmeida/Dados/Dev/WhatSMS/whatsms-v2`)
+
+---
+
+## Objectivo
+
+Criar o `PROC-DEV-STANDARD` — protocolo de desenvolvimento de ciclo completo (ideia → produção) para todos os projectos Descomplicar®. Agnóstico de stack. Garante que qualquer agente (Claude, Gemini, Hermes, OpenCode, Antigravity) compreende o estado do projecto, nunca perde contexto e partilha toda a informação disponível.
+
+---
+
+## Localização
+
+- **Fonte de verdade:** `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md` (código D7-SIS-006)
+- **Resumo/referência:** `Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md`
+
+---
+
+## Estrutura do Documento
+
+```
+1. Princípios
+2. Fluxo Completo (visão geral)
+3. Estrutura de Projecto Obrigatória
+4. Ficheiros de Contexto Cross-Agent
+5. Fase 1 — Ideia
+6. Fase 2 — Pesquisa (deep research + NLM)
+7. Fase 3 — Spec
+8. Fase 4 — Plan
+9. Fase 5 — Desenvolvimento (branch + commits)
+10. Fase 6 — Quality Gates
+11. Fase 7 — Code Review & PR
+12. Fase 8 — Deploy & Validação
+13. Gestão de Ferramentas: Gitea vs Desk CRM
+14. Gates Obrigatórios (Issue-First, Deploy Guard)
+15. Excepções (hotfix, re-deploy)
+16. Referências
+```
+
+---
+
+## Fluxo Completo
+
+```
+Ideia
+  → Pesquisa (deep research + NLM existente ou novo se domínio novo)
+  → Spec (SPEC.md aprovado)
+  → Plan (implementação detalhada)
+  → Desenvolvimento (feat/* → commits atómicos)
+  → Quality Gates (pre-commit → pre-push → CI)
+  → Code Review & PR (Gitea)
+  → Deploy & Validação (PROC-DEPLOY-STANDARD)
+```
+
+Excepções ao pipeline completo: bugfix, operação unitária, continuação de plano existente.
+
+---
+
+## Estrutura de Projecto Obrigatória
+
+```
+/ (root)
+├── docs/
+│   ├── PLANS/          # Planos de acção e roadmaps
+│   └── SPECS/          # Specs técnicas + notas de pesquisa
+├── scripts/            # Automação local (opcional)
+├── AGENTS.md           # Directrizes por agente (obrigatório)
+├── CHANGELOG.md        # Histórico de versões
+├── CLAUDE.md           # Instruções Claude Code (se aplicável)
+├── MEMORY.md           # Contexto cross-agent (obrigatório)
+├── STATUS.md           # Estado vivo do projecto (obrigatório)
+└── .desk-project       # Ligação Desk CRM (JSON, obrigatório)
+```
+
+Validação automática: `scripts/validate-structure.sh` (já existente no modelo).
+
+---
+
+## Ficheiros de Contexto Cross-Agent
+
+### MEMORY.md
+- Partilhado entre Claude, Gemini, Hermes, OpenCode, Antigravity e outros
+- Formato: secções por data, ordem cronológica inversa
+- Conteúdo: decisões, paths, IDs, workarounds, factos de sessão
+- **Não** usar `projects/*/memory/*.md` do Claude Code — usar sempre `MEMORY.md` local
+
+### STATUS.md
+- Estado instantâneo do projecto — actualizado no início e fim de cada sessão
+- Conteúdo: sprint actual, versão, bloqueios, próximos passos, agente activo
+- Formato sugerido:
+  ```
+  # STATUS.md — [Nome Projecto]
+  **Versão:** vX.Y.Z | **Sprint:** #N | **Data:** YYYY-MM-DD
+  **Agente activo:** [nome] | **Sessão iniciada:** HH:MM
+
+  ## Estado
+  - Em curso: [o que está a ser feito]
+  - Bloqueios: [impedimentos activos]
+  - Próximos passos: [próxima acção concreta]
+  ```
+
+### AGENTS.md
+- Directrizes específicas do projecto para cada família de agentes
+- Conteúdo: o que cada agente pode/não pode fazer, ferramentas disponíveis, restrições
+- Actualizado pelo owner quando as regras mudam
+
+### CHANGELOG.md
+- Histórico de versões com data, sprint e impacto
+- Actualizado pelo agente activo a cada versão/sprint concluído
+- Formato: Conventional Changelog (## vX.Y.Z — YYYY-MM-DD)
+
+### Protocolo de sessão (qualquer agente)
+1. **Início** → ler `MEMORY.md` + `STATUS.md` + `.desk-project`
+2. **Durante** → registar decisões relevantes em `MEMORY.md` em tempo real
+3. **Fim** → actualizar `STATUS.md` + `MEMORY.md` com factos novos
+
+---
+
+## Fase 1 — Ideia
+
+**Entrada:** ideia ou pedido de funcionalidade
+**Saída:** decisão de avançar ou descartar + âmbito inicial definido
+
+Verificar antes de avançar:
+- Não existe já funcionalidade equivalente no projecto
+- Alinhado com o MASTER-PLAN / objectivos do projecto
+- Âmbito claro o suficiente para pesquisar
+
+---
+
+## Fase 2 — Pesquisa
+
+**Entrada:** ideia com âmbito definido
+**Saída:** nota de pesquisa em `docs/SPECS/research-YYYY-MM-DD-tema.md`
+
+### Processo
+1. Identificar domínio da ideia
+2. Verificar NLMs existentes via `/knowledge` (65 notebooks inventariados)
+   - Se domínio coberto → usar NLM existente (adicionar fontes se necessário)
+   - Se domínio novo **e** pesquisa extensa → criar NLM dedicado ao projecto
+   - Criar NLM apenas se estritamente necessário
+3. Executar deep research: WebSearch + WebFetch + NLM
+4. Sintetizar: decisões técnicas, alternativas avaliadas, alternativas descartadas e porquê, riscos identificados
+5. Guardar nota de pesquisa em `docs/SPECS/`
+
+### Output mínimo da nota de pesquisa
+- Pergunta de investigação
+- Fontes consultadas
+- Conclusões (o que fazer e porquê)
+- Alternativas descartadas (com justificação)
+- Riscos e mitigações
+
+---
+
+## Fase 3 — Spec
+
+**Entrada:** nota de pesquisa aprovada
+**Saída:** `SPEC.md` ou ficheiro em `docs/SPECS/` aprovado pelo owner
+
+- Seguir skill `/brainstorm` → `/spec` para trabalho não-trivial (>3 ficheiros ou sistema novo)
+- Excepções: bugfix, operação unitária, continuação de plano existente
+- A spec é o contrato bilateral — nada entra em código sem spec aprovada
+
+---
+
+## Fase 4 — Plan
+
+**Entrada:** spec aprovada
+**Saída:** plano de implementação em `docs/PLANS/`
+
+- Seguir skill `/writing-plans` para decompor em tarefas executáveis
+- Cada tarefa com critério de aceitação claro
+- Registar plano em `docs/PLANS/PLAN-YYYY-MM-DD-tema.md`
+
+---
+
+## Fase 5 — Desenvolvimento
+
+**Entrada:** plano aprovado
+**Saída:** commits atómicos em branch dedicada
+
+### Branch strategy
+- `main` — produção (protegida)
+- `dev` — desenvolvimento (se aplicável)
+- `feat/N-descricao` — novas funcionalidades
+- `fix/N-descricao` — correções de bugs (N = número da issue Gitea)
+
+### Commits
+Formato Conventional Commits com referência à issue:
+```
+tipo(scope): descrição breve (#N)
+
+Corpo opcional com contexto adicional.
+
+Closes #N
+Co-Authored-By: [Agente] <noreply@anthropic.com>
+```
+
+Tipos válidos: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+
+**Regras:**
+- Um commit = uma alteração lógica
+- `#N` obrigatório (ref à issue Gitea)
+- Pre-commit hooks automáticos: formatação + lint (apenas staged)
+
+---
+
+## Fase 6 — Quality Gates
+
+**Entrada:** código desenvolvido
+**Saída:** código validado pronto para PR
+
+| Gate | Momento | Responsável | O que verifica |
+|------|---------|-------------|----------------|
+| Pre-commit | Automático | Hook | Formatação, lint |
+| Pre-push | Manual | Agente | Build, testes, cobertura, auditoria segurança |
+| CI | Automático (push) | Gitea Actions | Tudo + report cobertura |
+
+Thresholds de cobertura e comandos concretos definidos por projecto no `CONTRIBUTING.md` do projecto — não no PROC genérico.
+
+**Regra:** nunca fazer push sobre CI vermelho. Nunca fazer PR sem quality gates verdes.
+
+---
+
+## Fase 7 — Code Review & PR
+
+**Entrada:** branch com CI verde
+**Saída:** PR aprovado e merged para `main`
+
+### Checklist PR
+- [ ] Branch actualizada com `main`
+- [ ] Todos os testes passam localmente
+- [ ] Cobertura acima do threshold do projecto
+- [ ] Build sem erros
+- [ ] Auditoria de segurança sem vulnerabilidades críticas/altas
+- [ ] `CHANGELOG.md` actualizado
+- [ ] Documentação actualizada (se aplicável)
+- [ ] `STATUS.md` reflecte o novo estado
+
+### Reviewers verificam
+- Código segue convenções do projecto (CLAUDE.md / AGENTS.md)
+- Testes cobrem casos críticos
+- Sem código duplicado
+- Sem secrets hardcoded, inputs validados
+- `MEMORY.md` actualizado com decisões relevantes
+
+---
+
+## Fase 8 — Deploy & Validação
+
+**Entrada:** PR merged para `main`
+**Saída:** versão em produção validada
+
+Seguir `PROC-DEPLOY-STANDARD.md` (D7-SIS-005) na íntegra.
+
+Após deploy:
+- Actualizar `STATUS.md` com versão deployada
+- Registar em `MEMORY.md`: versão, data, o que foi deployado
+- Fechar task Desk CRM correspondente + registar tempo
+
+---
+
+## Gestão de Ferramentas: Gitea vs Desk CRM
+
+### Divisão de responsabilidades
+
+| O quê | Onde | Nunca em |
+|-------|------|----------|
+| Bugs, issues técnicas, PRs, releases | **Gitea** | Desk CRM |
+| Projectos, sprints, tempo, facturação | **Desk CRM** | Gitea |
+| Código, commits, CI/CD | **Gitea** | — |
+| Cliente 360, propostas, pagamentos | **Desk CRM** | — |
+
+**Regra geral:** Gitea = tracker técnico. Desk CRM = gestão de projecto e facturação.
+
+### Sincronização manual (regras)
+
+1. **Bug descoberto** → criar issue Gitea (Issue-First Gate) → comentar na task Desk com URL da issue Gitea
+2. **Feature concluída** → fechar issue Gitea com `Closes #N` no commit → actualizar task Desk para "concluído" + registar tempo
+3. **PR merged** → `CHANGELOG.md` actualizado → `STATUS.md` actualizado
+4. **Deploy prod** → task Desk fechada → `MEMORY.md` regista versão deployada
+
+### Referências cruzadas obrigatórias
+
+- `.desk-project` contém: `task_id` Desk + `gitea_repo` + `gitea_project_id`
+- `MEMORY.md` regista IDs relevantes de ambos os sistemas
+- Commits referenciam `(#N)` da issue Gitea
+- Comentários Desk referenciam URL completa da issue/PR Gitea
+
+---
+
+## Gate Obrigatório — Issue-First (Bugs)
+
+**Regra não-negociável:** todo o bug passa por issue Gitea **antes** de qualquer commit de fix.
+
+**Fluxo:**
+1. Descoberta → criar issue com labels: `Bug` + severidade (`P: Critical/High/Medium/Low`) + área
+2. Branch `fix/N-descricao-curta`
+3. Commits com `(#N)` + `Fixes #N` no commit que fecha
+4. **Excepção hotfix:** fix cirúrgico urgente em prod → criar issue *post-hoc* com label `Backfill`, fechada à criação, com link ao commit
+
+---
+
+## Gate Obrigatório — Deploy Guard
+
+Ver `PROC-DEPLOY-STANDARD.md` (D7-SIS-005) — secção "Deploy Guard".
+
+**Regra:** CI tem de estar verde no último commit de `main` antes de qualquer deploy. Se abortar, não fazer override — investigar, corrigir, empurrar, esperar verde.
+
+---
+
+## Excepções Documentadas
+
+| Situação | Excepção permitida | Condições |
+|----------|-------------------|-----------|
+| Bug crítico em prod | Hotfix sem PR (push directo main) | Fix trivial e reversível; issue criada post-hoc |
+| Re-deploy sem código novo | workflow_dispatch | Após mudança de env vars |
+| Bugfix simples | Sem spec/plan | Apenas 1-2 ficheiros, causa raiz clara |
+| Continuação de plano | Sem nova spec | Plano existente aprovado, âmbito inalterado |
+
+---
+
+## Referências
+
+- `PROC-DEPLOY-STANDARD.md` — D7-SIS-005 (deploy para produção)
+- `ESTRUTURA.md` — hierarquia de projecto standard
+- `GOVERNANCA.md` — manifesto de qualidade
+- `PROTOCOLO-CRM.md` — integração Lean Gitea ↔ Desk CRM
+- `scripts/validate-structure.sh` — validação automática de estrutura
+- WhatSMS v2 `CONTRIBUTING.md` — implementação de referência
+
+---
+
+**Criado:** 2026-05-16 | **Aprovado por:** Emanuel Almeida | **Próximo passo:** writing-plans