fsolla/teqo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

chore: format docs

Browse source
This commit is contained in:
Francisco Ignácio Fontoura Solla 2026-07-30 05:22:58 -03:00
parent e0430e559b
commit 79206f6526
4 changed files with 62 additions and 65 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
docs/AGENT-OPS.md
View file

@ -4,11 +4,11 @@ Uma página. Norte: simplicidade (só GitHub + Cursor), agente para no merge a `
## Ambientes de dados (test ladder — nunca misturar)
| Ambiente | Conteúdo | Quem usa |
| --- | --- | --- |
| **Mínimo** (`teqo_test` local / service CI) | schema migrado + `pnpm db:seed:minimal` (sintético, sem PII) | agentes, Cursor Cloud, CI de PR |
| **Stage** (Neon branch `stage`, clone de prod) | snapshot 100% de prod (PII!) | só CI `ci-stage.yml` + humanos em smoke controlado |
| **Prod** (Neon prod) | real | deploy Vercel a partir de `main` apenas |
| Ambiente | Conteúdo | Quem usa |
| ---------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------- |
| **Mínimo** (`teqo_test` local / service CI) | schema migrado + `pnpm db:seed:minimal` (sintético, sem PII) | agentes, Cursor Cloud, CI de PR |
| **Stage** (Neon branch `stage`, clone de prod) | snapshot 100% de prod (PII!) | só CI `ci-stage.yml` + humanos em smoke controlado |
| **Prod** (Neon prod) | real | deploy Vercel a partir de `main` apenas |
Agentes **nunca** recebem `DATABASE_URL` de stage/prod e nunca setam `ALLOW_REMOTE_DB`. O escape `ALLOW_STAGE_TEST_DB` (`tests/helpers/assertTestDatabase.ts`) só existe para o workflow `ci-stage.yml`.
@ -25,15 +25,15 @@ stage → CI stage green → (humano) pnpm agent:promote --i-am-human → main
## Comandos
| Comando | Faz |
| --- | --- |
| `pnpm agent:claim [-- --dry-run]` | Fila ready+unblocked por prio → `in-progress` + brief no stdout. Deps sem Issue = itens entregues do roadmap (satisfeitas, avisadas no brief) |
| `pnpm agent:register -- --id X --title T [--prio P1] [--depends A,B] [--plan docs/plans/x.md]` | Cria Issue (spec + labels) |
| `pnpm agent:prioritize -- <issue> <P0..P3>` | Troca a label `prio:*` |
| `pnpm agent:file-miss -- --title ...` | Issue `kind:agent-miss` → harvest em guardrail (`docs/GUARDRAILS.md`) |
| `pnpm agent:promote -- --i-am-human` | **Humano:** PR `stage→main` + merge se CI green |
| `pnpm db:seed:minimal` | DB mínimo sintético (contrato: [`scripts/lib/seed-minimal-manifest.mjs`](../scripts/lib/seed-minimal-manifest.mjs), pin `tests/unit/seedMinimalManifest.unit.spec.ts`) |
| `pnpm db:refresh:stage` | **Humano:** nova Neon branch `stage` de prod + swap do secret `STAGE_DATABASE_URL` (requer `NEON_API_KEY`) |
| Comando | Faz |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pnpm agent:claim [-- --dry-run]` | Fila ready+unblocked por prio → `in-progress` + brief no stdout. Deps sem Issue = itens entregues do roadmap (satisfeitas, avisadas no brief) |
| `pnpm agent:register -- --id X --title T [--prio P1] [--depends A,B] [--plan docs/plans/x.md]` | Cria Issue (spec + labels) |
| `pnpm agent:prioritize -- <issue> <P0..P3>` | Troca a label `prio:*` |
| `pnpm agent:file-miss -- --title ...` | Issue `kind:agent-miss` → harvest em guardrail (`docs/GUARDRAILS.md`) |
| `pnpm agent:promote -- --i-am-human` | **Humano:** PR `stage→main` + merge se CI green |
| `pnpm db:seed:minimal` | DB mínimo sintético (contrato: [`scripts/lib/seed-minimal-manifest.mjs`](../scripts/lib/seed-minimal-manifest.mjs), pin `tests/unit/seedMinimalManifest.unit.spec.ts`) |
| `pnpm db:refresh:stage` | **Humano:** nova Neon branch `stage` de prod + swap do secret `STAGE_DATABASE_URL` (requer `NEON_API_KEY`) |
Labels: estado `ready|in-progress|blocked|done|in-prod`, `prio:P0..P3`, `kind:feature|defect|chore|agent-miss`, `needs:migration|consent`, `requirements-changed`. Issues carregam frontmatter `id/depends/serializes/priority` no body.
@ -45,12 +45,12 @@ Labels: estado `ready|in-progress|blocked|done|in-prod`, `prio:P0..P3`, `kind:fe
## CI por alvo
| Workflow | Trigger | Banco | Passos |
| --- | --- | --- | --- |
| `ci-pr.yml` | PR → `stage`/`main` | service Postgres 17 (mínimo) | lint, format, typecheck, knip, cycles, unit → migrate → **seed:minimal** → int → **build** + `migration-lock` |
| `ci-stage.yml` | push em `stage` | `STAGE_DATABASE_URL` (Environment `stage`) | **só** `migrate` + `test:int` — **NUNCA `pnpm build`** (build migra o banco que vê), nunca seed:minimal |
| `ci.yml` | push em `main` | service Postgres | gate pós-promote |
| E2E | fora do caminho crítico (nightly/label futura) | — | não bloqueia autonomia |
| Workflow | Trigger | Banco | Passos |
| -------------- | ---------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `ci-pr.yml` | PR → `stage`/`main` | service Postgres 17 (mínimo) | lint, format, typecheck, knip, cycles, unit → migrate → **seed:minimal** → int → **build** + `migration-lock` |
| `ci-stage.yml` | push em `stage` | `STAGE_DATABASE_URL` (Environment `stage`) | **só** `migrate` + `test:int` — **NUNCA `pnpm build`** (build migra o banco que vê), nunca seed:minimal |
| `ci.yml` | push em `main` | service Postgres | gate pós-promote |
| E2E | fora do caminho crítico (nightly/label futura) | — | não bloqueia autonomia |
Fast gate local do agente antes do push: `pnpm lint && pnpm exec tsc --noEmit && pnpm test:unit` (+ `pnpm format:check` e `pnpm check:cycles` antes de commitar; int/build = CI).

1
docs/CHANGELOG-AGENTS.md
View file

@ -102,4 +102,3 @@ Backlog consolidado (bloqueadores, site, campanha, white-label): [`docs/roadmap.
**Recently resolved (2026-07-24):** **B19** Gerenciar assessores — `/campanha/assessores` (lista + novo + detalhe) for coordinator/candidate only (`isCampaignUnrestricted`); create/edit `advisor` accounts, municipality portfolio (per-municipality auto-save + advisory lock), password-reset email (blocks `@planilha.invalid`); aligned `canUpdateCampaignUser` / phone field access / `canAssignMunicipalityAdvisors` / `assignMunicipalityAdvisorsRecord` to unrestricted; privileged email read in `advisorData` loaders after the route gate; `reloadUnrestrictedActor`. No migration. Plano: [`docs/plans/gerenciar-assessores.md`](docs/plans/gerenciar-assessores.md).
**Recently resolved (2026-07-23):** **A10** Cenários de estimativa (pessimista/média/otimista) — `votePledge.estimatedVotes` e `municipality.expectedVotes` viram groups (`pessimistic|central|optimistic`); migration `20260723_124200_add_vote_estimate_scenarios` (backfill scalar→`central`); agregação por cenário em `votePledgeData` com default `central`; mapa 2026 com `values2026ByScenario` + seletor local; lista/overview/dashboard com média + faixa secundária; liderança continua com um `declaredVotes` sem ver estimativas. Plano: [`docs/plans/cenarios-estimativa-votos.md`](docs/plans/cenarios-estimativa-votos.md). Desbloqueia **E8**.

1
docs/PAYLOAD-REFERENCE.md
View file

@ -6,7 +6,6 @@ Os padrões CRÍTICOS de segurança também vivem em `.cursor/rules/security-cri
---
## Configuration
### Minimal Config Pattern

85
docs/plans/paradigma-agentes-paralelos.md
View file

@ -1,30 +1,30 @@
---
name: Paradigm parallel agents
overview: "GitHub + Cursor only: Issues/PR/Actions; agents claim→PR→stage with minimal DB; stage = Neon prod snapshot (restricted); main/prod só via promote humano com CI; miss→guardrail progressivo."
overview: 'GitHub + Cursor only: Issues/PR/Actions; agents claim→PR→stage with minimal DB; stage = Neon prod snapshot (restricted); main/prod só via promote humano com CI; miss→guardrail progressivo.'
todos:
- id: onda0-minimal-db
content: "Script db:seed:minimal idempotente (collections/fixtures mínimas) + contrato PR: schema/migration exige atualizar seed no mesmo PR"
content: 'Script db:seed:minimal idempotente (collections/fixtures mínimas) + contrato PR: schema/migration exige atualizar seed no mesmo PR'
status: pending
- id: onda0-ci-pr
content: "ci.yml PR: service Postgres 17 → migrate → seed:minimal → int → build; check 1 PR em migrations"
content: 'ci.yml PR: service Postgres 17 → migrate → seed:minimal → int → build; check 1 PR em migrations'
status: pending
- id: onda0-stage-git
content: "Branch stage + protection + merge→stage CI (int/e2e contra STAGE_DATABASE_URL, NUNCA build); labels/prio + scripts claim|register|prioritize|file-miss|promote; seed Issues"
content: 'Branch stage + protection + merge→stage CI (int/e2e contra STAGE_DATABASE_URL, NUNCA build); labels/prio + scripts claim|register|prioritize|file-miss|promote; seed Issues'
status: pending
- id: onda0-stage-data
content: "Neon prod snapshot → branch stage; runbook refresh (nova branch + swap secret) via workflow_dispatch humano"
content: 'Neon prod snapshot → branch stage; runbook refresh (nova branch + swap secret) via workflow_dispatch humano'
status: pending
- id: onda0-cursor-context
content: "AGENT-OPS.md + fatiar AGENTS + kernels + .cursorignore + Cloud env + hooks portáteis + standards fast-gate + PR template + README cheatsheet"
content: 'AGENT-OPS.md + fatiar AGENTS + kernels + .cursorignore + Cloud env + hooks portáteis + standards fast-gate + PR template + README cheatsheet'
status: pending
- id: onda0-remove-codeberg
content: "Remover Codeberg de package.json/AGENTS/TECH-DEBT/ci.yml e qualquer referência; GitHub = única casa"
content: 'Remover Codeberg de package.json/AGENTS/TECH-DEBT/ci.yml e qualquer referência; GitHub = única casa'
status: pending
- id: onda1-autonomy
content: "Skills claim→PR base stage; Automation requirements-changed; promote só humano; ship-to-main morto"
content: 'Skills claim→PR base stage; Automation requirements-changed; promote só humano; ship-to-main morto'
status: pending
- id: onda2-stage-ops-guardrails
content: "Harvest agent-miss→guardrails; compile-roadmap opcional; Vercel staging se necessário"
content: 'Harvest agent-miss→guardrails; compile-roadmap opcional; Vercel staging se necessário'
status: pending
isProject: false
---
@ -41,14 +41,14 @@ isProject: false
Stack exclusiva:
| Papel | Onde |
| --- | --- |
| Spec + status + deps + miss + prio | **GitHub Issues** |
| Integração contínua de features | Branch **`stage`** + PRs |
| Produção | Branch **`main`** → Vercel prod (só promote humano) |
| Qualidade | **GitHub Actions** (DB conforme o alvo) |
| Execução | **Cursor** (Cloud/local) |
| Doctrine | **Repo** (kernels) |
| Papel | Onde |
| ---------------------------------- | --------------------------------------------------- |
| Spec + status + deps + miss + prio | **GitHub Issues** |
| Integração contínua de features | Branch **`stage`** + PRs |
| Produção | Branch **`main`** → Vercel prod (só promote humano) |
| Qualidade | **GitHub Actions** (DB conforme o alvo) |
| Execução | **Cursor** (Cloud/local) |
| Doctrine | **Repo** (kernels) |
```mermaid
flowchart LR
@ -73,11 +73,11 @@ Paralelismo hoje esbarra em roadmap/plans/ship-to-main/gate local; testes int de
Três bancos, papéis distintos — não misturar:
| Ambiente | Conteúdo | Quem usa |
| --- | --- | --- |
| **Mínimo** (`teqo_test` / service CI) | Schema migrado + seed sintético pequeno, sem PII real | Agentes, Cloud, CI de **PR → stage** |
| **Stage** (Neon `teqo_stage` ou branch Neon) | Clone **100%** de prod, renovado periodicamente | Só CI pós-merge em `stage` + humanos em smoke controlado |
| **Prod** (Neon prod) | Real | Deploy Vercel a partir de `main` apenas |
| Ambiente | Conteúdo | Quem usa |
| -------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------- |
| **Mínimo** (`teqo_test` / service CI) | Schema migrado + seed sintético pequeno, sem PII real | Agentes, Cloud, CI de **PR → stage** |
| **Stage** (Neon `teqo_stage` ou branch Neon) | Clone **100%** de prod, renovado periodicamente | Só CI pós-merge em `stage` + humanos em smoke controlado |
| **Prod** (Neon prod) | Real | Deploy Vercel a partir de `main` apenas |
**Invariante de agente/Cloud:** nunca `DATABASE_URL` de stage/prod; nunca `ALLOW_REMOTE_DB` salvo promote/refresh humano documentado. Guards existentes (`assert-local-database`, `guard-dev-db`) permanecem; stage CI usa secret só no runner GHA.
@ -125,12 +125,12 @@ pnpm test:unit # fast gate local
## Fluxo git: feature → stage → main
| Passo | Quem | Regra |
| --- | --- | --- |
| PR feature → **`stage`** | Agente (`gh pr create --base stage`) | CI **PR** green (DB mínimo) |
| Merge em `stage` | **Automático** quando CI PR green | **NUNCA** roda `pnpm build` (migra prod). CI stage = `migrate` + `int` (+ opcional e2e smoke) contra `STAGE_DATABASE_URL`. Fecha Issue / unblock deps. |
| **`stage` → `main`** | **Só humano**: `pnpm agent:promote --i-am-human`, confirmação explícita em sessão de agente, ou `workflow_dispatch` manual | Requer CI stage green + CI do PR promote green (service Postgres + build). Antes: rebase/merge de `main` em `stage` se divergiu. |
| `main` → prod | Vercel no push de `main` | Como hoje; migrate no build. |
| Passo | Quem | Regra |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| PR feature → **`stage`** | Agente (`gh pr create --base stage`) | CI **PR** green (DB mínimo) |
| Merge em `stage` | **Automático** quando CI PR green | **NUNCA** roda `pnpm build` (migra prod). CI stage = `migrate` + `int` (+ opcional e2e smoke) contra `STAGE_DATABASE_URL`. Fecha Issue / unblock deps. |
| **`stage` → `main`** | **Só humano**: `pnpm agent:promote --i-am-human`, confirmação explícita em sessão de agente, ou `workflow_dispatch` manual | Requer CI stage green + CI do PR promote green (service Postgres + build). Antes: rebase/merge de `main` em `stage` se divergiu. |
| `main` → prod | Vercel no push de `main` | Como hoje; migrate no build. |
Agente **default: para no merge a stage**. Promote não é autónomo.
@ -187,16 +187,15 @@ Fast gate local do agente (antes do push): `lint + typecheck + unit` (+ opcional
## Superfície de comandos
| Comando | Faz |
| --- | --- |
| `pnpm agent:claim` | Fila ready+unblocked por prio → `in-progress` + brief |
| `pnpm agent:register` | Cria Issue (spec + prio) |
| `pnpm agent:prioritize` | Reajusta prio |
| `pnpm agent:file-miss` | Issue kind:agent-miss/defect |
| Comando | Faz |
| --------------------------------- | ------------------------------------------------------------------------------------------------ |
| `pnpm agent:claim` | Fila ready+unblocked por prio → `in-progress` + brief |
| `pnpm agent:register` | Cria Issue (spec + prio) |
| `pnpm agent:prioritize` | Reajusta prio |
| `pnpm agent:file-miss` | Issue kind:agent-miss/defect |
| `pnpm agent:promote --i-am-human` | **Humano:** PR `stage→main` + merge se CI green; recusa se `main` divergiu de `stage` sem rebase |
| `pnpm db:seed:minimal` | DB mínimo para agentes/CI PR |
| `pnpm db:refresh:stage` | **Humano/CI manual:** nova Neon branch stage + atualiza secret (não roda em agente) |
| `pnpm db:seed:minimal` | DB mínimo para agentes/CI PR |
| `pnpm db:refresh:stage` | **Humano/CI manual:** nova Neon branch stage + atualiza secret (não roda em agente) |
Labels: estado `ready|in-progress|blocked|done`; `kind:*`; `prio:P0`…`P3`; `needs:migration|consent`; `requirements-changed`.
@ -222,13 +221,13 @@ Cloud env: `gh` autenticado (Cursor GitHub integration); sem secrets de stage/pr
## Cursor Cloud readiness
| Item | Ação |
| --- | --- |
| Item | Ação |
| -------- | --------------------------------------------------------------- |
| Contexto | Fatiar AGENTS; kernels PRODUCT/DESIGN/CUSTOMER; `.cursorignore` |
| Env | Compose Postgres + `migrate` + `db:seed:minimal` |
| Hooks | Paths relativos |
| Regra | PR base `stage`; nunca Neon; 1 Issue/run |
| Brief | stdout do claim |
| Env | Compose Postgres + `migrate` + `db:seed:minimal` |
| Hooks | Paths relativos |
| Regra | PR base `stage`; nunca Neon; 1 Issue/run |
| Brief | stdout do claim |
---