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 (`

`, `