constellai 0.3.0

package/docs/pt/GITHUB.md

@@ -0,0 +1,341 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/GITHUB.md) · [✦ Constella](../../README.pt-BR.md)
+
+# GitHub 🛰️
+
+![](../assets/divider-orbit.svg)
+
+A baía de lançamento que conecta o workspace de uma constelação a um remoto Git real. Daqui partem duas rotas de voo distintas: **Commit GitHub** (o workspace completo do plano de controle → o `origin` vinculado) e **Export Clean Source** (apenas o produto, sem a camada interna da Constella → um repositório separado). Ambas passam pela mesma comporta de varredura de segredos.
+
+> Fonte da verdade: [`src/server/github.ts`](../../src/server/github.ts), [`src/server/prepare-deploy.ts`](../../src/server/prepare-deploy.ts), [`src/server/git-scan.ts`](../../src/server/git-scan.ts).
+
+---
+
+## 1. Quando usar 🌠
+
+- Você conectou uma conta GitHub durante o onboarding (ou quer conectar/substituir uma agora).
+- Um agente (ou você) terminou um trabalho e quer **histórico git local real** mais um **push para o remoto**.
+- Você quer publicar **apenas o produto** — sem `.claude/`, docs de planejamento ou qualquer arquivo interno de controle — em um repositório público/separado.
+- Você precisa garantir que nenhum segredo vazou antes que algo deixe a nave.
+
+---
+
+## 2. Como funciona 🌌
+
+Todo workspace vive na raiz da organização em disco (`orgRoot(org.id)`). O módulo GitHub opera sobre esse diretório como um **repositório git normal**:
+
+- `ensureRepo(cwd)` executa `git init -b main` no primeiro uso e cria um `.gitignore` padrão para que `git add -A` nunca prepare `node_modules/`, `.next/`, `dist/`, saída de build, `.env*`, `uploads/` ou `.testdev/`.
+- A autenticação usa um **token do GitHub** resolvido por `ghToken(workspaceId, userId)`:
+  1. **PAT no cofre** (`getSecret(workspaceId, "github_pat")`) — preferido.
+  2. **Token de acesso OAuth** — o `account.accessToken` do GitHub do usuário (via better-auth), utilizável para git **somente** se o app OAuth recebeu o escopo `repo`.
+- O token é **redatado de toda string capturada** (`redact()` divide pela string do token e a substitui por `***`), de modo que nunca pode vazar para uma notificação, o Inbox ou a UI.
+- Todas as chamadas à API do GitHub passam por `ghApi(token, path)` contra `https://api.github.com` com timeout de 12s e `User-Agent: constella`.
+
+### As duas rotas de voo
+
+| Rota | Função | Diretório de origem | Alvo | Remove a camada interna? | Estilo de push |
+|------|--------|---------------------|------|--------------------------|----------------|
+| **Commit GitHub** | `commitPush()` em `github.ts` | o workspace ao vivo (`orgRoot`) | o repositório `origin` **vinculado** | Não — faz commit de todo o workspace (menos o `.gitignore`) | `git push HEAD:<branch>` |
+| **Export Clean Source** | `exportCleanSource()` em `prepare-deploy.ts` | uma árvore limpa em **temp** | um repositório **separado** (`owner/repo`) | Sim — só sobrevive o que passa por `isCleanProductPath` | `git push -f HEAD:<branch>` |
+
+---
+
+## 3. Fluxo principal 🚀
+
+### Conectar
+
+```
+connectGitHub(pat)
+  → trim + checagem de tamanho
+  → GET https://api.github.com/user  (verifica que o token de fato funciona; 401 → erro)
+  → apaga qualquer linha github_pat existente → putSecret(ws, "github_pat", token)
+  → vincula { login, repo: undefined, defaultBranch: undefined } em workspace.settings.github
+```
+
+O vínculo de repositório é **limpo ao (re)conectar**, para que uma conta diferente não consiga dar push no repositório da conta anterior.
+
+### Vincular um repositório
+
+```
+setRepo("owner/repo")
+  → normaliza (remove https://github.com/ e .git)
+  → ghToken() precisa alcançar GET /repos/owner/repo  (404 → "o token não consegue acessá-lo")
+  → ensureRepo(cwd) → git remote add|set-url origin https://github.com/owner/repo.git
+  → persiste settings.github = { repo, defaultBranch }
+```
+
+`createRepo({ name, private })` é um atalho: faz `POST` em `/user/repos` e então chama `setRepo` no novo nome completo.
+
+### Commit + push
+
+`commitPush({ repo, branch, message, delegated?, force? })` executa três portões de segurança **antes** de tocar no git, então faz o commit e (opcionalmente) push / abre um PR. Veja [§4](#4-conceitos-chave-) e o diagrama em [§8](#8-diagramas-mermaid-).
+
+### Exportar código limpo
+
+`exportCleanSource({ repo, token?, branch?, message? })` copia apenas o produto limpo para um diretório temporário, varre-o e faz force-push para um repositório **diferente**. Ele nunca toca no `origin` do próprio workspace.
+
+---
+
+## 4. Conceitos-chave 🪐
+
+### PAT vs token OAuth
+
+| | PAT no cofre (`github_pat`) | OAuth `account.accessToken` |
+|---|---|---|
+| Armazenado onde | tabela `vault`, AES-256-GCM (`CONSTELLA_VAULT_KEY`) | linha `account` do better-auth |
+| Definido por | `connectGitHub()` / onboarding | login OAuth do GitHub |
+| Usado para git push? | Sim | Somente se receber o escopo `repo` |
+| Precedência | **Primeiro** (preferido) | Fallback quando não há PAT |
+| Por empresa | Sim — no cofre por `workspaceId` | Por conta de usuário |
+
+`ghToken()` sempre retorna o PAT se presente, caso contrário o token OAuth, caso contrário `null` ("Connect GitHub first").
+
+### Vínculo do `setRepo` — o guarda por empresa
+
+O repositório escolhido é registrado em `workspace.settings.github.repo` (e `defaultBranch`). Esse vínculo é verificado depois, na hora do commit, para que um agente jamais consiga dar push em um repositório que o token desta empresa não deveria alcançar. O vínculo **falha** se o token vinculado não conseguir `GET /repos/owner/repo`.
+
+### `refreshGitStatus` — reconciliando a árvore de trabalho
+
+`file.gitStatus` nunca é preenchido pelo watcher; `refreshGitStatus()` executa o **real** `git status --porcelain -z --untracked-files=all` e reconcilia a tabela `file` para que os módulos GitHub + Code mostrem as mudanças reais.
+
+- `-z` → caminhos **crus** separados por NUL (renames/copies consomem um campo extra de caminho antigo; nomes não-ASCII permanecem intactos).
+- Cada entrada mapeia para um código de uma letra: `U` (não rastreado `?`), `D` (deletado), `A` (adicionado), senão `M` (modificado).
+- Caminhos `.git/` e `node_modules/` são ignorados.
+- Arquivos que não estão mais alterados têm seu `gitStatus` limpo de volta para `""`.
+- Um lock em memória por workspace (Set `refreshing`) evita que duas renderizações concorrentes disputem a reconciliação e insiram linhas duplicadas.
+
+### Commit GitHub vs Export Clean Source
+
+- **Commit GitHub** = histórico git local honesto do *workspace inteiro*, com push para o `origin` *vinculado*. A camada do plano de controle (`.claude/`, diretórios de planejamento) também entra no commit (faz parte do seu repositório privado).
+- **Export Clean Source** = uma *árvore limpa* — apenas arquivos que passam por `isCleanProductPath()` — com force-push para um repositório *separado*. Este é o caminho para publicar o produto entregável sem expor as entranhas da Constella.
+
+`isCleanProductPath(rel)` rejeita qualquer caminho cujo diretório de topo esteja em `DENY_TOP` (`.claude`, `DOCS`, `PO`, `Reports`, `specs`, `issues`, `mock`, `uploads`, `archives`, `.testdev`, `node_modules`, `.git`, `.next`, `dist`, `build`, `out`, `coverage`, `.cache`, `.turbo`, `vendor`), qualquer coisa sob `.constella`, e qualquer arquivo `SENSITIVE` (`.env*`, chaves privadas, `*.pem/.key/.p12/...`, JSON de credenciais, dumps/db/logs) — **exceto** templates de env inofensivos que casam com `ALLOW_ENV` (`.env.example|.sample|.template|.dist`).
+
+### Varredura de segredos — a comporta compartilhada
+
+Ambas as rotas chamam `scanForSecrets(cwd)` de `git-scan.ts`. Ela varre os arquivos que *seriam* commitados (o conjunto de mudanças da árvore de trabalho; arquivos no gitignore já estão excluídos pelo `git status`).
+
+- **Arquivos que nunca podem ser commitados** por nome: `.env*`, `id_rsa*`, `*.pem/.key/.p12/.pfx/.keystore/.jks/.ppk/.asc`, `credentials.json`, `service-account*.json`, `*.sql/.dump/.bak/.sqlite/.db`, `*.local`, `npm-debug.log` — exceto templates `ALLOW_FILE`.
+- **Padrões de conteúdo de alta confiança**: chave de acesso AWS, token do GitHub, chave OpenAI/Anthropic, chave de API Google, token Slack, bloco de chave privada, JWT, URL de DB com credenciais, token de bot do Telegram, e um padrão genérico de segredo hardcoded.
+- O padrão genérico é suprimido para **placeholders** óbvios (`your_`, `xxx`, `<...>`, `change_me`, `example`, `placeholder`, `***`, `dummy`, `todo`, `redacted`, `...`).
+- As ocorrências são **redatadas** no preview (`primeiros4•••últimos2`).
+- Arquivos acima de 2 MB e arquivos binários (contendo `\0`) são ignorados; a varredura limita-se a 3000 arquivos / 300 ocorrências.
+
+---
+
+## 5. Tabelas 🌌
+
+### `vault` (ref relevante)
+
+| Coluna | Valor para o GitHub |
+|--------|---------------------|
+| `ref` | `github_pat` |
+| `ciphertext` | texto cifrado AES-GCM do PAT |
+| `iv` | IV por segredo |
+
+### `workspace.settings.github` (JSON)
+
+| Campo | Significado |
+|-------|-------------|
+| `login` | nome de usuário GitHub da conta conectada |
+| `repo` | `owner/repo` vinculado (o vínculo por empresa) |
+| `defaultBranch` | branch padrão do repositório (vinda da API) |
+
+### `file.gitStatus`
+
+| Código | Significado |
+|--------|-------------|
+| `""` | sem mudança |
+| `M` | modificado |
+| `A` | adicionado / novo preparado |
+| `U` | não rastreado |
+| `D` | deletado |
+
+### `deploy_run.lastExport` (definido por `exportCleanSource`)
+
+| Campo | Significado |
+|-------|-------------|
+| `ok` | exportação bem-sucedida |
+| `sha` | SHA curto do commit da árvore limpa |
+| `copied` | número de arquivos limpos enviados |
+| `repo` / `branch` | alvo da exportação |
+| `at` | timestamp |
+
+### `PushResult` (retorno de `commitPush`)
+
+| Campo | Significado |
+|-------|-------------|
+| `ok` | um commit real aconteceu |
+| `committed` | commit local criado |
+| `sha` | sha curto do HEAD |
+| `pushed` | alcançou o remoto |
+| `prUrl` | URL do PR (somente na rota delegada) |
+| `nothing` | árvore de trabalho não tinha nada para commitar |
+| `blocked` | um portão de segurança parou o commit |
+| `secrets` | ocorrências da varredura de segredos quando bloqueado |
+
+---
+
+## 6. Passo a passo 🛰️
+
+### Commit do workspace para o repositório vinculado
+
+1. **Conecte** um PAT (`connectGitHub`) ou faça login com OAuth do GitHub (escopo `repo`).
+2. **Vincule** um repositório com `setRepo("owner/repo")` (ou `createRepo`).
+3. (Opcional) **Atualize** o status — `refreshGitStatus()` preenche a lista de mudanças; `draftCommitMessage()` propõe um assunto Conventional-Commit a partir das contagens de `A`/`M`/`D`.
+4. **Varra** sob demanda com `scanWorkspace()` (sem commit) para pré-visualizar ocorrências.
+5. **Commit + push** com `commitPush({ repo, branch, message })`. Passe `delegated: true` para também abrir um PR via `gh pr create --fill`. Passe `force: true` para contornar o portão de varredura de segredos *após revisão*.
+
+### Exportar apenas o produto
+
+1. Execute **Prepare Deploy** (ou `previewCleanExport()`) para ver a árvore limpa + uma varredura pré-exportação.
+2. Chame `exportCleanSource({ repo: "myorg/my-app-public" })` — ou `/export-source myorg/my-app-public` no chat.
+3. A árvore limpa é construída em um diretório temporário, varrida em busca de segredos, commitada e enviada com **force-push** para o repositório separado. `deploy_run.lastExport` registra o resultado.
+
+---
+
+## 7. Exemplos 🌠
+
+### Comandos de barra
+
+```
+/github                      # atualiza o status do git, reporta a contagem de arquivos alterados (Werner)
+/export-source myorg/app-pub # exporta o produto limpo para um repositório separado
+/prepare-deploy              # executa o pipeline completo de preparo para produção
+```
+
+`/github` (tratado em `src/server/commands.ts`) chama `refreshGitStatus()` e posta a contagem de arquivos alterados pelo Werner (DevOps).
+
+### Mensagens do portão de commit (strings reais)
+
+```
+Blocked: 2 potential secret(s)/sensitive file(s) in the change set. Resolve them or review before committing.
+Origin (acme/app) doesn't match this company's configured repo (acme/app-2). Re-select the repo before committing.
+committed locally — connect a GitHub PAT to push
+```
+
+### URL de push autenticada
+
+`commitPush` reescreve o origin HTTPS para injetar o PAT apenas no momento do push:
+
+```
+https://github.com/owner/repo.git
+→ https://x-access-token:<PAT>@github.com/owner/repo.git   (usada no `git push`, redatada em todo o resto)
+```
+
+---
+
+## 8. Diagramas Mermaid 🪐
+
+### Commit GitHub vs Export Clean Source
+
+```mermaid
+flowchart TD
+  subgraph WS["Workspace em disco (orgRoot)"]
+    A[".claude / DOCS / PO / specs / issues / mock"]
+    B["código do produto + README + .env.example"]
+  end
+
+  WS --> P{Qual rota?}
+
+  P -->|"Commit GitHub<br/>commitPush()"| G1["Portão 1: PAT para esta empresa?"]
+  G1 --> G2["Portão 2: origin == repo vinculado?"]
+  G2 --> G3["Portão 3: scanForSecrets()"]
+  G3 -->|"ocorrências"| BLK1["BLOQUEADO → Inbox + notifyOps"]
+  G3 -->|"limpo (ou force)"| C1["git add -A → commit → push HEAD:branch"]
+  C1 --> C2["delegated? gh pr create --fill"]
+  C1 --> ORIGIN["repo origin vinculado<br/>(workspace inteiro)"]
+
+  P -->|"Export Clean Source<br/>exportCleanSource()"| E1["buildCleanTree → dir temp<br/>(filtro isCleanProductPath)"]
+  E1 --> E2["git init + add -A"]
+  E2 --> E3["scanForSecrets() — portão final"]
+  E3 -->|"ocorrências"| BLK2["BLOQUEADO → Inbox + notifyOps"]
+  E3 -->|"limpo"| E4["commit → push -f HEAD:branch"]
+  E4 --> SEP["repositório separado<br/>(somente produto)"]
+```
+
+### Resolução de token
+
+```mermaid
+flowchart LR
+  T["ghToken(ws, user)"] --> V{"vault github_pat?"}
+  V -->|sim| PAT["usa o PAT do cofre"]
+  V -->|não| OA{"conta OAuth do GitHub?"}
+  OA -->|sim| TOK["usa account.accessToken<br/>(precisa do escopo 'repo' para push)"]
+  OA -->|não| NULL["null → 'Connect GitHub first'"]
+```
+
+---
+
+## 9. Estados possíveis 🕳️
+
+### Portões de commit (em ordem)
+
+| Portão | Gatilho | Resultado |
+|--------|---------|-----------|
+| **1. PAT configurado** | sem `github_pat` para este workspace | `blocked` — "GitHub isn't configured for this company" |
+| **2. Repo vinculado + origin casa** | sem `settings.github.repo` / sem origin, ou divergência | `blocked` — re-selecione o repositório |
+| **3. Varredura de segredos** | qualquer ocorrência (e `force` não definido) | `blocked`, `secrets[]`, card no Inbox + notificação aos operadores |
+
+Após os portões passarem: `committed` → opcional `pushed` → opcional `prUrl`. Uma árvore de trabalho sem nada a commitar retorna `nothing: true`.
+
+### Rejeição de push
+
+Um push rejeitado / non-fast-forward (`rejected | non-fast-forward | fetch first | merge conflict | failed to push`) **não** é descartado silenciosamente — ele gera um card `block` no Inbox ("Push rejected — \<repo\>") para que o operador faça pull + resolva.
+
+### Estados da exportação
+
+| Estado | Causa |
+|--------|-------|
+| `ok: false, error: "Use the form owner/repo."` | alvo malformado |
+| `ok: false, error: "...token can't access it."` | `GET /repos/...` retornou 404 |
+| `blocked: true, secrets[]` | a varredura final encontrou um segredo |
+| `ok: true, pushed: true, sha, copied` | force-push limpo concluído |
+| `error: "Nothing to export yet..."` | `buildCleanTree` copiou 0 arquivos |
+
+---
+
+## 10. Integrações relacionadas 🌌
+
+- **Vault** — armazena `github_pat` criptografado; veja [SECURITY](./SECURITY.md).
+- **Inbox** — recebe cards `block` para ocorrências de segredos + rejeições de push; veja [INBOX](./INBOX.md).
+- **Prepare Deploy** — o pipeline que faz build, valida e gate da exportação limpa; veja [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) e [DEPLOY](./DEPLOY.md).
+- **Agentes** — Werner (DevOps) é o agente padrão de deploy/commit; veja [AGENTS](./AGENTS.md).
+- **Comandos de chat** — `/github`, `/export-source`, `/prepare-deploy`; veja [CHAT_COMMANDS](./CHAT_COMMANDS.md).
+- **Onboarding** — import/conexão inicial do GitHub; veja [ONBOARDING](./ONBOARDING.md).
+
+---
+
+## 11. Segurança 🕳️
+
+- **Token nunca registrado.** `redact()` remove o PAT de cada stdout/stderr capturado antes que chegue à UI, ao Inbox ou às notificações. A URL de push autenticada (`x-access-token:<PAT>@...`) só é construída em memória para a chamada do `git push`.
+- **Isolamento por empresa.** O PAT fica no cofre por `workspaceId`; o vínculo é verificado contra o token; o Portão 2 do commit garante que `origin` seja igual ao repositório vinculado — você não consegue dar push no repositório de outra organização.
+- **Varredura de segredos obrigatória.** O Portão 3 do commit e o portão final da exportação ambos executam `scanForSecrets`. A flag `force` só contorna a varredura do *commit* e destina-se a uso *pós-revisão*.
+- **A exportação limpa remove as entranhas.** `isCleanProductPath` remove toda a camada de controle da Constella e todos os arquivos sensíveis antes que algo seja enviado a um repositório separado.
+- **`.gitignore` seguro.** `ensureRepo` garante que deps/build/segredos nunca sejam preparados por `git add -A`.
+
+Veja [SECURITY](./SECURITY.md) para o modelo completo de cofre + scrub.
+
+---
+
+## 12. Solução de problemas 🛰️
+
+| Sintoma | Causa provável | Correção |
+|---------|----------------|----------|
+| "Connect GitHub first." | sem PAT e sem token OAuth | execute `connectGitHub` com um PAT de escopo `repo` |
+| "Invalid token (401). ...needs the 'repo' scope." | PAT sem escopo `repo` ou errado | regenere com escopo `repo` |
+| "Repo not found, or this company's token can't access it." | `GET /repos/owner/repo` 404 | confira o nome do repositório + se a conta do token tem acesso |
+| "Origin (X) doesn't match this company's configured repo (Y)." | origin e vínculo divergiram | chame `setRepo` para re-vincular |
+| Commit `blocked` com `secrets[]` | a varredura achou um segredo/arquivo sensível | remova-o (ou mova para `.env`), ou use `force` após revisão |
+| "Push rejected — \<repo\>" no Inbox | o remoto avançou / conflito | faça pull + resolva, então push novamente |
+| O módulo GitHub mostra "No changes" mas os arquivos mudaram | `file.gitStatus` não reconciliado | dispare `refreshGitStatus()` (botão Refresh / `/github`) |
+| "committed locally — connect a GitHub PAT to push" | commit feito, sem credenciais para push | conecte um PAT |
+| "Nothing to export yet..." | nenhum arquivo de produto limpo encontrado | adicione código do produto fora dos diretórios internos |
+
+---
+
+## 13. Links relacionados 🌠
+
+- [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) · [DEPLOY](./DEPLOY.md) · [PUBLISHING](./PUBLISHING.md)
+- [SECURITY](./SECURITY.md) · [INBOX](./INBOX.md) · [CHAT_COMMANDS](./CHAT_COMMANDS.md)
+- [AGENTS](./AGENTS.md) · [ONBOARDING](./ONBOARDING.md) · [CONFIGURATION](./CONFIGURATION.md)
+- [✦ Voltar ao Índice da documentação](./README.md)

package/docs/pt/GOALS_SPECS_ISSUES.md

@@ -0,0 +1,303 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/GOALS_SPECS_ISSUES.md) · [✦ Constella](../../README.pt-BR.md)
+
+# Metas, Specs, Issues, Planos — A Constelação do Trabalho 🌌🪐
+
+![](../assets/divider-orbit.svg)
+
+O modelo de dados e as máquinas de estado por trás de cada unidade de trabalho. Uma **Meta (Goal)** é uma órbita; as **Specs** são suas cartas estelares; as **Issues** são as manobras; as **Tasks** são as queimas que o motor realmente dispara; o **Plano (Plan)** é o portão de lançamento que o operador abre. Esta página documenta as tabelas reais, colunas, enums de status e as transições entre eles.
+
+## Descrição curta
+
+A Constella transforma um briefing em um pipeline de entrega estruturado e consciente de estado: `Goal → Spec → Issue → Plan → Execution → Review → Test → Done`. O agente CEO (Ada) rascunha specs e issues; o operador aprova o plano; as issues aprovadas são *materializadas* em tasks executáveis que o runner pega. Cancelar ou arquivar uma meta cascateia para seus filhos, de modo que nada já encerrado continue aparecendo como pendente.
+
+## Quando usar
+
+- Você quer entender **o que é cada entidade**, quais colunas ela tem e como as linhas se relacionam.
+- Você precisa dos **enums de status** exatos e das **colunas do kanban** de `goal`, `spec`, `issue`, `task` e `plan`.
+- Você está depurando por que uma meta cancelada ainda mostra trabalho pendente, ou por que um plano reaprovado criou apenas *algumas* tasks.
+- Você quer saber o que é o **SUPER-SPEC** e quando ele é escrito.
+
+## Como funciona 🛰️
+
+Cada entidade é uma linha no banco de dados SQLite (`src/db/schema.ts`), com escopo por `workspaceId` (um workspace por organização). O diretório em disco é a fonte da verdade para os artefatos legíveis (`specs/*.md`, `issues/*.md`, `specs/SUPER-SPEC.md`); as tabelas os indexam e carregam o estado de ciclo de vida.
+
+O pipeline é conduzido por três módulos:
+
+| Módulo | Arquivo | Responsabilidade |
+| --- | --- | --- |
+| Planner | `src/server/planner-core.ts` | `generatePlanFor` / `runPlanJob` / `planFromConversationFor` — o CEO rascunha a Goal + specs + issues |
+| Plan ops | `src/server/plan-ops.ts` | `approvePlanFor` / `requestPlanChangesFor` / `setAuto247For` — o portão de aprovação |
+| Work ops | `src/server/work-ops.ts` | `cancelGoalFor` / `archiveGoalFor` + helpers de cascata — ciclo de vida da meta |
+| Materialize | `src/server/materialize.ts` | `materializeTasks` — converte issues aprovadas em linhas `task` executáveis |
+
+Os quatro são cores `server-only` chaveados por um `(orgId, workspaceId)` explícito, então podem ser chamados a partir de uma server action de sessão **ou** dos canais sem sessão (o controle remoto via Telegram, a API pública).
+
+## Fluxo principal 🌠
+
+```
+briefing / DM "@ada construa X"
+   └─ generatePlanFor → runPlanJob (Ada, destacado, canal "planner")
+        ├─ (primeiro plano, projeto existente) analyzeExistingProject → specs/SUPER-SPEC.md
+        ├─ insere goal (a partir da spec PRINCIPAL/primeira)
+        ├─ insere linhas spec  + escreve specs/SPEC-NN.md
+        ├─ insere linhas issue + escreve issues/<key>.md   (col=todo, approved=false)
+        └─ envia item ao Inbox "Aprovar plano"
+   └─ operador aprova → approvePlanFor
+        ├─ plan.approved=true, stage=6
+        ├─ issue.approved=true, spec.approved=true (specs ativas)
+        ├─ materializeTasks → uma task por issue (idempotente)
+        └─ organiza o backlog do PO
+   └─ Run 24/7 (plan.auto247=true) → runner pega tasks → Review → Test → Done
+```
+
+## Conceitos-chave 🕳️
+
+- **A Goal nasce da spec PRINCIPAL.** O `runPlanJob` trata a primeira spec da saída do modelo como a spec principal; `goal.specId` aponta para ela, e toda spec/issue rascunhada recebe o id da meta (`goalId`).
+- **O ciclo de vida é independente da coluna de fluxo.** `spec.status` / `issue.status` (`active | cancelled | archived`) são *separados* de `issue.col` (a raia do kanban). Cancelar uma meta vira o `status` dos filhos, nunca a `col`, então o histórico do board sobrevive.
+- **`approved` é um booleano, não um status.** Uma spec ou issue pode estar `approved=true` ainda que `active`. O portão de aprovação fica na linha singleton `plan`.
+- **Tasks são a única coisa que o runner executa.** Issues são planos; tasks são trabalho. `materializeTasks` faz a ponte e é idempotente via `task.issueId`.
+- **O disco é a fonte da verdade.** As keys de spec/issue são renumeradas para *continuar* a partir das existentes, de modo que um segundo plano de "New work" nunca sobrescreva `specs/SPEC-01.md` em disco.
+
+## Tabelas 🪐
+
+### `goal` — uma unidade de trabalho (uma órbita)
+
+| Coluna | Tipo | Notas |
+| --- | --- | --- |
+| `id` | text PK | |
+| `workspaceId` | text FK → workspace | indexado `goal_ws_idx` |
+| `title` / `description` | text | |
+| `ownerId` | text FK → agent | normalmente Ada (a CEO) |
+| `progress` | int | rollup em cache 0–100, recomputado pelo runner |
+| `parentId` | text | meta pai opcional |
+| `status` | enum | `active \| cancelled \| archived \| done` (padrão `active`) |
+| `specId` | text | a spec **principal** da qual esta meta nasceu |
+| `archivePath` | text | caminho do ZIP quando arquivada |
+| `createdAt` / `updatedAt` / `doneAt` / `cancelledAt` / `archivedAt` / `reopenedAt` | timestamp | marcadores de ciclo de vida (nuláveis) |
+
+A proveniência é rastreada em `goal_file` (PK `goalId + path`, `op = created | edit`), para que um ZIP de arquivamento inclua *apenas* os arquivos que esta meta produziu.
+
+### `spec` — uma carta estelar
+
+| Coluna | Tipo | Notas |
+| --- | --- | --- |
+| `id` | text PK | |
+| `workspaceId` | text FK | |
+| `key` | text | ex.: `SPEC-01` (renumerada para continuar a partir das existentes) |
+| `title` / `summary` / `body` | text | |
+| `authorId` | text FK → agent | o papel que o CEO designou como autor |
+| `approved` | bool | padrão `false` |
+| `goalId` | text | meta pai |
+| `status` | enum | `active \| cancelled \| archived` (padrão `active`) |
+| `createdAt` / `updatedAt` | timestamp | |
+
+### `issue` — uma manobra
+
+| Coluna | Tipo | Notas |
+| --- | --- | --- |
+| `id` | text PK | |
+| `workspaceId` | text FK | |
+| `specId` | text FK → spec | `onDelete: cascade` |
+| `goalId` | text | meta pai |
+| `key` | text | sequencial, continuando a partir das issues existentes |
+| `title` | text | |
+| `prio` | enum | `low \| med \| high` (padrão `med`) |
+| `col` | enum | `todo \| doing \| blocked \| review \| done` (raia do kanban, padrão `todo`) |
+| `moscow` | enum | `Must \| Should \| Could \| Won't` (derivado de `prio`) |
+| `points` | int | story points (derivado: high→8, med→5, low→3) |
+| `assigneeId` | text FK → agent | o papel que o CEO designou |
+| `approved` | bool | padrão `false` |
+| `status` | enum | `active \| cancelled \| archived` (padrão `active`) |
+| `createdAt` / `updatedAt` | timestamp | |
+
+### `task` — uma queima de motor (a unidade executável)
+
+| Coluna | Tipo | Notas |
+| --- | --- | --- |
+| `id` | text PK | |
+| `workspaceId` | text FK | |
+| `key` / `title` / `description` | text | |
+| `col` | enum | `triage \| todo \| doing \| blocked \| review \| done` (padrão `triage`) |
+| `prio` | enum | `low \| med \| high` |
+| `assigneeId` | text FK → agent | |
+| `goalId` | text FK → goal | |
+| `issueId` | text FK → issue | a issue da qual foi materializada (chave de idempotência) |
+| `createdBy` | enum | `operator \| agent` |
+| `createdAt` / `updatedAt` | timestamp | |
+
+Os sub-passos vivem em `task_step` (`text`, `done`, `active`, `ord`) — semeados a partir do `## Checklist` da issue e base do progresso ao vivo.
+
+### `plan` — o portão de lançamento (uma linha por workspace)
+
+| Coluna | Tipo | Notas |
+| --- | --- | --- |
+| `workspaceId` | text **PK** | um plano por workspace |
+| `approved` | bool | padrão `false` |
+| `auto247` | bool | chave da execução autônoma 24/7 |
+| `stage` | int | marcador de estágio do pipeline (padrão `4`) |
+| `createdAt` / `updatedAt` | timestamp | |
+
+Note a diferença de cardinalidade: existe exatamente **uma** linha `plan` por workspace (a PK é `workspaceId`), mas **muitas** goals/specs/issues/tasks.
+
+## Diagrama de relacionamento de entidades
+
+```mermaid
+erDiagram
+    WORKSPACE ||--|| PLAN : "tem um (portao)"
+    WORKSPACE ||--o{ GOAL : contem
+    GOAL ||--o{ SPEC : "pai de"
+    GOAL ||--o{ ISSUE : "pai de"
+    GOAL ||--o{ GOAL_FILE : "proveniencia"
+    SPEC ||--o{ ISSUE : "agrupa (delete em cascata)"
+    ISSUE ||--o| TASK : "materializada em"
+    TASK ||--o{ TASK_STEP : "checklist"
+    GOAL ||--o| SPEC : "nasce de (specId)"
+    AGENT ||--o{ GOAL : possui
+    AGENT ||--o{ SPEC : escreve
+    AGENT ||--o{ ISSUE : atribuida
+    AGENT ||--o{ TASK : atribuida
+```
+
+## Transições de status 🌠
+
+### Máquina de estado da Goal
+
+```mermaid
+stateDiagram-v2
+    [*] --> active : runPlanJob insere goal
+    active --> done : todas as issues 100% (auto-conclusao, sticky)
+    active --> cancelled : cancelGoalFor
+    active --> archived : archiveGoalFor (ZIP)
+    cancelled --> active : reopenGoal
+    archived --> active : restoreGoal (re-extrai ZIP)
+    done --> [*]
+```
+
+`progress` e `status` mudam **apenas enquanto active**. Assim que uma meta encerra (`done`/`cancelled`/`archived`), seu `%` fica fixo (sticky) — uma issue posterior bloqueada ou adicionada não pode fazer uma meta "Done" mostrar 62%. A auto-conclusão é compare-and-set: só o primeiro escritor que ainda vê a meta `active` carimba `done` + `doneAt` (`src/server/progress.ts`).
+
+### Ciclo de vida de Spec / Issue (status) — cascateia da meta pai
+
+```mermaid
+stateDiagram-v2
+    [*] --> active
+    active --> cancelled : meta cancelada (setGoalChildrenStatus)
+    active --> archived : meta arquivada
+    cancelled --> active : meta reaberta
+    archived --> active : meta restaurada
+```
+
+### Coluna kanban de Issue / Task (fluxo, independente do status)
+
+```mermaid
+stateDiagram-v2
+    [*] --> triage : padrao da task
+    triage --> todo
+    todo --> doing : runner assume
+    doing --> review : trabalho concluido
+    doing --> blocked : parkGoalTasks / agente travado
+    blocked --> todo : unparkGoalTasks
+    review --> done : aprovacao da QA
+    done --> [*]
+```
+
+> As Issues usam as colunas `todo · doing · blocked · review · done`. As Tasks adicionam uma raia inicial `triage`.
+
+### Portão do Plano
+
+```mermaid
+stateDiagram-v2
+    [*] --> draft : runPlanJob (approved=false, stage=4)
+    draft --> approved : approvePlanFor (approved=true, stage=6)
+    approved --> draft : requestPlanChangesFor (approved=false, auto247=false, stage=1)
+    approved --> running247 : setAuto247For(true)
+    running247 --> approved : setAuto247For(false)
+```
+
+## Passo a passo 🚀
+
+1. **Chega um briefing** — o briefing permanente do workspace (`.claude/BRIEF.md`), uma DM para `@ada`, ou `/new-work` / `/new-goal`.
+2. **`generatePlanFor`** marca Ada como `working` e dispara o `runPlanJob` destacado no servidor node persistente (faz streaming no canal `planner`).
+3. **Análise do primeiro plano** (apenas quando há um projeto existente ainda não analisado): `analyzeExistingProject` lê o projeto arquivo a arquivo e escreve `specs/SUPER-SPEC.md`, então sinaliza `settings.source.analyzed = true`.
+4. **Ada rascunha** um único objeto JSON de `specs[]` + `issues[]`. A primeira spec é a spec **principal**.
+5. **Persiste** — insere a `goal` (título de `opts.goalTitle` / spec principal / objetivo), depois as specs (keys renumeradas para continuar), depois as issues (`col=todo`, `points`/`moscow` derivados de `prio`). Escreve `specs/SPEC-NN.md` e `issues/<key>.md` em disco.
+6. **Inbox + Telegram** — um item de inbox `approval` (`refType=plan`) é enviado; se o Telegram estiver configurado, o plano é enviado ao celular com botões Aprovar / Iniciar execução / Revisar / Rejeitar.
+7. **O operador aprova** (`approvePlanFor`): `plan.approved=true, stage=6`, issues + specs ativas viram `approved=true`, `materializeTasks` cria uma task por issue não materializada, e o backlog do PO (`PO/backlog.md`) é organizado.
+8. **Run 24/7** (`setAuto247For(true)`) — o runner pega tasks `todo`, avança-as por `doing → review → done`, espelhando o progresso de volta nas issues e metas.
+9. **Cancelar / arquivar** quando necessário — `cancelGoalFor` / `archiveGoalFor` param tudo e cascateiam o status dos filhos.
+
+## Exemplos
+
+**Novo trabalho a partir de uma DM** (tratado por `planFromConversationFor` → `generatePlanFor`):
+
+```
+@ada construa um painel de cobrança com Stripe e exportação CSV
+```
+
+**Aprovar via slash command** ([CHAT_COMMANDS](./CHAT_COMMANDS.md)):
+
+```
+/approve          # approvePlanFor: aprova plano/specs/issues + materializa tasks
+/run-247          # setAuto247For(true)
+/reject <motivo>  # requestPlanChangesFor — volta para Ada, estágio recua para 1
+/cancel           # cancelGoalFor — para + estaciona, reabre depois
+/archive          # archiveGoalFor — compacta o source da meta + manifesto
+```
+
+**Materialização Issue → task** (`materializeTasks`, idempotente): reaprovar após um replanejamento cria tasks **apenas** para issues sem `task.issueId`, então o trabalho existente nunca é duplicado.
+
+## Estados possíveis
+
+| Entidade | Campo | Valores |
+| --- | --- | --- |
+| goal | `status` | `active`, `cancelled`, `archived`, `done` |
+| spec | `status` | `active`, `cancelled`, `archived` |
+| spec | `approved` | `true`, `false` |
+| issue | `status` | `active`, `cancelled`, `archived` |
+| issue | `col` | `todo`, `doing`, `blocked`, `review`, `done` |
+| issue | `approved` | `true`, `false` |
+| issue | `moscow` | `Must`, `Should`, `Could`, `Won't` |
+| task | `col` | `triage`, `todo`, `doing`, `blocked`, `review`, `done` |
+| plan | `approved` / `auto247` | `true`, `false` |
+
+## O SUPER-SPEC 🌌
+
+Quando o onboarding importa um projeto existente (um repositório GitHub, um diretório local copiado, ou um `mock/` anexado), a **primeira** execução de plano não rascunha às cegas. `analyzeExistingProject` (`src/server/analyze.ts`) roda uma passagem real de agente com o workspace como `cwd`, lê docs → manifestos → código arquivo a arquivo, e escreve `specs/SUPER-SPEC.md` com seções como *Visão geral & propósito, Arquitetura & camadas, Stack & dependências, Mapa de diretórios / módulos, Frontend, Backend, Modelo de dados & banco, Auth & segurança, Integrações, Regras de negócio & fluxos-chave, O que é mock/stub vs real, Lacunas para tornar production-real*.
+
+O plano então lê o SUPER-SPEC por inteiro e **estende** o sistema existente — nunca cria um segundo protótipo separado. A análise roda uma vez por projeto (`settings.source.analyzed`).
+
+## Integrações relacionadas
+
+- **Grooming do PO** — ao aprovar, cada issue é copiada para `backlog_item` (MoSCoW + points) e `PO/backlog.md` é reescrito. Veja [PO_AGENT](./PO_AGENT.md).
+- **Inbox** — a decisão de aprovar o plano aparece como item acionável (`refType=plan`). Veja [INBOX](./INBOX.md).
+- **Log de decisões** — aprovar/cancelar/arquivar acrescentam cada um uma linha `decision`. Veja [TEAM_ROOM](./TEAM_ROOM.md).
+- **Remoto via Telegram** — os mesmos cores sem sessão alimentam `/approve`, `/cancel`, etc. pelo celular. Veja [TELEGRAM](./TELEGRAM.md).
+- **Runner / execução** — as tasks fluem por review e teste. Veja [WORKFLOW](./WORKFLOW.md), [TEST_DEV](./TEST_DEV.md).
+
+## Segurança 🔒
+
+- Todos os cores de ciclo de vida são `server-only` e chaveados por um `(orgId, workspaceId)` explícito — **nunca** expostos como endpoints RPC não autenticados. Todo chamador (server action de sessão, allowlist do Telegram, PAT da API pública) já deve estar autorizado para o workspace.
+- `ownGoal(wsId, goalId)` verifica que a meta pertence ao workspace antes de qualquer mutação.
+- A extração de ZIP em arquivar/restaurar normaliza caminhos e recusa escrever fora da raiz do workspace (`abs !== root && !abs.startsWith(root + sep)`), parte da FS jail. Veja [SECURITY](./SECURITY.md).
+
+## Solução de problemas 🕳️
+
+| Sintoma | Causa | Solução |
+| --- | --- | --- |
+| Meta cancelada ainda mostra issues pendentes | `status` do filho não cascateado | `cancelGoalFor` chama `setGoalChildrenStatus`; reabra + cancele de novo se uma linha foi editada direto |
+| Reaprovação não criou novas tasks | todas as issues já têm `task.issueId` | esperado — `materializeTasks` é idempotente; só novas issues materializam |
+| Meta "Done" travada abaixo de 100% | progresso em cache fixo (sticky) | por design, uma vez encerrada; reabra para recomputar enquanto `active` |
+| Plano não aprova | sem linha `plan` / specs não `active` | `approvePlanFor` só aprova `spec.status = active`; garanta que existe um plano |
+| Ada travada em "working", sem plano | um job anterior morreu antes do `finally` | `generatePlanFor` se auto-recupera checando o stream de eventos `planner` ao vivo |
+| Segundo "New work" sobrescreveu SPEC-01 | não deveria ocorrer | as keys são renumeradas para continuar a partir das specs/issues existentes em disco |
+
+## Links relacionados
+
+- [WORKFLOW](./WORKFLOW.md) — o ritual de execução ponta a ponta
+- [PO_AGENT](./PO_AGENT.md) — grooming de backlog, story points, MoSCoW
+- [AGENTS](./AGENTS.md) — a tripulação (Ada é a CEO/planner)
+- [INBOX](./INBOX.md) — aprovações e decisões do operador
+- [CHAT_COMMANDS](./CHAT_COMMANDS.md) — `/approve`, `/cancel`, `/archive`, `/new-work`
+- [DM](./DM.md) — iniciar novo trabalho a partir de uma mensagem direta
+- [TEAM_ROOM](./TEAM_ROOM.md) — onde a CEO narra o plano
+- [ARCHITECTURE](./ARCHITECTURE.md) — a camada de dados e o motor de sync
+- [TELEGRAM](./TELEGRAM.md) — controle remoto dos mesmos cores