ealmeida/bi-descomplicar

Fork 0

Files

T

ealmeida 75041136d2 chore: ignora graphify-out gerado

2026-10-28 15:59:30 +00:00

34 KiB

Raw Blame History

layer, type, tags, title, description, timestamp

layer

type

Ecosystem Alignment + PROC-DEV-STANDARD — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [x]) syntax for tracking.

Goal: Alinhar os 4 agentes do ecossistema (Claude, Gemini, Hermes, OpenCode) para operarem de forma consistente, e criar o PROC-DEV-STANDARD como protocolo de desenvolvimento partilhado.

Architecture: Criar ECOSYSTEM.md como fonte de verdade comum → actualizar cada config de agente com as secções em falta → criar PROC-DEV-STANDARD no Hub → criar resumo no modelo-organizacao.

Tech Stack: Markdown, Bash (chmod, validação), ficheiros de config YAML/JSON/MD

Ficheiros a Criar/Modificar

Acção	Ficheiro	Responsabilidade
Criar	`Hub/06-Operacoes/Documentacao/ECOSYSTEM.md`	Fonte de verdade comum — regras partilhadas por todos os agentes
Modificar	`~/.gemini/GEMINI.md`	Corrigir worklog HTML, adicionar STATUS.md, MEMORY.md criar, Gitea/Desk, Regra 48
Modificar	`~/.hermes/AGENTS.md`	Adicionar STATUS.md, MEMORY.md criar, Gitea/Desk, worklog, CARL, Regra 48
Modificar	`~/.config/opencode/AGENTS.md`	Adicionar tudo: MEMORY.md, STATUS.md, Sistema Triangular, CARL, Gitea/Desk, Regra 48
Modificar	`~/.claude/CLAUDE.md`	Adicionar STATUS.md ao protocolo de sessão
Criar	`Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md`	Protocolo de desenvolvimento ciclo completo
Criar	`Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md`	Resumo/referência do PROC
Criar	`Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-AUDIT-STANDARD.md`	Protocolo de auditoria (4 tipos)
Criar	`[projecto]/docs/audit/`	Estrutura de auditoria por projecto (template)

Task 1: Criar ECOSYSTEM.md — Fonte de Verdade Comum

Files:

Criar: Hub/06-Operacoes/Documentacao/ECOSYSTEM.md
Step 1: Criar o ficheiro ECOSYSTEM.md

cat > /media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/ECOSYSTEM.md << 'EOF'
---
title: Ecossistema Multi-Agente Descomplicar®
type: reference
status: active
date: 2026-05-16
tags: [ecossistema, agentes, protocolo, standard]
---

# ECOSYSTEM.md — Regras Comuns do Ecossistema Descomplicar®

**Fonte de verdade** para todos os agentes: Claude Code, Gemini CLI, Hermes/Izito, OpenCode.
Cada config de agente herda estas regras e pode adicionar as suas especificidades.

---

## 1. Identidade dos Agentes

| Agente | Config principal | staff_id Desk | Papel |
|--------|-----------------|---------------|-------|
| Claude Code | `~/.claude/CLAUDE.md` | 25 | Desenvolvimento, automação, orquestração |
| Gemini CLI | `~/.gemini/GEMINI.md` | — | Pesquisa, análise, tarefas longas |
| Hermes/Izito | `~/.hermes/SOUL.md` + `AGENTS.md` | 28 | Braço direito técnico, wiki, delegação |
| OpenCode | `~/.config/opencode/AGENTS.md` | — | Edição de código, contexto longo |
| Emanuel | — | 1 | Owner — timesheets sempre com staff_id=1 |

---

## 2. Protocolo de Sessão (todos os agentes)

### Início de sessão
1. Verificar data/hora actual (MCP `mcp-time` ou `date`)
2. Ler `.desk-project` se existir na raiz do projecto
3. Ler `MEMORY.md` se existir — se **não existir**, **criar** com cabeçalho:
   ```markdown
   # MEMORY.md — [Nome do Projecto]

Ler STATUS.md se existir — se não existir, criar com cabeçalho:

# STATUS.md — [Nome do Projecto]
**Versão:** — | **Data:** YYYY-MM-DD | **Agente:** [nome]
## Estado actual
- Em curso: —
- Bloqueios: —
- Próximos passos: —

Fim de sessão

Actualizar MEMORY.md (topo, ordem cronológica inversa) com:
- Decisões tomadas
- Paths/IDs relevantes descobertos
- Workarounds aplicados
Actualizar STATUS.md com estado actual, bloqueios e próximos passos
Registar tempo no Desk CRM se aplicável

3. Sistema Triangular

DESK CRM (Fonte Verdade) → Clientes, projectos, tarefas, tempo, facturas
HUB (Vault Obsidian)     → /media/ealmeida/Dados/Hub/ (00-Inbox a 99-Arquivo)
FICHEIROS (Local)        → /media/ealmeida/Dados/Dev/ (código)

4. Gitea vs Desk CRM — Routing Explícito

O quê	Sistema	Nunca em
Bugs, issues técnicas, PRs, releases	Gitea	Desk CRM
Código, commits, CI/CD	Gitea	—
Projectos, sprints, tarefas de gestão	Desk CRM	Gitea
Tempo (timesheets), facturação	Desk CRM	Gitea
Cliente 360, propostas, leads	Desk CRM	Gitea

Regra de sincronização:

Bug descoberto → criar issue Gitea → comentar na task Desk com URL
Feature concluída → fechar issue Gitea → actualizar task Desk + registar tempo
Deploy prod → task Desk fechada → MEMORY.md regista versão

5. Formato de Worklog (standard markdown PT-PT)

## [Projecto] — YYYY-MM-DD

### O que foi feito
- [alteração concreta]

### Ficheiros alterados
- `path/ficheiro.ext`

### Próximos passos
- [próxima acção]

6. Regras Core

Regra	Descrição
PT-PT Strict	Português europeu SEMPRE — acentos, cedilhas, 95EUR. Zero brasileirismos em tudo
Zero Assumptions	Verificar via ficheiros ou MCP antes de afirmar. Confiança <80% → dizer explicitamente
Dados Reais	MCPs → Ficheiros → WebFetch. Nunca simular, nunca inventar URLs/paths/IDs
Causa Raiz	Resolver sempre a causa, não o sintoma
Regra 48 — Dev Local	Todo o desenvolvimento em `/media/ealmeida/Dados/Dev/` (desktop). CT 102 extinto em 20-04-2026. Nunca usar `ssh_execute(server="dev")`
PDCA	Plan → Do → Check → Act. Nunca agir sem plano
Segurança	Confirmação obrigatória antes de: `rm -rf`, `DROP TABLE`, force-push, comandos destrutivos em produção

7. Sistema CARL

Domínios contextuais em /media/ealmeida/Dados/.carl/carl.json. Consultar antes de responder sobre: desenvolvimento, CRM, WordPress, Hub, infraestrutura, qualidade, skills.

8. LLM Wiki

~/wiki/ — base de conhecimento compilada do stack.

Ler: qualquer agente pode ler (~/wiki/index.md, grep -ril "termo" ~/wiki/)
Escrever: apenas Hermes/Izito
Protocolo ao iniciar: ~/wiki/SCHEMA.md → ~/wiki/index.md → ~/wiki/log.md (últimas 20 linhas)

9. MCPs Essenciais por Agente

MCP	Claude	Gemini	Hermes	OpenCode
desk-crm-v3	✅	✅	✅	activar
gitea	✅	✅	✅	✅
memory-supabase	✅	✅	✅	✅
mcp-time	✅	adicionar	adicionar	✅
ssh-unified	✅	✅	✅	✅
notebooklm	✅	✅	—	✅ (wrapper)

Última actualização: 2026-05-16 Mantido por: Emanuel Almeida EOF


- [x] **Step 2: Verificar que o ficheiro foi criado correctamente**

```bash
wc -l /media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/ECOSYSTEM.md
head -5 /media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/ECOSYSTEM.md

Esperado: >80 linhas, cabeçalho frontmatter visível.

Task 2: Actualizar GEMINI.md

Files:

Modificar: ~/.gemini/GEMINI.md

Problemas a corrigir: worklog HTML → markdown, adicionar STATUS.md, MEMORY.md criar se não existe, Gitea/Desk routing, Regra 48.

Step 1: Fazer backup

cp ~/.gemini/GEMINI.md ~/.gemini/GEMINI.md.bak-2026-05-16

Step 2: Ler o ficheiro actual

cat ~/.gemini/GEMINI.md

Step 3: Substituir secção de Memória e adicionar secções em falta

Localizar a secção ## 3. Autonomia e Ferramentas → subsecção **Memória:** e substituir:

**Memória:** 
  - **Sessão:** `MEMORY.md` na raiz do projecto (partilhado com Claude Code e OpenCode). Ler ao iniciar, escrever ao terminar. Formato: secções por data, ordem cronológica inversa.

Por:

**Memória:**
  - **Sessão:** `MEMORY.md` na raiz do projecto (partilhado com todos os agentes).
    - Ler ao iniciar sessão
    - Se **não existir**, criar com cabeçalho `# MEMORY.md — [Nome Projecto]`
    - Escrever no fim com factos novos (topo, ordem cronológica inversa)
  - **STATUS.md:** ficheiro de estado vivo do projecto.
    - Ler ao iniciar sessão
    - Se **não existir**, criar com cabeçalho e campos: Versão, Data, Agente, Em curso, Bloqueios, Próximos passos
    - Actualizar no fim de sessão com estado actual
  - **Referência:** `Hub/06-Operacoes/Documentacao/ECOSYSTEM.md` — regras comuns a todos os agentes

Step 4: Substituir formato de worklog (HTML → markdown)

Localizar:

`<h4>[Projecto] - Descrição</h4><ul><li>Alteração</li></ul><p><strong>Ficheiros:</strong> <code>path</code></p><hr><p><strong>Data:</strong> YYYY-MM-DD</p>`

Substituir por:

```markdown
## [Projecto] — YYYY-MM-DD
### O que foi feito
- [alteração concreta]
### Ficheiros alterados
- `path/ficheiro.ext`
### Próximos passos
- [próxima acção]


- [x] **Step 5: Adicionar secção Gitea vs Desk CRM**

Após a secção `## 2. Sistema CARL`, adicionar:

```markdown
## 5. Gitea vs Desk CRM

| O quê | Sistema |
|-------|---------|
| Bugs, issues, PRs, código | **Gitea** |
| Tarefas gestão, tempo, facturação, clientes | **Desk CRM** |

Bug descoberto → issue Gitea primeiro → comentar Desk com URL.
Feature concluída → fechar Gitea → actualizar Desk + registar tempo.

Step 6: Adicionar Regra 48

Na secção de regras core, adicionar:

- **Regra 48 — Dev Local:** Todo o desenvolvimento em `/media/ealmeida/Dados/Dev/` (desktop local). CT 102 extinto em 20-04-2026. **Nunca** usar `ssh_execute(server="dev")`.

Step 7: Verificar resultado

grep -n "STATUS.md\|MEMORY.md\|Gitea\|Regra 48\|markdown" ~/.gemini/GEMINI.md

Esperado: todas as strings presentes.

Task 3: Actualizar Hermes AGENTS.md

Files:

Modificar: ~/.hermes/AGENTS.md

Problemas a corrigir: adicionar STATUS.md, MEMORY.md criar se não existe, Gitea/Desk routing, worklog, CARL domínios, Regra 48.

Step 1: Fazer backup

cp ~/.hermes/AGENTS.md ~/.hermes/AGENTS.md.bak-2026-05-16

Step 2: Actualizar secção MEMORY.md

Localizar:

## MEMORY.md

Cada projeto pode ter um `MEMORY.md` na raiz. Se existir:
- **Ler** ao iniciar sessão no projeto
- **Escrever** no final com factos novos (topo, ordem cronológica inversa)
- **Formato:** secções por data, markdown simples, decisões + técnico + IDs

Substituir por:

## Protocolo de Sessão

### MEMORY.md
Cada projecto tem (ou deve ter) um `MEMORY.md` na raiz:
- **Ler** ao iniciar sessão no projecto
- Se **não existir**, **criar** com cabeçalho: `# MEMORY.md — [Nome Projecto]`
- **Escrever** no final com factos novos (topo, ordem cronológica inversa)
- **Formato:** secções por data, markdown simples, decisões + técnico + IDs

### STATUS.md
Ficheiro de estado vivo do projecto:
- **Ler** ao iniciar sessão
- Se **não existir**, **criar** com estrutura:

STATUS.md — [Nome Projecto]

Versão: — | Data: YYYY-MM-DD | Agente: Izito

Estado actual

Em curso: —
Bloqueios: —
Próximos passos: —

- **Actualizar** no fim de sessão com estado actual e próximos passos

Step 3: Adicionar Gitea vs Desk CRM

Após a secção ## Sistema Triangular, adicionar:

## Gitea vs Desk CRM

| O quê | Sistema |
|-------|---------|
| Bugs, issues técnicas, PRs, código | **Gitea** |
| Tarefas gestão, tempo, facturação, leads | **Desk CRM** |

**Fluxo:** Bug → issue Gitea → comentar Desk com URL → fix → fechar Gitea → actualizar Desk + tempo.

Step 4: Adicionar worklog standard

Adicionar secção:

## Worklog (formato standard)

```markdown
## [Projecto] — YYYY-MM-DD
### O que foi feito
- [alteração concreta]
### Ficheiros alterados
- `path/ficheiro.ext`
### Próximos passos
- [próxima acção]

Registar também como comentário na task Desk CRM correspondente.


- [x] **Step 5: Actualizar referência CARL**

Localizar referência ao CARL e expandir:

```markdown
## Sistema CARL

Domínios contextuais em `/media/ealmeida/Dados/.carl/carl.json`.
Usar MCP `carl` para recall por keyword antes de responder sobre:
- DEVELOPMENT, CRM, WORDPRESS, HUB, INFRASTRUCTURE, QUALITY, SKILLS

Consultar sempre que o prompt contiver keywords técnicas do stack.

Step 6: Adicionar Regra 48

Adicionar à secção de Convenções ou Regras:

## Regra 48 — Desenvolvimento Local

Todo o desenvolvimento em `/media/ealmeida/Dados/Dev/` (desktop local).
CT 102 extinto em 20-04-2026. **Nunca** usar `ssh_execute(server="dev")`.
Automações migradas para systemd user timers no desktop.

Step 7: Verificar resultado

grep -n "STATUS.md\|criar\|Gitea\|worklog\|Regra 48\|CARL" ~/.hermes/AGENTS.md

Esperado: todas as strings presentes.

Task 4: Actualizar OpenCode AGENTS.md

Files:

Modificar: ~/.config/opencode/AGENTS.md

O OpenCode é o mais nu — precisa de tudo.

Step 1: Fazer backup

cp ~/.config/opencode/AGENTS.md ~/.config/opencode/AGENTS.md.bak-2026-05-16

Step 2: Ler o ficheiro actual

cat ~/.config/opencode/AGENTS.md

Step 3: Adicionar protocolo de sessão completo

Adicionar após o cabeçalho existente (PT-PT + Wiki):

## Sistema Triangular

DESK CRM (Fonte Verdade) → Clientes, projectos, tarefas, tempo, facturas HUB (Vault Obsidian) → /media/ealmeida/Dados/Hub/ FICHEIROS (Local) → /media/ealmeida/Dados/Dev/ (código)


## Protocolo de Sessão

### Início
1. Verificar data actual
2. Ler `.desk-project` se existir na raiz do projecto
3. Ler `MEMORY.md` — se **não existir**, criar:

MEMORY.md — [Nome Projecto]

4. Ler `STATUS.md` — se **não existir**, criar:

STATUS.md — [Nome Projecto]

Data: YYYY-MM-DD | Agente: OpenCode

Estado actual

Em curso: —
Bloqueios: —
Próximos passos: —


### Fim
1. Actualizar `MEMORY.md` (topo) com decisões, paths e IDs relevantes
2. Actualizar `STATUS.md` com estado actual e próximos passos

## Gitea vs Desk CRM

| O quê | Sistema |
|-------|---------|
| Bugs, issues técnicas, PRs, código | **Gitea** |
| Tarefas, tempo, facturação, leads | **Desk CRM** |

Bug → issue Gitea → comentar Desk com URL → fix → fechar Gitea → actualizar Desk.

## Worklog (formato standard)

```markdown
## [Projecto] — YYYY-MM-DD
### O que foi feito
- [alteração concreta]
### Ficheiros alterados
- `path/ficheiro.ext`

Sistema CARL

Domínios contextuais em /media/ealmeida/Dados/.carl/carl.json. Consultar antes de responder sobre: desenvolvimento, CRM, Hub, infraestrutura.

Regra 48 — Desenvolvimento Local

Todo o desenvolvimento em /media/ealmeida/Dados/Dev/ (desktop). CT 102 extinto em 20-04-2026. Nunca usar SSH para servidor dev remoto.

Staff IDs Desk CRM

Emanuel: staff_id=1 (timesheets sempre com este ID)
Claude Code: staff_id=25
Hermes/Izito: staff_id=28


- [x] **Step 4: Activar desk-crm-v3 no opencode.json**

```bash
python3 -c "
import json
with open('/home/ealmeida/.config/opencode/opencode.json', 'r') as f:
    d = json.load(f)
d['mcp']['desk-crm-v3']['enabled'] = True
with open('/home/ealmeida/.config/opencode/opencode.json', 'w') as f:
    json.dump(d, f, indent=2)
print('desk-crm-v3 activado')
"

Step 5: Verificar resultado

grep -n "STATUS.md\|MEMORY.md\|Gitea\|CARL\|Regra 48\|staff_id" ~/.config/opencode/AGENTS.md
python3 -c "import json; d=json.load(open('/home/ealmeida/.config/opencode/opencode.json')); print('desk-crm-v3:', d['mcp']['desk-crm-v3']['enabled'])"

Esperado: todas as strings presentes; desk-crm-v3: True.

Task 5: Actualizar CLAUDE.md — Adicionar STATUS.md

Files:

Modificar: ~/.claude/CLAUDE.md
Step 1: Localizar a Regra 19 (Data Sessão) no CLAUDE.md

grep -n "STATUS\|Data Sessão\|MEMORY\|sessão" ~/.claude/CLAUDE.md | head -20

Step 2: Adicionar STATUS.md à tabela de regras

Na tabela de REGRAS CORE, após a linha da Regra 19, adicionar:

| 20 | **STATUS.md** — Ler ao iniciar sessão de projecto. Criar se não existir. Actualizar no fim com estado actual, bloqueios e próximos passos |

Step 3: Verificar

grep -n "STATUS.md" ~/.claude/CLAUDE.md

Esperado: pelo menos 1 ocorrência.

Task 6: Criar PROC-DEV-STANDARD.md

Files:

Criar: Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md
Step 1: Criar o PROC completo

cat > /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md << 'PROCEOF'
---
title: Desenvolvimento Standard — Protocolo de Ciclo Completo
type: procedure
code: D7-SIS-006
department: D7-Tecnologia
subdepartment: Sistema
status: active
date: 2026-05-16
tags: [desenvolvimento, ciclo, protocolo, standard, gitea, desk-crm]
---

# PROC-DEV-STANDARD — Protocolo de Desenvolvimento (Ciclo Completo)

**Última actualização:** 2026-05-16
**Aplicável a:** todos os projectos Descomplicar®
**Fonte:** Extraído da experiência WhatSMS v2 + auditoria de ecossistema 2026-05-16

---

## Princípios

1. **Pesquisa antes de spec** — nunca especificar sem investigar
2. **Spec antes de código** — nada entra em código sem spec aprovada (excepções: bugfix, operação unitária)
3. **CI verde é gate obrigatório** — nunca deployar sobre CI vermelho
4. **Issue-First para bugs** — todo o bug tem issue Gitea antes do fix
5. **Contexto partilhado** — MEMORY.md e STATUS.md actualizados em cada sessão
6. **Causa raiz** — resolver sempre a causa, não o sintoma

---

## Fluxo Completo

Ideia → Pesquisa (deep research + NLM) → Spec (SPEC.md aprovado) → Plan (docs/PLANS/) → Desenvolvimento (feat/* → commits atómicos) → Quality Gates (pre-commit → CI) → Code Review & PR (Gitea) → Deploy & Validação (PROC-DEPLOY-STANDARD D7-SIS-005)


---

## Estrutura de Projecto Obrigatória

/ (root) ├── docs/ │ ├── PLANS/ # Planos de implementação │ └── SPECS/ # Specs técnicas + notas de pesquisa ├── AGENTS.md # Directrizes para agentes (obrigatório) ├── CHANGELOG.md # Histórico de versões ├── MEMORY.md # Contexto cross-agent (obrigatório) ├── STATUS.md # Estado vivo do projecto (obrigatório) └── .desk-project # Ligação Desk CRM (JSON, obrigatório)


---

## Ficheiros Cross-Agent

| Ficheiro | Quem lê | Quem escreve | Quando |
|----------|---------|--------------|--------|
| `MEMORY.md` | Todos | Todos | Início (ler/criar) + fim (escrever) |
| `STATUS.md` | Todos | Agente activo | Início (ler/criar) + fim (actualizar) |
| `AGENTS.md` | Todos | Owner | Quando mudam as regras |
| `CHANGELOG.md` | Todos | Agente activo | A cada versão/sprint |

**Protocolo de sessão (qualquer agente):**
1. Início → ler `MEMORY.md` + `STATUS.md` (criar se não existem)
2. Durante → registar decisões relevantes em `MEMORY.md`
3. Fim → actualizar `STATUS.md` + `MEMORY.md`

---

## Fase 1 — Ideia

**Entrada:** pedido ou ideia
**Saída:** decisão de avançar + âmbito inicial

- Verificar que não existe funcionalidade equivalente
- Verificar alinhamento com MASTER-PLAN
- Âmbito suficientemente claro para pesquisar

---

## Fase 2 — Pesquisa

**Entrada:** ideia com âmbito definido
**Saída:** `docs/SPECS/research-YYYY-MM-DD-tema.md`

1. Identificar domínio
2. Verificar NLMs existentes via `/knowledge` (65 notebooks)
   - Domínio coberto → usar NLM existente
   - Domínio novo + pesquisa extensa → criar NLM dedicado (apenas se estritamente necessário)
3. Deep research: WebSearch + WebFetch + NLM
4. Sintetizar: decisões, alternativas descartadas, riscos
5. Guardar nota em `docs/SPECS/`

---

## Fase 3 — Spec

**Entrada:** nota de pesquisa aprovada
**Saída:** SPEC.md aprovado em `docs/SPECS/`

- Usar `/brainstorm` → `/spec` para trabalho não-trivial
- Design doc salvo em `docs/SPECS/YYYY-MM-DD-tema-design.md`
- Excepções: bugfix, operação unitária, continuação de plano

---

## Fase 4 — Plan

**Entrada:** spec aprovada
**Saída:** plano em `docs/PLANS/YYYY-MM-DD-tema.md`

- Usar `/writing-plans` para decompor em tarefas executáveis
- Cada tarefa com critério de aceitação claro

---

## Fase 5 — Desenvolvimento

**Entrada:** plano aprovado
**Saída:** commits atómicos em branch dedicada

### Branch strategy
- `main` — produção (protegida)
- `feat/N-descricao` — novas funcionalidades
- `fix/N-descricao` — bugs (N = número da issue Gitea)

### Commits (Conventional Commits)

tipo(scope): descrição breve (#N)

Closes #N Co-Authored-By: [Agente] noreply@anthropic.com


Tipos: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`

---

## Fase 6 — Quality Gates

| Gate | Momento | O que verifica |
|------|---------|----------------|
| Pre-commit | Automático | Formatação, lint |
| Pre-push | Manual | Build, testes, cobertura, segurança |
| CI | Automático (push) | Tudo + report cobertura |

Thresholds definidos no `CONTRIBUTING.md` do projecto.
**Regra:** nunca PR sem CI verde.

---

## Fase 7 — Code Review & PR

### Checklist PR
- [x] Branch actualizada com `main`
- [x] Testes passam localmente
- [x] Cobertura acima do threshold
- [x] Build sem erros
- [x] Auditoria segurança sem vulnerabilidades críticas/altas
- [x] `CHANGELOG.md` actualizado
- [x] `STATUS.md` reflecte novo estado

---

## Fase 8 — Deploy & Validação

Ver `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 + registar tempo

---

## Gestão de Ferramentas: Gitea vs Desk CRM

| O quê | Onde |
|-------|------|
| Bugs, issues técnicas, PRs, releases, código | **Gitea** |
| Projectos, sprints, tempo, facturação, cliente | **Desk CRM** |

### Sincronização manual
1. Bug → issue Gitea → comentar Desk com URL
2. Feature concluída → fechar Gitea → actualizar Desk + tempo
3. PR merged → `CHANGELOG.md` + `STATUS.md` actualizados
4. Deploy → task Desk fechada → `MEMORY.md` regista versão

### Referências cruzadas
- `.desk-project`: `task_id` Desk + `gitea_repo`
- `MEMORY.md`: IDs de ambos os sistemas
- Commits: `(#N)` da issue Gitea

---

## Gate Obrigatório — Issue-First (Bugs)

**Regra não-negociável:** todo o bug tem issue Gitea antes do fix.

1. Descoberta → criar issue com labels: `Bug` + severidade + área
2. Branch `fix/N-descricao`
3. Commits com `(#N)` + `Fixes #N`
4. **Hotfix urgente:** criar issue post-hoc com label `Backfill`, fechada à criação

---

## Excepções

| Situação | Excepção | Condições |
|----------|----------|-----------|
| Bug crítico prod | Hotfix sem PR | Fix trivial e reversível; issue post-hoc |
| Re-deploy sem código | workflow_dispatch | Após mudança env vars |
| Bugfix simples | Sem spec/plan | 1-2 ficheiros, causa raiz clara |
| Continuação de plano | Sem nova spec | Plano aprovado, âmbito inalterado |

---

## Referências

- `PROC-DEPLOY-STANDARD.md` — D7-SIS-005
- `ECOSYSTEM.md` — `Hub/06-Operacoes/Documentacao/ECOSYSTEM.md`
- `ESTRUTURA.md` — hierarquia de projecto standard
- `scripts/validate-structure.sh` — validação automática
- WhatSMS v2 `CONTRIBUTING.md` — implementação de referência

---

**Desk CRM:** Modelo-Organizacao-Proc-Dev · Task #2134 · Domínio CARL: MODELO-ORGANIZACAO
PROCEOF

Step 2: Verificar criação

wc -l /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md
grep "^code:" /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md

Esperado: >150 linhas; code: D7-SIS-006

Task 7: Criar PROC-DEV-STANDARD-ref.md no Modelo

Files:

Criar: Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md
Step 1: Criar ficheiro de referência

cat > /media/ealmeida/Dados/Hub/05-Projectos/Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md << 'EOF'
# PROC-DEV-STANDARD — Referência Rápida

**Fonte de verdade:** `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md` (D7-SIS-006)

---

## Fluxo

Ideia → Pesquisa → Spec → Plan → Dev → Quality Gates → PR → Deploy


## Estrutura Mínima de Projecto

MEMORY.md / STATUS.md / AGENTS.md / CHANGELOG.md / .desk-project docs/PLANS/ + docs/SPECS/


## Gitea vs Desk

| Gitea | Desk CRM |
|-------|----------|
| Bugs, PRs, código | Tarefas, tempo, clientes |

## Gate de Bugs

Bug → issue Gitea → branch fix/N → fix → Closes #N → actualizar Desk

## Excepções ao pipeline

Bugfix simples, hotfix, continuação de plano existente.

---

**Ver PROC completo para todos os detalhes.**
EOF

Step 2: Verificar

cat /media/ealmeida/Dados/Hub/05-Projectos/Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md

Task 8: Actualizar MEMORY.md e CARL

Files:

Modificar: Modelo-Organizacao-Proc-Dev/MEMORY.md
Verificar: domínio CARL MODELO-ORGANIZACAO
Step 1: Actualizar MEMORY.md do projecto

Adicionar ao topo do MEMORY.md:

## 2026-05-16
- **Auditoria ecossistema:** questionários directos a Gemini, Hermes, OpenCode via aionui. Relatório em `docs/SPECS/2026-05-16-ecosystem-audit.md`
- **Segurança OpenCode:** credenciais NotebookLM movidas para `~/.opencode-secrets` (600). Wrapper em `~/.opencode-wrappers/`. Permissões claude.json + settings.json corrigidas para 600.
- **ECOSYSTEM.md criado:** `Hub/06-Operacoes/Documentacao/ECOSYSTEM.md` — fonte de verdade comum
- **PROC-DEV-STANDARD criado:** D7-SIS-006 em `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/`
- **Configs actualizadas:** GEMINI.md, Hermes/AGENTS.md, OpenCode/AGENTS.md, CLAUDE.md
- **skill brainstorming:** caminho docs/SPECS/ corrigido (era docs/superpowers/specs/)
- **Task Desk #2134:** Em Curso

Step 2: Verificar domínio CARL

cat /media/ealmeida/Dados/.carl/carl.json | python3 -m json.tool | grep -A5 "MODELO-ORGANIZACAO"

Esperado: domínio com 7+ regras presente.

Task 9: Criar PROC-AUDIT-STANDARD.md

Files:

Criar: Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-AUDIT-STANDARD.md
Step 1: Criar o PROC de auditoria

cat > /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-AUDIT-STANDARD.md << 'EOF'
---
title: Auditoria Standard — Protocolo de 4 Tipos
type: procedure
code: D7-SIS-007
department: D7-Tecnologia
subdepartment: Sistema
status: active
date: 2026-05-16
tags: [auditoria, segurança, qualidade, ecossistema, projecto]
---

# PROC-AUDIT-STANDARD — Protocolo de Auditoria (4 Tipos)

**Última actualização:** 2026-05-16
**Aplicável a:** todos os projectos Descomplicar®

---

## Tipos de Auditoria

| Tipo | Código | Frequência | Gatilho adicional |
|------|--------|------------|-------------------|
| Código | AUDIT-CODE | Mensal | Antes de cada deploy prod |
| Segurança | AUDIT-SEC | Mensal | Antes de cada deploy prod |
| Ecossistema | AUDIT-ECO | Trimestral | Após mudança de agente/config |
| Projecto | AUDIT-PROJ | Semanal/sprint | Início de sprint |

---

## Estrutura de Findings

Cada projecto com auditorias activas mantém:

docs/audit/ ├── audit.md # Log master de todas as auditorias ├── security.md # Findings de segurança activos ├── tech-debt.md # Dívida técnica registada └── findings/ └── F-NNN-descricao.md # Um ficheiro por finding


### Formato de Finding (F-NNN-descricao.md)

```markdown
# F-NNN — Título do Finding

**Data:** YYYY-MM-DD
**Tipo:** CODE | SEC | ECO | PROJ
**Severidade:** Critical | High | Medium | Low
**Estado:** Open | In Progress | Resolved | Accepted Risk

## Descrição
[O que foi encontrado]

## Impacto
[Consequência se não resolvido]

## Resolução
[O que foi feito ou planear fazer]

## Referências
- Issue Gitea: #N
- Commit: [hash]

AUDIT-CODE — Auditoria de Código

Checklist:

Lint sem erros (npm run lint / equivalente stack)
Build sem erros (npm run build / equivalente)
Testes passam (npm test / equivalente)
Cobertura acima do threshold do projecto
Sem TODO / FIXME não rastreados em issues Gitea
CHANGELOG.md actualizado
Dependências sem versões muito desactualizadas (major version lag >2)

Output: entrada em docs/audit/audit.md + findings em docs/audit/findings/ se aplicável.

AUDIT-SEC — Auditoria de Segurança

Checklist:

Auditoria de dependências (npm audit --audit-level=high / equivalente)
Scan de credenciais: nenhum secret em código ou configs com permissões >600
Verificar ficheiros de config de agentes: permissões 600
OWASP Top 10 — verificar inputs validados, sem SQL injection, sem XSS
Tokens/API keys — rotação se >90 dias sem rotação
Variáveis de ambiente — todas em .env (gitignored), nunca hardcoded

Output: entrada em docs/audit/security.md + findings críticos em issues Gitea com label Security.

AUDIT-ECO — Auditoria de Ecossistema

Frequência: trimestral ou após mudança de agente/config.

Checklist:

Todos os agentes conhecem STATUS.md e MEMORY.md
Todos os agentes têm Regra 48 (dev local, sem CT 102)
Todos os agentes têm regras Gitea vs Desk CRM
Worklog em formato markdown PT-PT em todos
MCPs essenciais activos: desk-crm-v3, gitea, memory-supabase, mcp-time
Credenciais em plaintext — nenhuma em ficheiros com permissões >600
Referências extintas removidas (servidores, paths, IDs obsoletos)
CARL domínios actualizados e correctos

Método: questionário directo a cada agente (ver modelo em docs/SPECS/2026-05-16-ecosystem-audit.md).

Output: relatório em docs/SPECS/YYYY-MM-DD-ecosystem-audit.md + findings em docs/audit/findings/.

AUDIT-PROJ — Auditoria de Projecto

Frequência: semanal ou início de sprint.

Checklist:

MEMORY.md actualizado (última entrada ≤7 dias)
STATUS.md actualizado (última entrada ≤7 dias)
Issues Gitea abertas sem PR associado há >14 dias → rever prioridade
Tasks Desk CRM em "Em Curso" há >14 dias sem actividade → rever ou fechar
Timesheets registados para todo o trabalho da semana
CHANGELOG.md reflecte o que foi deployado
Sem branches feat/* ou fix/* com >30 dias sem merge → limpar ou fechar

Output: entrada em docs/audit/audit.md.

Integração com PROC-DEV-STANDARD

AUDIT-CODE + AUDIT-SEC correm automaticamente em CI (pre-deploy)
AUDIT-PROJ corre no início de cada sprint (manual)
AUDIT-ECO corre trimestralmente (manual, via questionário aionui ou directo)
Findings com severidade Critical/High → issue Gitea obrigatória (Issue-First Gate)

Referências

PROC-DEV-STANDARD.md — D7-SIS-006
ECOSYSTEM.md — Hub/06-Operacoes/Documentacao/ECOSYSTEM.md
WhatSMS v2 docs/audit/ — implementação de referência

Desk CRM: Modelo-Organizacao-Proc-Dev · Task #2134 EOF


- [x] **Step 2: Verificar criação**

```bash
wc -l /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-AUDIT-STANDARD.md
grep "^code:" /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-AUDIT-STANDARD.md

Esperado: >120 linhas; code: D7-SIS-007

Task 10: Adicionar Secção de Auditoria ao PROC-DEV-STANDARD

Files:

Modificar: Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md
Step 1: Adicionar estrutura docs/audit/ à secção de estrutura de projecto

Localizar a secção ## Estrutura de Projecto Obrigatória e adicionar docs/audit/ ao tree:

├── docs/
│   ├── PLANS/       # Planos de implementação
│   ├── SPECS/       # Specs técnicas + notas de pesquisa
│   └── audit/       # Auditorias e findings (se projecto activo)
│       ├── audit.md
│       ├── security.md
│       ├── tech-debt.md
│       └── findings/

Step 2: Adicionar referência à secção de Referências

Na secção ## Referências, adicionar:

- `PROC-AUDIT-STANDARD.md` — D7-SIS-007 (auditoria: código, segurança, ecossistema, projecto)

Step 3: Verificar

grep -n "audit\|AUDIT\|D7-SIS-007" /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md

Esperado: 3+ ocorrências.

Validação Final

Verificar todos os ficheiros criados

ls -la \
  /media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/ECOSYSTEM.md \
  /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md \
  /media/ealmeida/Dados/Hub/05-Projectos/Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md

Verificar configs actualizadas

grep -l "STATUS.md" ~/.gemini/GEMINI.md ~/.hermes/AGENTS.md ~/.config/opencode/AGENTS.md ~/.claude/CLAUDE.md

Esperado: 4 ficheiros listados.

Executar validate-structure.sh

bash /media/ealmeida/Dados/Hub/05-Projectos/Modelo-Organizacao-Proc-Dev/scripts/validate-structure.sh

Esperado: 0 falhas, 0 avisos.

Criado: 2026-05-16 | Baseado em: auditoria multi-agente via aionui

34 KiB Raw Blame History

Ecosystem Alignment + PROC-DEV-STANDARD — Implementation Plan

Ficheiros a Criar/Modificar

Task 1: Criar ECOSYSTEM.md — Fonte de Verdade Comum

Fim de sessão

3. Sistema Triangular

4. Gitea vs Desk CRM — Routing Explícito

5. Formato de Worklog (standard markdown PT-PT)

6. Regras Core

7. Sistema CARL

8. LLM Wiki

9. MCPs Essenciais por Agente

Task 2: Actualizar GEMINI.md

Task 3: Actualizar Hermes AGENTS.md

STATUS.md — [Nome Projecto]

Estado actual

Task 4: Actualizar OpenCode AGENTS.md

MEMORY.md — [Nome Projecto]

STATUS.md — [Nome Projecto]

Estado actual

Sistema CARL

Regra 48 — Desenvolvimento Local

Staff IDs Desk CRM

Task 5: Actualizar CLAUDE.md — Adicionar STATUS.md

Task 6: Criar PROC-DEV-STANDARD.md

Task 7: Criar PROC-DEV-STANDARD-ref.md no Modelo

Task 8: Actualizar MEMORY.md e CARL

Task 9: Criar PROC-AUDIT-STANDARD.md

AUDIT-CODE — Auditoria de Código

AUDIT-SEC — Auditoria de Segurança

AUDIT-ECO — Auditoria de Ecossistema

AUDIT-PROJ — Auditoria de Projecto

Integração com PROC-DEV-STANDARD

Referências

Task 10: Adicionar Secção de Auditoria ao PROC-DEV-STANDARD

Validação Final

34 KiB

Raw Blame History