From 75041136d26dc148df55083e79d5351806a9dddd Mon Sep 17 00:00:00 2001 From: Emanuel Almeida Date: Wed, 28 Oct 2026 15:59:30 +0000 Subject: [PATCH] chore: ignora graphify-out gerado --- .gitignore | 2 +- AGENTS.md | 98 ++ CICLO-VIDA-PROJECTO.md | 148 +++ ESTRUTURA.md | 89 ++ GOVERNANCA.md | 42 + INSTRUCOES.md | 20 + MEMORY.md | 69 + PROTOCOLO-CRM.md | 48 + STATUS.md | 25 + desk.project | 6 + docs/PLANS/2026-05-16-ecosystem-alignment.md | 1147 +++++++++++++++++ docs/PLANS/BRAINSTORM.md | 10 + docs/PLANS/PLAN.md | 10 + docs/SPECS/2026-05-16-ecosystem-audit.md | 106 ++ .../2026-05-16-proc-dev-standard-design.md | 347 +++++ docs/SPECS/BRIEF.md | 10 + docs/SPECS/PROC-DEV-STANDARD-ref.md | 120 ++ docs/SPECS/SPEC.md | 11 + docs/SPECS/Workflow-Diagram.html | 353 +++++ docs/SPECS/Workflow-Fluxo.drawio | 195 +++ docs/SPECS/research.md | 10 + docs/audit/audit.md | 49 + .../findings/F-001-hermes-mcps-incompletos.md | 53 + .../findings/F-002-gemini-mcps-parciais.md | 44 + index.md | 9 + log.md | 3 + 26 files changed, 3023 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md create mode 100644 CICLO-VIDA-PROJECTO.md create mode 100644 ESTRUTURA.md create mode 100644 GOVERNANCA.md create mode 100644 INSTRUCOES.md create mode 100644 MEMORY.md create mode 100644 PROTOCOLO-CRM.md create mode 100644 STATUS.md create mode 100644 desk.project create mode 100644 docs/PLANS/2026-05-16-ecosystem-alignment.md create mode 100644 docs/PLANS/BRAINSTORM.md create mode 100644 docs/PLANS/PLAN.md create mode 100644 docs/SPECS/2026-05-16-ecosystem-audit.md create mode 100644 docs/SPECS/2026-05-16-proc-dev-standard-design.md create mode 100644 docs/SPECS/BRIEF.md create mode 100644 docs/SPECS/PROC-DEV-STANDARD-ref.md create mode 100644 docs/SPECS/SPEC.md create mode 100644 docs/SPECS/Workflow-Diagram.html create mode 100644 docs/SPECS/Workflow-Fluxo.drawio create mode 100644 docs/SPECS/research.md create mode 100644 docs/audit/audit.md create mode 100644 docs/audit/findings/F-001-hermes-mcps-incompletos.md create mode 100644 docs/audit/findings/F-002-gemini-mcps-parciais.md create mode 100644 index.md create mode 100644 log.md diff --git a/.gitignore b/.gitignore index af9adac..e8aa1b6 100644 --- a/.gitignore +++ b/.gitignore @@ -47,7 +47,7 @@ next-env.d.ts .claude/cache/ .gemini/ .ijfw/ -graphify-out/cache/ +graphify-out/ # Backups do editor draw.io .xdp-* diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a555d3b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,98 @@ +--- +type: Document +title: Agents +description: Este documento define o papel, limites e responsabilidades dos agentes + de IA (Gemini CLI, Claude Code, Hermes) a operar … +timestamp: 2026-05-13 11:28:03.523803+00:00 +tags: +- dev +- codigo +- governance +- 5w2h +- roles +- escalacao +- relacionamentos +--- +# AGENTS.md — Governance de Agentes IA + +## Definição +Este documento define o papel, limites e responsabilidades dos agentes de IA (Gemini CLI, Claude Code, Hermes) a operar neste repositório. + +## Identidade do Projecto +- **Repositório**: bi-descomplicar +- **Localização**: `/media/ealmeida/Dados/Dev/bi-descomplicar/` +- **CRM**: Ver `desk.project` para referência do projecto +- **Domínio CARL**: `BI-DESCOMPLICAR` (ou conforme CRM) + +## Directrizes de Operação + +### 1. PT-PT e Precisão +Toda a interacção, comentários, commits e documentação devem ser em português europeu, com acentos e cedilhas. + +### 2. MCP-first +- **CRM (Desk Project Minimal)**: Consultar/actualizar task #2134 via MCP +- **Gitea (MCP Gitea)**: Commits e gestão de versões via MCP +- **CARL (MCP CARL)**: Consultar domínio `MODELO-ORGANIZACAO` para regras do modelo +- **SSH (MCP SSH Unificado)**: Apenas se necessário para validação remota + +### 3. Ciclo de Trabalho Obrigatório +1. **Validar contexto** — ler AGENTS.md + MEMORY.md + desk.project +2. **Consultar CARL** — verificar regras do domínio `MODELO-ORGANIZACAO` +3. **Executar** — seguir o standard ESTRUTURA.md +4. **Validar** — correr `scripts/validate-structure.sh` se disponível +5. **Registar** — actualizar MEMORY.md e CRM + +### 4. Validação Obrigatória +Nunca dar uma tarefa como concluída sem validar o estado via shell ou MCP. +Este projecto é o modelo canónico — qualquer alteração aqui propaga-se a todos os outros. + +### 5. CARL +Respeitar o domínio `MODELO-ORGANIZACAO` no CARL. As regras lá definidas têm precedência sobre documentação local em caso de conflito. + +## O Que Este Projecto Contém + +| Ficheiro | Função | +|---|---| +| `ESTRUTURA.md` | Standard de hierarquia obrigatório para projectos | +| `GOVERNANCA.md` | Manifesto de qualidade e conduta DEV | +| `PROTOCOLO-CRM.md` | Integração Lean Gitea & Desk CRM | +| `INSTRUCOES.md` | Visão geral e próximos passos | +| `MEMORY.md` | Registo cronológico de sessões | +| `AGENTS.md` | (Este ficheiro) Governance de agentes | +| `desk.project` | Ancoragem CRM (task #2134) | +| `scripts/validate-structure.sh` | Validação automática de conformidade | + +## Regra Anti-Pattern +- **Não** criar pastas `docs/PROC` ou `docs/RUNBOOK` — vivem no Hub centralizado +- **Não** duplicar procedimentos que existem em `06-Operacoes/Procedimentos/` +- **Não** saltar a validação MEMORY.md no final da sessão + +## Relacionamentos Direccionais + +### Depende De +- [[../../Hub/06-Operacoes]] - Hub operacional central com procedimentos +- [[../../Hub/04-Stack]] - Decisões técnicas e stack Descomplicar + +### Suporta +- [[../../Hub/05-Projectos/Modelo-Organizacao-Proc-Dev/ESTRUTURA.md]] - Modelo de projectos + +### Documenta +- [[../../Hub/06-Operacoes/Procedimentos/]] - Procedimentos operacionais + +### Implementação +- [[.]] - Código-fonte e implementação do projecto +### Relacionado Com +- [[../../Hub/04-Stack]] - Stack técnico partilhado + +### Procedimento +- [[../../Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-Desk-Subtarefas-Dependencias.md]] - Modelo de subtarefas + +### Herança +- [[../../Hub/05-Projectos/Modelo-Organizacao-Proc-Dev/ESTRUTURA.md]] - Estrutura canónica + +## Histórico de Intervenções + +| Data | Agente | Acção | +|---|---|---| +| 2026-05-13 | Gemini CLI | Criação da estrutura base de governance | +| 2026-05-13 | Izito (Hermes) | Correção estrutural, criação CARL, script de validação | \ No newline at end of file diff --git a/CICLO-VIDA-PROJECTO.md b/CICLO-VIDA-PROJECTO.md new file mode 100644 index 0000000..636cd1a --- /dev/null +++ b/CICLO-VIDA-PROJECTO.md @@ -0,0 +1,148 @@ +--- +layer: wiki +type: Document +title: "Ciclo de Vida de Projecto — Sequência Obrigatória" +description: >- + Sequência canónica de todas as fases de um projecto Descomplicar — da ideia + ao deploy. Obrigatória para todos os projectos, com ou sem código. +tags: [projecto, ciclo-vida, sequencia, obrigatorio, spec, brainstorming, deploy] +timestamp: 2026-06-29T23:00:00+01:00 +status: active +--- + +# Ciclo de Vida de Projecto — Sequência Obrigatória + +> **Regra de ouro:** Nunca saltar fases. Cada fase produz um artefacto concreto. +> Sem artefacto → fase não concluída → não avançar. + +--- + +## A Sequência + +``` +1. IDEIA + ↓ +2. BRIEFING + ↓ +3. PESQUISA ← obrigatória (Web + NLM + Mem0 + Wiki) + ↓ +4. BRAINSTORMING + ↓ +5. SPEC (aprovada por Emanuel) + ↓ +6. PLAN (validado antes de tocar em código) + ↓ +7. REPO GIT (se projecto com código) + ↓ +8. IMPLEMENTAÇÃO + ↓ +9. CI/CD (se aplicável — paralelo ao deploy) + ↓ +10. DEPLOY +``` + +--- + +## Detalhe por Fase + +### 1. Ideia +- Capturar em `00-Inbox/` do Hub ou comentário Desk +- **Artefacto:** nota de ideia (1 parágrafo mínimo) + +### 2. Briefing +- Definir: contexto, problema, objectivo, stakeholders, restrições +- Registar no Desk CRM como tarefa ou ticket +- **Artefacto:** `docs/SPECS/BRIEF.md` ou comentário Desk + +### **3. Pesquisa — OBRIGATÓRIA** ⚠️ +Antes de qualquer decisão de arquitectura ou implementação: + +| Fonte | O que pesquisar | +|-------|----------------| +| **Web** | Estado da arte, soluções existentes, benchmarks | +| **NotebookLM** | Notebooks temáticos relevantes | +| **Mem0** | `search_memories("contexto do projecto")` — o que já sabemos | +| **Wiki IJFW** | Conhecimento curado existente | +| **Hub** | PROCs, QRs, decisões anteriores relacionadas | + +> **Regra:** Se a pesquisa revelar que a solução já existe → usar o que existe, não reinventar. +- **Artefacto:** notas de pesquisa em `docs/` ou resumo no BRIEF + +### 4. Brainstorming +- Explorar abordagens alternativas +- Avaliar trade-offs com evidência da pesquisa +- Envolver Mem0 para contexto de decisões passadas +- **Artefacto:** `docs/PLANS/BRAINSTORM.md` com opções e decisão + +### 5. SPEC +- Especificação completa: arquitectura, componentes, interfaces, critérios de aceitação +- **Aprovação explícita por Emanuel antes de avançar** +- **Artefacto:** `docs/SPECS/SPEC.md` com status `approved` + +### 6. Plan +- Plano de implementação detalhado: fases, tarefas, dependências, estimativas +- Validação humana antes de tocar em código +- Registar tarefas no Desk CRM +- **Artefacto:** `docs/PLANS/PLAN.md` + tarefas Desk + +### 7. Repo Git +- Criar repositório em `git.descomplicar.pt` (Gitea) +- Seguir PROC INF-EZP-001 para deploy no EasyPanel +- Configurar `.desk-project` na raiz +- **Artefacto:** repo criado, README.md inicial, estrutura XDP-PRJ-001 + +### 8. Implementação +- Seguir o PLAN por fases +- Registar progresso em `MEMORY.md` por sessão +- Cada decisão arquitectural → comentário Desk +- **Artefacto:** código funcional + testes + +### 9. CI/CD *(se aplicável)* +- Configurar via Gitea Actions → EasyPanel webhook +- Ver `PROC-Gitea-Runners-CICD.md` +- **Artefacto:** pipeline funcional com deploy automático + +### 10. Deploy +- Seguir PROC INF-EZP-001 (EasyPanel) ou PROC adequado +- Validar com E2E após deploy +- Actualizar `STATUS.md` → estado `deployed` +- **Artefacto:** serviço em produção + STATUS.md actualizado + +--- + +## Artefactos por Fase (resumo) + +| Fase | Artefacto obrigatório | +|------|----------------------| +| Ideia | Nota capturada | +| Briefing | BRIEF.md ou comentário Desk | +| **Pesquisa** | **Notas de pesquisa (Web + NLM + Mem0 + Wiki)** | +| Brainstorming | BRAINSTORM.md com decisão | +| SPEC | SPEC.md aprovada | +| Plan | PLAN.md + tarefas Desk | +| Repo Git | Repositório Gitea + estrutura | +| Implementação | Código + testes + MEMORY.md | +| CI/CD | Pipeline funcional | +| Deploy | Serviço em produção + STATUS.md | + +--- + +## Anti-Padrões (proibido) + +- ❌ Começar a implementar sem SPEC aprovada +- ❌ Saltar a pesquisa — "já sei o que fazer" +- ❌ Deploy sem testes passados +- ❌ Criar repositório antes do PLAN estar validado +- ❌ Reinventar o que já existe (Mem0 evita isto) + +--- + +## Referências + +- `PROC-Estrutura-Pasta-Projecto.md` (XDP-PRJ-001) — ficheiros obrigatórios por pasta +- `06-Operacoes/Procedimentos/D7-Tecnologia/Infraestrutura/PROC-EasyPanel-Deployment.md` — deploy +- `06-Operacoes/Procedimentos/D7-Tecnologia/Infraestrutura/PROC-Gitea-Runners-CICD.md` — CI/CD + +--- + +*Criado: 29-06-2026 | Descomplicar® | Sequência obrigatória para todos os projectos* diff --git a/ESTRUTURA.md b/ESTRUTURA.md new file mode 100644 index 0000000..4d3e010 --- /dev/null +++ b/ESTRUTURA.md @@ -0,0 +1,89 @@ +--- +layer: wiki +type: Document +tags: [projecto, modelo, organizacao, estrutura] +title: Estrutura +description: >- + Este documento define a estrutura de pastas e ficheiros obrigatória para todos os projectos do ecossistema Descomplicar®… +timestamp: 2026-05-13T11:27:31.572569+00:00 +--- +# ESTRUTURA.md — Standard de Hierarquia de Projectos + +## Introdução +Este documento define a estrutura de pastas e ficheiros obrigatória para todos os projectos do ecossistema Descomplicar®. A consistência da estrutura permite que agentes de IA e programadores transitem entre projectos com atrito zero. + +## Hierarquia Base (Root) + +```text +/ (root) +├── docs/ # Documentação específica do projecto +│ ├── PLANS/ # Planos de acção e roadmaps específicos +│ └── SPECS/ # Especificações técnicas e requisitos do projecto +├── scripts/ # Scripts de automação local (opcional) +├── tests/ # Testes globais ou de integração +├── index.md # Navegação OKF — links only, minúsculas (Obsidian + Wayland) +├── AGENTS.md # Contexto para agentes IA — 5W2H + relacionamentos (Wayland, Hermes, Claude, OpenCode) +├── CLAUDE.md # Instruções específicas para Claude Code +├── GEMINI.md # Instruções específicas para Gemini CLI +├── STATUS.md # Estado actual — PDCA (Plan/Do/Check/Act) +├── CHANGELOG.md # Histórico de versões e decisões +├── MEMORY.md # Factos duráveis, decisões, workarounds (append-only) +├── README.md # Visão geral humana — o que é, porquê existe +├── desk.project # Ligação ao Desk CRM (JSON) +└── ... # Ficheiros de código (src, backend, frontend, etc.) +``` + +**Nota:** PROCs e RUNBOOKs NÃO residem aqui. Consultar `06-Operacoes/Procedimentos/` e `06-Operacoes/Runbooks/` no Hub — são a fonte de verdade centralizada. + +## Definição de Directórios e Ficheiros Críticos + +### 1. `/docs` +Documentação que vive e morre com o projecto. +- **PLANS/**: Documentos que descrevem "o que vamos fazer" neste projecto (ex: `PLANS/PLAN-MIGRACAO-DB.md`). +- **SPECS/**: Definições técnicas, diagramas de arquitectura e contratos de API específicos. + +### 2. Documentação Centralizada (Externo ao Projecto) +Os procedimentos operacionais e manuais de manutenção não residem na pasta do projecto para evitar duplicação e garantir que todos seguem a versão mais recente (Single Source of Truth). + +- **PROCs** no Hub em `06-Operacoes/Procedimentos/` +- **Runbooks** no Hub em `06-Operacoes/Runbooks/` +- **Quick References** no Hub em `06-Operacoes/Documentacao/Quick-Reference/` + +**Nunca** criar pastas `docs/PROC` ou `docs/RUNBOOK` num projecto. A referência correcta é sempre o Hub. + +--- + +### 3. Ficheiros de Governance de IA (`AGENTS.md`, `GEMINI.md`, `CLAUDE.md`) +Servem para alinhar o comportamento dos agentes neste repositório. Devem conter regras de estilo, convenções de código e restrições de segurança específicas do projecto. Pelo menos `AGENTS.md` é obrigatório. + +### 4. `MEMORY.md` +**Obrigatório.** Deve ser actualizado no final de cada sessão. +- Formato: Secções por data (ordem cronológica inversa). +- Conteúdo: O que foi feito, problemas encontrados e o que ficou pendente. + +### 4. `desk.project` +Ficheiro JSON que mapeia o repositório local à tarefa ou projecto correspondente no Desk CRM. + +## Regras de Nomenclatura +- Pastas: `UPPERCASE` para categorias de documentação (`PLANS`, `SPECS`), `lowercase` para código. +- Ficheiros: `kebab-case.md` (letras minúsculas e hífens). +- Excepções: Ficheiros de sistema como `README.md`, `CHANGELOG.md` ou ficheiros de governance em `UPPERCASE`. + +## Validação de Estrutura +Um projecto é considerado "em conformidade" se contiver, no mínimo: +1. `docs/` com as pastas `PLANS/` e `SPECS/` (mesmo que vazias). +2. `AGENTS.md` com directrizes específicas do projecto. +3. `MEMORY.md` com registo de sessões. +4. `desk.project` com task_id válido no Desk CRM. + +> **Validação automática:** Executar `scripts/validate-structure.sh` na raiz do projecto para verificar conformidade. + +--- + +## Convenção para Pastas Hub (Sistemas e Aplicações) + +Para pastas de documentação no Hub (`04-Stack/02.04-Sistemas/`, `04-Stack/02.05-Aplicações/`, etc.) aplica-se uma convenção própria: + +→ Ver **`06-Operacoes/Procedimentos/Cross-Departamental/PROC-Estrutura-Pasta-Projecto.md`** (XDP-PRJ-001) + +**Diferença principal:** pastas Hub não têm `docs/`, `scripts/` nem `tests/` — são documentação pura. O `AGENTS.md` contém o 5W2H do sistema e os relacionamentos com o ecossistema. diff --git a/GOVERNANCA.md b/GOVERNANCA.md new file mode 100644 index 0000000..a88fa46 --- /dev/null +++ b/GOVERNANCA.md @@ -0,0 +1,42 @@ +--- +layer: wiki +type: Document +tags: [projecto, modelo, organizacao, governanca] +title: Governanca +description: >- + Este documento estabelece as regras de ouro para o desenvolvimento de software na Descomplicar®. A conformidade com esta… +timestamp: 2026-05-13T10:46:34.903096+00:00 +--- +# GOVERNANCA.md — Manifesto de Qualidade e Conduta DEV + +## Introdução +Este documento estabelece as regras de ouro para o desenvolvimento de software na Descomplicar®. A conformidade com estas regras é obrigatória para todos os contribuidores (humanos e agentes). + +## 1. Regras de Ouro (Core Rules) +1. **PT-PT Strictly**: Código (comentários), documentação e mensagens de commit devem ser em Português Europeu. +2. **Zero Breaking Deploys**: Nenhum deploy pode ser efectuado com testes falhados ou vulnerabilidades críticas. +3. **Single Source of Truth**: Procedimentos (`PROC`) e `RUNBOOKS` são consultados centralmente no Hub. Não se criam cópias locais. +4. **Audit-First**: Todo o projecto deve ser auditado mensalmente seguindo o `DEV-AUDIT-001`. + +O desenvolvimento segue a sequência obrigatória de 10 fases: + +**Ideia → Briefing → Pesquisa (Web + NLM + Mem0 + Wiki) → Brainstorming → SPEC → Plan → Repo Git → Implementação → CI/CD → Deploy** + +> ⚠️ **A Pesquisa é obrigatória antes de qualquer decisão.** Consultar sempre Mem0 (`search_memories`), NotebookLM, Wiki IJFW e Hub antes de arquitectar. + +Ver detalhe completo em **`CICLO-VIDA-PROJECTO.md`** — artefactos, anti-padrões e referências por fase. + +## 3. Gestão de Dependências e Upgrades +- Upgrades de frameworks seguem obrigatoriamente o `DEV-UPGRADE-001`. +- Proibida a utilização de dependências "stale" ou sem licença activa em projectos de produção. + +## 4. Interacção com o ecossistema (CRM & Git) +- Toda a alteração técnica deve ter um rastro no Desk CRM (Comentário na tarefa correspondente). +- Commits devem ser atómicos e descritivos. +- Uso obrigatório de ficheiros `desk.project` para ancorar o contexto. + +## 5. Compliance de Agentes IA +Agentes devem reportar o seu estado e decisões em `MEMORY.md` e respeitar as directrizes em `AGENTS.md`. Em caso de falha repetida (3x), o agente deve parar e solicitar intervenção humana. + +## 6. Penalizações e Bloqueios +O incumprimento da governação (especialmente deploys sem auditoria) resulta no bloqueio imediato do pipeline de produção até à resolução da causa raiz. diff --git a/INSTRUCOES.md b/INSTRUCOES.md new file mode 100644 index 0000000..3c6fa65 --- /dev/null +++ b/INSTRUCOES.md @@ -0,0 +1,20 @@ +--- +layer: wiki +type: Document +tags: [projecto, modelo, organizacao, instrucoes] +title: Instrucoes +description: >- + Este diretório é a fonte de verdade para o modelo de organização de projetos. A partir de agora, todas as definições est… +timestamp: 2026-05-13T10:34:35.758090+00:00 +--- +# Instruções para o Modelo de Organização (HUB) + +Este diretório é a fonte de verdade para o modelo de organização de projetos. A partir de agora, todas as definições estruturais e procedimentos padrão do ecossistema Descomplicar® devem ser mantidos e versionados aqui. + +## Próximos Passos +1. **Documentação Master:** Criar os ficheiros ESTRUTURA.md, GOVERNANCA.md e PROTOCOLO-CRM.md baseados no modelo aprovado. +2. **Templates:** Criar templates de documentos em docs/SPECS e docs/PLANS. +3. **Sincronização:** Manter a paridade entre este diretório e os repositórios individuais dos projetos (via git submodules ou simples cópia/script de deploy). + +## Como editar +Pode editar este repositório diretamente com o agente de IA, desde que a sessão esteja configurada com o root correto no Hub. \ No newline at end of file diff --git a/MEMORY.md b/MEMORY.md new file mode 100644 index 0000000..3c07ad9 --- /dev/null +++ b/MEMORY.md @@ -0,0 +1,69 @@ +--- +type: Document +title: Memory +description: 'AUDIT-ECO #001 executada: 4 agentes validados. 2 findings abertos' +timestamp: 2026-05-16 19:22:27.808202+00:00 +tags: +- dev +- codigo +- historico +- sessoes +- proximos-passos +- '2026-06-30' +- reorganizacao +layer: wiki +--- +# MEMORY.md + +## 2026-05-16 (sessão Claude — auditoria pós-OpenCode) +- **AUDIT-ECO #001 executada:** 4 agentes validados. 2 findings abertos. + - F-001 (High): Hermes sem `desk-crm-v3`, `mcp-time`, `memory-supabase`, `ssh-unified`, `notebooklm` — só tem `mcp-gitea` local + - F-002 (Medium): Gemini sem `desk-crm-v3` (usa `desk-project-minimal`) e sem `mcp-time` +- **CARL recall expandido:** 7 → 27 keywords no domínio MODELO-ORGANIZACAO (backup `.carl/carl.json.bak-2026-05-16`) +- **Script criado:** `scripts/propagate-structure.sh` — aplica estrutura standard a outro projecto, idempotente, com dry-run. Testado: CONFORME +- **Estrutura audit/:** `docs/audit/audit.md` + `docs/audit/findings/F-001.md` + `F-002.md` +- **Worklog HTML:** zero ocorrências em todos os 4 agentes — confirmado migrado para markdown +- **Permissões 600:** confirmadas em opencode-secrets, claude.json, claude/settings.json, opencode.json, hermes/config.yaml + +## 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/` +- **PROC-AUDIT-STANDARD criado:** D7-SIS-007 em `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/` +- **PROC-DEV-STANDARD-ref criado:** em `docs/SPECS/PROC-DEV-STANDARD-ref.md` +- **Configs actualizadas:** GEMINI.md, Hermes/AGENTS.md, OpenCode/AGENTS.md + desk-crm-v3 activado, CLAUDE.md +- **Task Desk #2134:** Em Curso + +## 2026-05-13 +- **Formalização de Estrutura**: Criado `ESTRUTURA.md` definindo a hierarquia padrão. +- **Centralização de Documentação**: + - Movidos procedimentos locais (`DEV-AUDIT`, `DEV-UPGRADE`, `PROC-DEPLOY`) para `06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/`. + - Criada estrutura central de `Runbooks` no Hub com guia de utilização. + - Removidas pastas locais `docs/PROC` e `docs/RUNBOOK`. +- **Governação**: Criado `GOVERNANCA.md` como manifesto de qualidade. +- **Protocolo de Gestão**: Criado `PROTOCOLO-CRM.md` definindo a integração Lean entre Gitea (execução) e Desk CRM (visibilidade). +- **Identidade**: Criado `AGENTS.md` e `desk.project` (Tarefa #2134). + +## 2026-05-13 (Sessão 2 — Correções Izito) +- **Análise Crítica:** Identificados 8 problemas estruturais no modelo, incluindo falta de dogfooding, contradição interna no ESTRUTURA.md, CRM desactualizado, e ausência de integração CARL. +- **Correções Aplicadas:** + - `ESTRUTURA.md` — removida contradição docs/PROC e docs/RUNBOOK vs Hub centralizado, corrigida numeração de secções, actualizada validação para 2 subpastas (PLANS + SPECS). + - `AGENTS.md` — reescrito com directrizes específicas, referência ao CARL, tabela de projectos, e histórico de intervenções. + - `scripts/validate-structure.sh` — criado script de validação automática (exit code 0 = conforme). + - `docs/PLANS/` e `docs/SPECS/` — criadas pastas em falta. +- **CARL:** Criado domínio `MODELO-ORGANIZACAO` com 6 regras e 9 recall keywords para descoberta por agentes. +- **CRM:** Task #2134 actualizada de "Não iniciado" para "Em Curso". Comentário de registo adicionado. +- **Validação:** Script corre contra o próprio projecto — **CONFORME** (0 falhas, 0 avisos). +- **Pendente:** Templates em docs/PLANS e docs/SPECS, sincronização com outros projectos via script/hook. +- **PROC-DEPLOY-STANDARD:** Criado standard genérico de deploy (PROC-DEPLOY-STANDARD.md) extraído do PROC-DEPLOY-PROD (WhatSMS v2). O WhatSMS-specific foi simplificado e passou a referenciar o standard como base. +- **Diagrama:** Adicionado F5 (Deploy) ao workflow.drawio — fluxo branch → CI → PR → merge → auto-deploy → validação + rollback. + +## 2026-05-13 (Sessão 3 — Fecho) +- **MCP EasyPanel:** Instalado no Hermes (`~/.hermes/config.yaml`). Endpoint: `gateway.descomplicar.pt/v1/easypanel/mcp` (type: http). Disponível após restart de sessão. +- **Diagrama:** Fontes uniformizadas para sans-serif (Helvetica) em todo o Workflow-Fluxo.drawio. Adicionado F5 (Deploy) com Deploy Guard + Rollback Plan. +- **PROC-DEPLOY-STANDARD:** Criado `PROC-DEPLOY-STANDARD.md` como standard genérico de deploy. `PROC-DEPLOY-PROD.md` simplificado com referência ao standard e apenas detalhes WhatSMS. +- **CARL:** Adicionada regra #7 ao domínio MODELO-ORGANIZACAO — deploy segue PROC-DEPLOY-STANDARD. +- **Pendente:** Templates docs/PLANS e docs/SPECS. Sincronização com outros projectos. + +--- \ No newline at end of file diff --git a/PROTOCOLO-CRM.md b/PROTOCOLO-CRM.md new file mode 100644 index 0000000..262b080 --- /dev/null +++ b/PROTOCOLO-CRM.md @@ -0,0 +1,48 @@ +--- +layer: wiki +type: Document +tags: [projecto, modelo, organizacao, protocolo] +title: Protocolo Crm +description: >- + No ecossistema Descomplicar®, a gestão de projectos segue uma hierarquia de granularidade distinta: +timestamp: 2026-05-13T11:01:24.047410+00:00 +--- +# PROTOCOLO-CRM.md — Integração Lean Gitea & Desk CRM + +## Princípio Fundamental: O Contentor de Tempo +No ecossistema Descomplicar®, a gestão de projectos segue uma hierarquia de granularidade distinta: +- **Desk CRM**: É o **Contentor de Tempo e Custos**. Utiliza-se apenas uma (ou poucas) "Tarefa Master" para registar horas e dar visibilidade financeira. +- **Gitea**: É a **Oficina Técnica**. É aqui que reside a complexidade granular (Issues, Milestones, Projects). + +## 1. Mapeamento de Entidades + +| Entidade Desk CRM | Entidade Gitea | Finalidade | +| :--- | :--- | :--- | +| **Tarefa Master** | Repositório / Milestones | Registo de horas (Timer) e Faturação. | +| **Comentário de Task** | Resumo de Sessão | Visibilidade para o Cliente/Gestor. | +| **(Inexistente)** | **Issues / Pull Requests** | Detalhe técnico, bugs e histórico de código. | + +## 2. Fluxo Operacional Simplificado + +### A. Início da Sessão +1. O Agente/Developer identifica a **Tarefa Master** no CRM via `desk.project`. +2. Inicia o timer: `mcp__desk-project-minimal__start_task_timer(task_id=XXXX)`. +3. Toda a exploração de tarefas granulares é feita no Gitea. + +### B. Durante a Execução +- As discussões técnicas, especificações de bugs e estados de desenvolvimento (To Do/Done) ocorrem exclusivamente nas **Issues** e **Projects** do Gitea. + +### C. Final da Sessão (Obrigatório) +1. Parar o timer no CRM. +2. Adicionar um comentário de fecho no CRM que faça a ponte entre os mundos: + *"Concluída sessão de desenvolvimento. No Gitea, foram fechadas as Issues #10 e #11 relativas à Milestone [Nome]."* +3. Actualizar o `MEMORY.md` local. + +## 3. Onde Documentar o Quê? + +- **Hub (`06-Operacoes/`)**: Padrões que se aplicam a TODOS os projectos (ex: "Como configurar um servidor"). +- **Gitea Wiki**: Documentação específica deste código (ex: "Esquema da API deste projecto"). +- **`MEMORY.md`**: Registo cronológico da vida do repositório. + +## 4. Conclusão +Este protocolo elimina a necessidade de duplicar o quadro de tarefas do Gitea no Desk CRM. O CRM mantém-se limpo, focado em resultados e tempo, enquanto o Gitea retém toda a riqueza técnica. diff --git a/STATUS.md b/STATUS.md new file mode 100644 index 0000000..ab5e48e --- /dev/null +++ b/STATUS.md @@ -0,0 +1,25 @@ +--- +layer: wiki +type: Status +tags: +- dev +- codigo +- estado +- versao +- conformidade +- '2026-06-30' +- reorganizacao +title: Status +description: 'Versão: 1.1 | Data: 2026-05-16 | Agente: Claude Code' +timestamp: 2026-05-16 19:22:18.276118+00:00 +--- +# STATUS.md — bi-descomplicar + +**Versão:** 1.0 | **Data:** 2026-06-30 | **Agente:** DevStructure-WorkerC + +- **Em curso:** Estruturação inicial — cópia de modelo Descomplicar +- **Bloqueios:** Nenhum +- **Próximos passos:** + - Validar estrutura conforme ESTRUTURA.md + - Revisar frontmatter em AGENTS.md + - Próxima revisão: TBD diff --git a/desk.project b/desk.project new file mode 100644 index 0000000..43c4d12 --- /dev/null +++ b/desk.project @@ -0,0 +1,6 @@ +{ + "task_id": 2134, + "project_name": "Modelo-Organizacao-Proc-Dev", + "rel_type": "project_documentation", + "updated_at": "2026-05-13" +} \ No newline at end of file diff --git a/docs/PLANS/2026-05-16-ecosystem-alignment.md b/docs/PLANS/2026-05-16-ecosystem-alignment.md new file mode 100644 index 0000000..fecab29 --- /dev/null +++ b/docs/PLANS/2026-05-16-ecosystem-alignment.md @@ -0,0 +1,1147 @@ +--- +layer: wiki +type: Document +tags: [projecto, modelo, organizacao, ecosystem] +title: 2026 05 16 Ecosystem Alignment +description: >- + > For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:exec… +timestamp: 2026-05-16T18:38:11.957939+00:00 +--- +# 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` + +- [x] **Step 1: Criar o ficheiro ECOSYSTEM.md** + +```bash +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] + ``` +4. Ler `STATUS.md` se existir — se **não existir**, **criar** com cabeçalho: + ```markdown + # 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 +1. Actualizar `MEMORY.md` (topo, ordem cronológica inversa) com: + - Decisões tomadas + - Paths/IDs relevantes descobertos + - Workarounds aplicados +2. Actualizar `STATUS.md` com estado actual, bloqueios e próximos passos +3. 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) + +```markdown +## [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. + +- [x] **Step 1: Fazer backup** + +```bash +cp ~/.gemini/GEMINI.md ~/.gemini/GEMINI.md.bak-2026-05-16 +``` + +- [x] **Step 2: Ler o ficheiro actual** + +```bash +cat ~/.gemini/GEMINI.md +``` + +- [x] **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 +``` + +- [x] **Step 4: Substituir formato de worklog (HTML → markdown)** + +Localizar: +``` +`

[Projecto] - Descrição

Ficheiros: path

Data: YYYY-MM-DD

` +``` + +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. +``` + +- [x] **Step 6: Adicionar Regra 48** + +Na secção de regras core, adicionar: + +```markdown +- **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")`. +``` + +- [x] **Step 7: Verificar resultado** + +```bash +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. + +- [x] **Step 1: Fazer backup** + +```bash +cp ~/.hermes/AGENTS.md ~/.hermes/AGENTS.md.bak-2026-05-16 +``` + +- [x] **Step 2: Actualizar secção MEMORY.md** + +Localizar: +```markdown +## 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: +```markdown +## 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 +``` + +- [x] **Step 3: Adicionar Gitea vs Desk CRM** + +Após a secção `## Sistema Triangular`, adicionar: + +```markdown +## 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. +``` + +- [x] **Step 4: Adicionar worklog standard** + +Adicionar secção: + +```markdown +## 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. +``` + +- [x] **Step 6: Adicionar Regra 48** + +Adicionar à secção de Convenções ou Regras: + +```markdown +## 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. +``` + +- [x] **Step 7: Verificar resultado** + +```bash +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. + +- [x] **Step 1: Fazer backup** + +```bash +cp ~/.config/opencode/AGENTS.md ~/.config/opencode/AGENTS.md.bak-2026-05-16 +``` + +- [x] **Step 2: Ler o ficheiro actual** + +```bash +cat ~/.config/opencode/AGENTS.md +``` + +- [x] **Step 3: Adicionar protocolo de sessão completo** + +Adicionar após o cabeçalho existente (PT-PT + Wiki): + +```markdown +## 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') +" +``` + +- [x] **Step 5: Verificar resultado** + +```bash +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` + +- [x] **Step 1: Localizar a Regra 19 (Data Sessão) no CLAUDE.md** + +```bash +grep -n "STATUS\|Data Sessão\|MEMORY\|sessão" ~/.claude/CLAUDE.md | head -20 +``` + +- [x] **Step 2: Adicionar STATUS.md à tabela de regras** + +Na tabela de REGRAS CORE, após a linha da Regra 19, adicionar: + +```markdown +| 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 | +``` + +- [x] **Step 3: Verificar** + +```bash +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` + +- [x] **Step 1: Criar o PROC completo** + +```bash +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] +``` + +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 +``` + +- [x] **Step 2: Verificar criação** + +```bash +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` + +- [x] **Step 1: Criar ficheiro de referência** + +```bash +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 +``` + +- [x] **Step 2: Verificar** + +```bash +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` + +- [x] **Step 1: Actualizar MEMORY.md do projecto** + +Adicionar ao topo do `MEMORY.md`: + +```markdown +## 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 +``` + +- [x] **Step 2: Verificar domínio CARL** + +```bash +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` + +- [x] **Step 1: Criar o PROC de auditoria** + +```bash +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:** +- [x] Lint sem erros (`npm run lint` / equivalente stack) +- [x] Build sem erros (`npm run build` / equivalente) +- [x] Testes passam (`npm test` / equivalente) +- [x] Cobertura acima do threshold do projecto +- [x] Sem `TODO` / `FIXME` não rastreados em issues Gitea +- [x] `CHANGELOG.md` actualizado +- [x] 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:** +- [x] Auditoria de dependências (`npm audit --audit-level=high` / equivalente) +- [x] Scan de credenciais: nenhum secret em código ou configs com permissões >600 +- [x] Verificar ficheiros de config de agentes: permissões 600 +- [x] OWASP Top 10 — verificar inputs validados, sem SQL injection, sem XSS +- [x] Tokens/API keys — rotação se >90 dias sem rotação +- [x] 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:** +- [x] Todos os agentes conhecem STATUS.md e MEMORY.md +- [x] Todos os agentes têm Regra 48 (dev local, sem CT 102) +- [x] Todos os agentes têm regras Gitea vs Desk CRM +- [x] Worklog em formato markdown PT-PT em todos +- [x] MCPs essenciais activos: desk-crm-v3, gitea, memory-supabase, mcp-time +- [x] Credenciais em plaintext — nenhuma em ficheiros com permissões >600 +- [x] Referências extintas removidas (servidores, paths, IDs obsoletos) +- [x] 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:** +- [x] `MEMORY.md` actualizado (última entrada ≤7 dias) +- [x] `STATUS.md` actualizado (última entrada ≤7 dias) +- [x] Issues Gitea abertas sem PR associado há >14 dias → rever prioridade +- [x] Tasks Desk CRM em "Em Curso" há >14 dias sem actividade → rever ou fechar +- [x] Timesheets registados para todo o trabalho da semana +- [x] `CHANGELOG.md` reflecte o que foi deployado +- [x] 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` + +- [x] **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/ +``` + +- [x] **Step 2: Adicionar referência à secção de Referências** + +Na secção `## Referências`, adicionar: + +```markdown +- `PROC-AUDIT-STANDARD.md` — D7-SIS-007 (auditoria: código, segurança, ecossistema, projecto) +``` + +- [x] **Step 3: Verificar** + +```bash +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 + +- [x] **Verificar todos os ficheiros criados** + +```bash +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 +``` + +- [x] **Verificar configs actualizadas** + +```bash +grep -l "STATUS.md" ~/.gemini/GEMINI.md ~/.hermes/AGENTS.md ~/.config/opencode/AGENTS.md ~/.claude/CLAUDE.md +``` +Esperado: 4 ficheiros listados. + +- [x] **Executar validate-structure.sh** + +```bash +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 diff --git a/docs/PLANS/BRAINSTORM.md b/docs/PLANS/BRAINSTORM.md new file mode 100644 index 0000000..d0554a0 --- /dev/null +++ b/docs/PLANS/BRAINSTORM.md @@ -0,0 +1,10 @@ +--- +type: Brainstorm +title: 'Brainstorm — bi-descomplicar' +timestamp: 2026-06-30 +layer: wiki +--- + +# BRAINSTORM — bi-descomplicar + +Estrutura padrão aplicada. diff --git a/docs/PLANS/PLAN.md b/docs/PLANS/PLAN.md new file mode 100644 index 0000000..88c4fbf --- /dev/null +++ b/docs/PLANS/PLAN.md @@ -0,0 +1,10 @@ +--- +type: Plan +title: 'PLAN — bi-descomplicar' +timestamp: 2026-06-30 +layer: wiki +--- + +# PLAN — bi-descomplicar + +1. Estruturação\n2. Validação\n3. Manutenção diff --git a/docs/SPECS/2026-05-16-ecosystem-audit.md b/docs/SPECS/2026-05-16-ecosystem-audit.md new file mode 100644 index 0000000..cee7b64 --- /dev/null +++ b/docs/SPECS/2026-05-16-ecosystem-audit.md @@ -0,0 +1,106 @@ +--- +layer: wiki +type: Document +tags: [projecto, modelo, organizacao, ecosystem] +title: 2026 05 16 Ecosystem Audit +description: >- + Auditoria de ecossistema multi-agente — questionário directo a cada agente, alinhamento de MCPs e skills. +timestamp: 2026-05-16T17:54:53.917476+00:00 +--- +# Auditoria de Ecossistema — Alinhamento Multi-Agente + +**Data:** 2026-05-16 +**Método:** Questionário directo a cada agente (dados reais, sem interpretação) +**Agentes auditados:** Gemini CLI, Hermes/Izito, OpenCode + +--- + +## Quadro Consolidado + +| | Gemini | Hermes | OpenCode | +|--|--------|--------|----------| +| MEMORY.md lê/escreve | ✅ | ✅ (se existir) | ❌ | +| Cria MEMORY.md se não existe | ❌ | ❌ | ❌ | +| STATUS.md | ❌ | ❌ | ❌ | +| Gitea vs Desk (regras explícitas) | ❌ | ❌ | ❌ | +| Worklog format | ⚠️ HTML | ❌ ausente | ❌ ausente | +| CARL (carl.json) | ✅ path correcto | ⚠️ só MCP | ❌ | +| Regra 48 (dev local) | ❌ | ❌ | ❌ | +| Refs extintas | ✅ limpo | ✅ limpo | ⚠️ dify-kb | +| Credenciais plaintext | — | — | 🔴 resolvido | + +--- + +## Achados por Prioridade + +### P1 — Crítico + +**1. STATUS.md — ausente em todos os agentes** +Nenhum agente conhece ou tem protocolo para o ficheiro de estado vivo do projecto. +Impacto: cada agente começa sessão sem saber o que o anterior fez. + +**2. MEMORY.md — nenhum cria se não existir** +Gemini e Hermes lêem/escrevem se existir. OpenCode não menciona de todo. +Impacto: projectos novos ficam sem memória até alguém criar manualmente. + +**3. Gitea vs Desk CRM — sem regras de routing** +Todos os agentes sabem que os sistemas existem mas nenhum tem regras explícitas +sobre o que vai para cada um. +Impacto: duplicação de registos, informação dispersa, dessincronia. + +**4. OpenCode sem contexto de ecossistema** +Zero referências a MEMORY.md, CARL, Regra 48, Desk CRM activo. +Impacto: o OpenCode opera isolado do ecossistema. + +### P2 — Médio + +**5. Worklog divergente** +- Gemini: HTML (`

`, `
    `, `
    `) — o único com formato diferente +- Hermes: sem template definido +- OpenCode: sem template definido +- Claude: markdown com /worklog — standard do ecossistema + +**6. CARL incompleto** +- Gemini: conhece o caminho `/media/ealmeida/Dados/.carl/carl.json` ✅ +- Hermes: apenas como nome de MCP, não conhece os domínios +- OpenCode: ausente + +**7. Regra 48 ausente em todos** +Nenhum agente sabe que o CT 102 foi extinto em 20-04-2026 e que o +desenvolvimento é local em `/media/ealmeida/Dados/Dev/`. + +### P3 — Melhoria + +**8. Boas práticas únicas a standardizar** +- Tabela de delegação multi-agente (Hermes SOUL.md) → todos deviam conhecer +- LLM Wiki protocolo 3 passos (Gemini) → standardizar +- Perfil do utilizador PHDA+INFJ (Hermes) → adicionar ao Gemini e OpenCode +- Redução activa de opções (Hermes) → comportamento a standardizar + +--- + +## Segurança — Resolvido em Sessão + +| Acção | Estado | +|-------|--------| +| `opencode.json` → 600 | ✅ | +| `~/.claude/settings.json` → 600 | ✅ | +| Credenciais NotebookLM → `~/.opencode-secrets` (600) | ✅ | +| Wrapper `notebooklm-mcp-wrapper.sh` | ✅ | +| `dify-kb` removido do opencode.json | ✅ | + +--- + +## Ficheiros a Criar/Actualizar + +| Ficheiro | Acção | Prioridade | +|----------|-------|------------| +| `ECOSYSTEM.md` (Hub) | Criar — fonte de verdade comum | P1 | +| `~/.gemini/GEMINI.md` | Actualizar — STATUS.md, MEMORY.md criar, Gitea/Desk, worklog, Regra 48 | P1 | +| `~/.hermes/AGENTS.md` | Actualizar — STATUS.md, MEMORY.md criar, Gitea/Desk, worklog, CARL domínios, Regra 48 | P1 | +| `~/.config/opencode/AGENTS.md` | Actualizar — tudo: MEMORY.md, STATUS.md, Gitea/Desk, CARL, Regra 48, sistema triangular | P1 | +| `~/.claude/CLAUDE.md` | Actualizar — adicionar STATUS.md ao protocolo de sessão | P2 | + +--- + +**Próximo passo:** implementar alinhamento — writing-plans diff --git a/docs/SPECS/2026-05-16-proc-dev-standard-design.md b/docs/SPECS/2026-05-16-proc-dev-standard-design.md new file mode 100644 index 0000000..1f1df9c --- /dev/null +++ b/docs/SPECS/2026-05-16-proc-dev-standard-design.md @@ -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] +``` + +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 diff --git a/docs/SPECS/BRIEF.md b/docs/SPECS/BRIEF.md new file mode 100644 index 0000000..c767653 --- /dev/null +++ b/docs/SPECS/BRIEF.md @@ -0,0 +1,10 @@ +--- +type: Brief +title: 'Briefing — bi-descomplicar' +timestamp: 2026-06-30 +layer: wiki +--- + +# BRIEF — bi-descomplicar + +Projecto bi-descomplicar do ecossistema Descomplicar. diff --git a/docs/SPECS/PROC-DEV-STANDARD-ref.md b/docs/SPECS/PROC-DEV-STANDARD-ref.md new file mode 100644 index 0000000..3102130 --- /dev/null +++ b/docs/SPECS/PROC-DEV-STANDARD-ref.md @@ -0,0 +1,120 @@ +--- +layer: wiki +title: PROC-DEV-STANDARD — Referência Rápida +description: >- + > Este ficheiro é um resumo/índice do PROC-DEV-STANDARD.md completo +type: Reference +code: D7-SIS-006 +date: 2026-05-16 +timestamp: 2026-05-16T00:00:00+01:00 +tags: [protocolo, referência, desenvolvimento] +--- + +# PROC-DEV-STANDARD — Referência Rápida + +> Este ficheiro é um resumo/índice do PROC-DEV-STANDARD.md completo. +> **Versão completa:** `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md` + +--- + +## Código & Versão + +- **Código:** D7-SIS-006 +- **Versão:** 1.0 +- **Data:** 2026-05-16 + +--- + +## Princípios Core + +1. Pesquisa antes de spec +2. Spec antes de código +3. CI verde é gate obrigatório +4. Issue-First para bugs +5. Contexto partilhado (MEMORY.md + STATUS.md) +6. Causa raiz — resolver sempre a causa, não o sintoma + +--- + +## Fluxo Completo + +``` +Ideia → Pesquisa → Spec → Plan → Desenvolvimento → Quality Gates → Code Review → Deploy +``` + +--- + +## Estrutura Obrigatória de Projecto + +``` +docs/ +├── PLANS/ # Planos de implementação +├── SPECS/ # Specs + notas de pesquisa +└── audit/ # Auditorias (se activo) + ├── audit.md + ├── security.md + ├── tech-debt.md + └── findings/ + +AGENTS.md, CHANGELOG.md, MEMORY.md, STATUS.md, .desk-project +``` + +--- + +## Ficheiros Cross-Agent + +| Ficheiro | Acção no Início | Acção no Fim | +|----------|-----------------|--------------| +| `MEMORY.md` | Ler/Criar | Escrever decisão | +| `STATUS.md` | Ler/Criar | Actualizar estado | +| `CHANGELOG.md` | — | Actualizar versão | + +--- + +## 8 Fases do Desenvolvimento + +| Fase | Input | Output | +|------|-------|--------| +| 1. Ideia | Pedido | Decisão avançar | +| 2. Pesquisa | Âmbito | `docs/SPECS/research-*.md` | +| 3. Spec | Nota pesquisa | `SPEC.md` aprovado | +| 4. Plan | Spec | `docs/PLANS/YYYY-MM-DD-*.md` | +| 5. Desenvolvimento | Plano | Commits atómicos | +| 6. Quality Gates | Código | CI verde | +| 7. Code Review | PR | Aprovação | +| 8. Deploy | PR merge | Produção | + +--- + +## Gitea vs Desk CRM + +| Gitea | Desk CRM | +|-------|----------| +| Bugs, issues, PRs, código | Projectos, sprints, tempo, facturação | + +--- + +## Auditoria (PROC-AUDIT-STANDARD — D7-SIS-007) + +| Tipo | Frequência | Gatilho | +|------|------------|---------| +| AUDIT-CODE | Mensal | Pre-deploy prod | +| AUDIT-SEC | Mensal | Pre-deploy prod | +| AUDIT-ECO | Trimestral | Mudança agente | +| AUDIT-PROJ | Semanal/sprint | Início sprint | + +**Ver:** `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-AUDIT-STANDARD.md` + +--- + +## Referências + +- `PROC-DEV-STANDARD.md` — D7-SIS-006 (completo) +- `PROC-AUDIT-STANDARD.md` — D7-SIS-007 +- `PROC-DEPLOY-STANDARD.md` — D7-SIS-005 +- `ECOSYSTEM.md` — regras partilhadas + +--- + +**Modelo-Organizacao-Proc-Dev** — Template canónico +**Desk CRM:** Task #2134 \ No newline at end of file diff --git a/docs/SPECS/SPEC.md b/docs/SPECS/SPEC.md new file mode 100644 index 0000000..0a394d3 --- /dev/null +++ b/docs/SPECS/SPEC.md @@ -0,0 +1,11 @@ +--- +type: Spec +title: 'SPEC — bi-descomplicar' +status: draft +timestamp: 2026-06-30 +layer: wiki +--- + +# SPEC — bi-descomplicar + +Projecto em estruturação. diff --git a/docs/SPECS/Workflow-Diagram.html b/docs/SPECS/Workflow-Diagram.html new file mode 100644 index 0000000..ff5ee56 --- /dev/null +++ b/docs/SPECS/Workflow-Diagram.html @@ -0,0 +1,353 @@ + + + + + + Modelo-Organizacao-Proc-Dev — Workflow + + + + +
    + +
    +
    +
    +

    Modelo-Organizacao-Proc-Dev — Fluxo de Trabalho

    +
    +

    Workflow de projectos Descomplicar®: iniciação, sessão, registo e governança

    +
    + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + F1: Iniciação de Projecto + + + + Novo Projecto + Repositório + + + + + desk.project + + AGENTS.md + + + + + docs/PLANS/ + + docs/SPECS/ + + + + + + validate-structure + scripts/ .sh + + + + + CONFORME + Exit 0 + + + + FALHA (exit 1) + + + + DONE + + + + F2: Sessão de Trabalho (Agente/Humano) + + + + 1. PLAN + Contexto: AGENTS.md + + MEMORY.md + CARL + + + + + + 2. DO + Executar (MCP/SSH) + Procurar dados reais + + + + + + 3. CHECK + Validação estrutural + Testes / QG + validate-structure.sh + + + + + + FALHA — corrigir + + + + 4. ACT + REGISTAR: MEMORY.md + + Comentário CRM + + + + + + OK + + + + F3: Separação de Responsabilidades (PROTOCOLO-CRM.md) + + + + + + DESK CRM + Contentor de Tempo e Custos + • Task Master (poucas, por projecto) + • Timer — registo de horas + • Comentários — visibilidade gestor/cliente + + + | + | + | + + + + + + GITEA / REPO + Oficina Técnica + • Código, branches, PRs + • Issues — detalhe técnico + • Milestones + CI/CD + + + | + | + | + + + + + + HUB OBSIDIAN (06-Operacoes) + Fonte de Verdade Centralizada + • Procedimentos (PROC-*) + • Quick References (QR-*) + • Runbooks — troubleshooting + + + + F4: Ecossistema de Governança + + + + CARL — Regras Activas + MODELO-ORGANIZACAO + + + + + + ESTRUTURA.md + Hierarquia Standard + + + + + + AGENTS.md + Directrizes de Agentes + + + + + + validate-structure.sh + Validação automática + Exit 0 = OK + + + + + + MEMORY.md + Registo Final + + + + AGENTS.md referência o domínio CARL correspondente + + + + Legenda: + + + Governance + + + Execução + + + Registo + + + Validação / Segurança + + + Correcção (feedback loop) + + + Fluxo/Fase + +
    + + +
    +
    +
    +
    +

    F1: Iniciação

    +
    +
      +
    • • Criar repositório e desk.project
      • +
    • • Scaffold docs/PLANS + docs/SPECS
      • +
    • • AGENTS.md com directrizes do projecto
      • +
    • • Validar com scripts/validate-structure.sh
      • +
    • • Só é "conforme" com exit 0
      • +
    +
    +
    +
    +
    +

    F2: Sessão PDCA

    +
    +
      +
    • • PLAN: Carregar AGENTS.md + MEMORY.md + CARL
      • +
    • • DO: Executar MCP/SSH — nunca assumir
      • +
    • • CHECK: validate-structure.sh + testes
      • +
    • • ACT: REGISTAR em MEMORY.md + CRM
      • +
    • • Se FALHA: loop back ao DO
      • +
    +
    +
    +
    +
    +

    F3+F4: Governança

    +
    +
      +
    • • CRM = tempo e custos (não granular)
      • +
    • • Gitea = código, issues, milestones
      • +
    • • Hub (06-Operacoes) = PROCs + Runbooks
      • +
    • • CARL regista decisões com recall keywords
      • +
    • • AGENTS.md aponta para CARL + MEMORY.md
      • +
    +
    +
    + + +

    + Modelo-Organizacao-Proc-Dev • Descomplicar® • Task CRM #2134 • Domínio CARL: MODELO-ORGANIZACAO +

    +
    + + \ No newline at end of file diff --git a/docs/SPECS/Workflow-Fluxo.drawio b/docs/SPECS/Workflow-Fluxo.drawio new file mode 100644 index 0000000..808cbd6 --- /dev/null +++ b/docs/SPECS/Workflow-Fluxo.drawio @@ -0,0 +1,195 @@ + 1| + 2| + 3| + 4| + 5| + 6| + 7| + 8| + 9| + 10| + 11| + 12| + 13| + 14| + 15| + 16| + 17| + 18| + 19| + 20| + 21| + 22| + 23| + 24| + 25| + 26| + 27| + 28| + 29| + 30| + 31| + 32| + 33| + 34| + 35| + 36| + 37| + 38| + 39| + 40| + 41| + 42| + 43| + 44| + 45| + 46| + 47| + 48| + 49| + 50| + 51| + 52| + 53| + 54| + 55| + 56| + 57| + 58| + 59| + 60| + 61| + 62| + 63| + 64| + 65| + 66| + 67| + 68| + 69| + 70| + 71| + 72| + 73| + 74| + 75| + 76| + 77| + 78| + 79| + 80| + 81| + 82| + 83| + 84| + 85| + 86| + 87| + 88| + 89| + 90| + 91| + 92| + 93| + 94| + 95| + 96| + 97| + 98| + 99| + 100| + 101| + 102| + 103| + 104| + 105| + 106| + 107| + 108| + 109| + 110| + 111| + 112| + 113| + 114| + 115| + 116| + 117| + 118| + 119| + 120| + 121| + 122| + 123| + 124| + 125| + 126| + 127| + 128| + 129| + 130| + 131| + 132| + 133| + 134| + 135| + 136| + 137| + 138| + 139| + 140| + 141| + 142| + 143| + 144| + 145| + 146| + 147| + 148| + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 149| + 150| + 151| + 152| \ No newline at end of file diff --git a/docs/SPECS/research.md b/docs/SPECS/research.md new file mode 100644 index 0000000..2bf042d --- /dev/null +++ b/docs/SPECS/research.md @@ -0,0 +1,10 @@ +--- +type: Note +title: 'Pesquisa — bi-descomplicar' +timestamp: 2026-06-30 +layer: wiki +--- + +# Pesquisa + +Documentar pesquisa aqui. diff --git a/docs/audit/audit.md b/docs/audit/audit.md new file mode 100644 index 0000000..3fe55ac --- /dev/null +++ b/docs/audit/audit.md @@ -0,0 +1,49 @@ +--- +layer: wiki +type: Document +tags: [projecto, modelo, organizacao, audit] +title: Audit +description: >- + Registo cronológico de todas as auditorias executadas. Findings detalhados em `findings/` +timestamp: 2026-05-16T19:21:21.662617+00:00 +--- +# Audit Log — Modelo-Organizacao-Proc-Dev + +Registo cronológico de todas as auditorias executadas. Findings detalhados em `findings/`. + +--- + +## 2026-05-16 — AUDIT-ECO #001 (1ª trimestral) + +**Auditor:** Claude Code (staff_id=25) +**Método:** validação directa de ficheiros de config + permissões + MCPs declarados +**Âmbito:** 4 agentes (Claude, Gemini, Hermes, OpenCode) + +### Resultado global + +| Dimensão | Estado | +|----------|--------| +| Protocolo de sessão (STATUS/MEMORY) | ✅ 4/4 agentes | +| Regra 48 (dev local) | ✅ 4/4 | +| Gitea vs Desk CRM | ✅ 4/4 | +| Worklog markdown (não HTML) | ✅ 4/4 | +| Credenciais com permissões 600 | ✅ 5/5 ficheiros | +| MCPs essenciais completos | ⚠️ 2/4 agentes | +| CARL domínio MODELO-ORGANIZACAO | ✅ 9 regras, 27 keywords | + +### Findings + +- **F-001** — Hermes sem MCPs essenciais (`desk-crm-v3`, `mcp-time`, `memory-supabase`, `ssh-unified`, `notebooklm`). Severidade: **High**. +- **F-002** — Gemini sem `desk-crm-v3` (tem apenas `desk-project-minimal`) e sem `mcp-time`. Severidade: **Medium**. + +### Conformes + +- Claude Code: protocolo completo, CARL activo, MCPs completos. +- OpenCode: protocolo adicionado nesta sessão, todos MCPs essenciais activos, credenciais movidas para `~/.opencode-secrets` (600). +- Worklog HTML eliminado em todos os agentes. + +### Próxima AUDIT-ECO + +Trimestral → **2026-08-16** (ou antes se mudança de agente/config). + +--- diff --git a/docs/audit/findings/F-001-hermes-mcps-incompletos.md b/docs/audit/findings/F-001-hermes-mcps-incompletos.md new file mode 100644 index 0000000..cd38b96 --- /dev/null +++ b/docs/audit/findings/F-001-hermes-mcps-incompletos.md @@ -0,0 +1,53 @@ +--- +layer: wiki +type: Document +tags: [projecto, modelo, organizacao, audit] +title: F 001 Hermes Mcps Incompletos +description: >- + Finding F-001: Hermes sem MCPs essenciais — desk-crm-v3, mcp-time, ssh-unified em falta, severidade High. +timestamp: 2026-05-16T19:21:33.900726+00:00 +--- +# F-001 — Hermes sem MCPs essenciais + +**Data:** 2026-05-16 +**Tipo:** ECO +**Severidade:** High +**Estado:** Open + +## Descrição + +O `~/.hermes/config.yaml` declara apenas `mcp-gitea` (local Node.js). Faltam: + +- `desk-crm-v3` (planeado no ECOSYSTEM.md — "✅" para Hermes) +- `mcp-time` +- `memory-supabase` +- `ssh-unified` +- `notebooklm` + +Apenas `memory_enabled: true` (memória interna do Hermes, não Supabase). + +## Impacto + +Hermes não consegue: +- Criar/actualizar tasks Desk CRM (Sistema Triangular comprometido) +- Consultar timestamps via MCP (cai para `date` local — sem timezone garantido) +- Persistir conhecimento no Supabase (memória só interna) +- Executar comandos em servidores remotos via SSH (operações de infra impossíveis) +- Consultar os 65 notebooks NotebookLM + +## Resolução + +Adicionar entradas MCP no `~/.hermes/config.yaml`. Endpoints já existem no gateway: +- `gateway.descomplicar.pt/v1/desk-crm/mcp` (3150) +- `gateway.descomplicar.pt/v1/memory/mcp` (3151) +- `gateway.descomplicar.pt/v1/mcp-time/mcp` +- `gateway.descomplicar.pt/v1/ssh-unified/mcp` +- `gateway.descomplicar.pt/v1/notebooklm/mcp` + +Tipo: `http` (mesmo padrão do MCP EasyPanel adicionado em 2026-05-13 sessão 3). + +## Referências + +- Issue Gitea: a criar +- ECOSYSTEM.md §9 (tabela MCPs por agente) +- MEMORY.md (Hub) — `mcp-gateway.md` diff --git a/docs/audit/findings/F-002-gemini-mcps-parciais.md b/docs/audit/findings/F-002-gemini-mcps-parciais.md new file mode 100644 index 0000000..482cd90 --- /dev/null +++ b/docs/audit/findings/F-002-gemini-mcps-parciais.md @@ -0,0 +1,44 @@ +--- +layer: wiki +type: Document +tags: [projecto, modelo, organizacao, audit] +title: F 002 Gemini Mcps Parciais +description: >- + Finding F-002: Gemini sem desk-crm-v3 e mcp-time — MCPs parciais no agente Gemini, severidade Medium. +timestamp: 2026-05-16T19:21:44.099816+00:00 +--- +# F-002 — Gemini sem desk-crm-v3 e mcp-time + +**Data:** 2026-05-16 +**Tipo:** ECO +**Severidade:** Medium +**Estado:** Open + +## Descrição + +`~/.gemini/settings.json` declara 8 MCP servers, mas: + +- Usa `desk-project-minimal` (Node.js local) em vez de `desk-crm-v3` (gateway HTTP, ferramentas completas) +- Não tem `mcp-time` (ECOSYSTEM.md §9 marca como "adicionar") + +Restantes essenciais OK: `gitea`, `memory-supabase`, `notebooklm`, `filesystem`, `carl`. + +## Impacto + +- `desk-project-minimal` expõe ~10 ferramentas vs `desk-crm-v3` com >150. Gemini não consegue gerir leads, propostas, facturas, analytics CRM. +- Sem `mcp-time`, Gemini cai para `date` local — risco de timezone em conversões. + +## Resolução + +Adicionar ao `~/.gemini/settings.json > mcpServers`: + +```json +"desk-crm-v3": {"httpUrl": "https://gateway.descomplicar.pt/v1/desk-crm/mcp"}, +"mcp-time": {"httpUrl": "https://gateway.descomplicar.pt/v1/mcp-time/mcp"} +``` + +Manter `desk-project-minimal` se for ainda usado para projectos locais — caso contrário remover. + +## Referências + +- ECOSYSTEM.md §9 diff --git a/index.md b/index.md new file mode 100644 index 0000000..e5de39f --- /dev/null +++ b/index.md @@ -0,0 +1,9 @@ +# bi-descomplicar + +## Documentação + +- [README](README.md) +- [AGENTS](AGENTS.md) +- [STATUS](STATUS.md) +- [MEMORY](MEMORY.md) +- [CHANGELOG](CHANGELOG.md) diff --git a/log.md b/log.md new file mode 100644 index 0000000..6cccf6c --- /dev/null +++ b/log.md @@ -0,0 +1,3 @@ +## 2026-06-30 init | Estrutura padrão aplicada + +- Estrutura PROC-DEV-STANDARD propagada