From 79206f6526f87f936efd77fba5284840ac3b809a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francisco=20Ign=C3=A1cio=20Fontoura=20Solla?= Date: Thu, 30 Jul 2026 05:22:58 -0300 Subject: [PATCH] chore: format docs --- docs/AGENT-OPS.md | 40 +++++------ docs/CHANGELOG-AGENTS.md | 1 - docs/PAYLOAD-REFERENCE.md | 1 - docs/plans/paradigma-agentes-paralelos.md | 85 +++++++++++------------ 4 files changed, 62 insertions(+), 65 deletions(-) diff --git a/docs/AGENT-OPS.md b/docs/AGENT-OPS.md index cce83cf4..fa6e3291 100644 --- a/docs/AGENT-OPS.md +++ b/docs/AGENT-OPS.md @@ -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 -- ` | 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 -- ` | 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). diff --git a/docs/CHANGELOG-AGENTS.md b/docs/CHANGELOG-AGENTS.md index 4dfca455..240b253f 100644 --- a/docs/CHANGELOG-AGENTS.md +++ b/docs/CHANGELOG-AGENTS.md @@ -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**. - diff --git a/docs/PAYLOAD-REFERENCE.md b/docs/PAYLOAD-REFERENCE.md index 1fd2fd09..490853e8 100644 --- a/docs/PAYLOAD-REFERENCE.md +++ b/docs/PAYLOAD-REFERENCE.md @@ -6,7 +6,6 @@ Os padrões CRÍTICOS de segurança também vivem em `.cursor/rules/security-cri --- - ## Configuration ### Minimal Config Pattern diff --git a/docs/plans/paradigma-agentes-paralelos.md b/docs/plans/paradigma-agentes-paralelos.md index 56b957fe..ad79502e 100644 --- a/docs/plans/paradigma-agentes-paralelos.md +++ b/docs/plans/paradigma-agentes-paralelos.md @@ -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 | ---