# Agente Central de Quadros e Projetos

Sistema **interno e privado** de gestao central de projetos e quadros do ecossistema Gabriel/AgenciAR, operado no GitHub usando:

- GitHub CLI
- tarefas agendadas do Codex/Claude
- diario append-only
- reconciliacao incremental
- relatorios e excecoes auditaveis

Este repositorio e **privado**. Ele governa os quadros e projetos reais do Gabriel/AgenciAR.

Abrir uma versao open source e um plano **futuro**, a ser feito por duplicacao deste repo, com sanitizacao propria. Enquanto isso nao acontecer, nada aqui e escrito para consumo publico. Segredos, credenciais e dados de cliente continuam proibidos em qualquer arquivo versionado -- eles vivem no mapa de acessos do Hermes.

## Credenciais, tokens e CLIs

Este repo guarda apenas o **indice operacional** e os **docs copiados** para consulta central. O cofre canônico continua sendo o Hermes.

### Fonte canonica

- [`imports/hermes/integracoes/credenciais/MASTER-ACCESS-MAP.md`](imports/hermes/integracoes/credenciais/MASTER-ACCESS-MAP.md)
- [`imports/hermes/integracoes/PAINEL-DE-INTEGRACOES.md`](imports/hermes/integracoes/PAINEL-DE-INTEGRACOES.md)
- [`imports/hermes/BOT-ACCESS-START-HERE.md`](imports/hermes/BOT-ACCESS-START-HERE.md)

### CLIs e acessos já mapeados

- `gh` - GitHub CLI
- `gcloud` - Google Cloud / contas Google
- `gmp` - Search Console, GA4, GTM, Ads, BigQuery
- `vercel` - deploy e contas Vercel
- `firebase` - projetos Firebase
- `gws` - Google Workspace
- `composio` - integrações MCP/SDK
- `wrangler` - Cloudflare
- `wavespeed` - multimodal

### Repos importados com docs de apoio

- `imports/hermes/`
- `imports/agenciar-hub/`
- `imports/agenciar-infra-docs/`
- `imports/agenciar-ops-lab/`
- `imports/exportador-conversas-claude-code-desktop/`

### Regra

- nao colocar segredo bruto em texto novo
- usar estes imports como referencia operacional
- consultar o Hermes antes de qualquer rotacao, login ou revogacao

## O que e

`Agente Central de Quadros e Projetos` e a camada central de governanca. Ele nao substitui os repositorios de produto. Cada repositorio monitorado continua sendo a fonte de verdade do proprio dominio. O papel desta base e:

- consolidar backlog, prioridades, gates, responsaveis e evidencias;
- reconciliar atividade recente do GitHub via `gh` CLI;
- detectar trabalho nao registrado no quadro central;
- manter um diario operacional append-only;
- gerar relatorios reproduziveis para operacao humana ou agentes.

## Como funciona

1. Uma tarefa agendada nativa do Codex abre um novo chat em cada ciclo.
2. O agente roda os scripts locais com `gh` autenticado.
3. O script consulta eventos, commits, issues, PRs e status de Projects dos repos monitorados.
4. Os fatos sao normalizados para o contrato central.
5. O journal append-only recebe apenas eventos novos.
6. A reconciliacao abre excecoes para trabalho sem registro esperado.
7. O relatorio consolidado fica pronto para leitura, sem depender de webhooks.

## Catalogo publico de capacidades

Toda capacidade publica do projeto deve nascer em um catalogo declarativo e sanitizado.

Fluxo:

1. uma rotina privada aprovada gera um registro interno sanitizado;
2. esse registro vira entrada no catalogo publico;
3. os artefatos publicos sao gerados a partir dele;
4. checks de redacao e seguranca bloqueiam vazamento;
5. revisao humana ou aprovacao explicita libera a publicacao.

Artefatos derivados:

- `README.md`
- `docs/CHANGELOG.md`
- pagina interna de visao geral (`index.html`)
- resumos de release

<!-- CAPABILITIES:START -->
- **Scheduled reconciliation**: Runs portfolio reconciliation through a scheduled Codex or Claude task and GitHub CLI.
- **Unregistered work detection**: Flags GitHub activity that is missing expected board registration signals.
- **Public capability catalog**: Generates public artifacts from a sanitized, declarative capability registry.
<!-- CAPABILITIES:END -->

## Por que CLI/Codex-first

- menos infraestrutura;
- operacao reproduzivel em qualquer clone;
- sem endpoint publico;
- fallback simples: rodar a tarefa novamente;
- permanece portavel caso o repo seja duplicado para uma versao aberta no futuro.

Webhooks ficam apenas como evolucao opcional futura, caso a necessidade de baixa latencia seja comprovada.

## Para quem serve

- times pequenos com varios repositorios e GitHub Projects;
- operadores que usam Codex/Claude como camada de execucao;
- consultorias, agencias e squads com backlog fragmentado;
- pessoas que querem um diario central auditavel sem montar uma plataforma inteira.

## Estrutura

```text
.
├── AGENTS.md
├── index.html
├── styles.css
├── app.js
├── package.json
├── vercel.json
├── config/
│   ├── board-rules.example.json
│   └── sources.example.json
├── catalog/
│   ├── capabilities.public.json
│   └── release-policy.example.json
├── docs/
│   ├── ARCHITECTURE.md
│   ├── BEST-PRACTICES.md
│   ├── CHANGELOG.md
│   ├── DATA-MODEL.md
│   ├── DECISIONS.md
│   ├── IMPLEMENTATION-PLAN.md
│   ├── OPERATIONS.md
│   ├── REPORTING-CADENCE.md
│   ├── SDD.md
│   ├── SECURITY-GUARDRAILS.md
│   ├── SPEC.md
│   ├── THREAT-MODEL.md
│   └── WORKFLOWS.md
├── examples/
│   ├── event-journal.sample.ndjson
│   └── report.sample.json
├── prompts/
│   ├── codex-daily-report.md
│   └── codex-scheduled-reconcile.md
├── runtime/
│   └── .gitkeep
├── schemas/
│   ├── event.schema.json
│   └── source.schema.json
└── scripts/
    ├── bootstrap-workspace.mjs
    ├── build-public-artifacts.mjs
    ├── reconcile.mjs
    ├── review-public-release.mjs
    └── render-report.mjs
```

## Inicio rapido

```bash
npm install
cp config/sources.example.json config/sources.local.json
cp config/board-rules.example.json config/board-rules.local.json
node scripts/bootstrap-workspace.mjs
node scripts/reconcile.mjs --config config/sources.local.json --rules config/board-rules.local.json --since 2026-08-01T00:00:00Z
node scripts/render-report.mjs
node scripts/build-public-artifacts.mjs
node scripts/review-public-release.mjs
```

## Requisitos

- Node.js 20+
- `gh` CLI autenticado
- acesso de leitura aos repositorios e Projects monitorados
- operador humano ou tarefa agendada do Codex/Claude

## Operacao em qualquer conta GitHub

1. Clone o repositorio.
2. Substitua os arquivos `*.example.json` por configuracoes da sua conta.
3. Garanta `gh auth status` valido.
4. Configure uma tarefa agendada no Codex usando [prompts/codex-scheduled-reconcile.md](prompts/codex-scheduled-reconcile.md).
5. Execute reconciliacao e relatorio no intervalo desejado.

## Limites

- nao ha write-back automatico nesta fase;
- nao ha alerta externo automatico nesta fase;
- heuristicas de trabalho nao registrado exigem calibracao por contexto;
- Projects complexos podem precisar de mapeamentos customizados.
- a duplicacao futura para open source exige sanitizacao e revisao humana antes de qualquer publicacao.

## Seguranca

- use apenas configs locais fora do git para dados reais;
- nao grave segredos em `config/*.json`;
- `config/*.example.json` e `examples/` contem apenas dados sinteticos;
- detalhes em [docs/SECURITY-GUARDRAILS.md](docs/SECURITY-GUARDRAILS.md) e [docs/THREAT-MODEL.md](docs/THREAT-MODEL.md).

## Docs

- visao geral interna: `index.html` (nao publicada)
- arquitetura: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- operacao: [docs/OPERATIONS.md](docs/OPERATIONS.md)
- SPEC: [docs/SPEC.md](docs/SPEC.md)
- SDD: [docs/SDD.md](docs/SDD.md)

## Licenca

MIT.