constella 0.1.0

package/docs/en/WORKFLOW.md

@@ -0,0 +1,321 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/WORKFLOW.md) · [✦ Constella](../../README.md)
+
+# Workflow — Goal to Done 🌠
+
+![](../assets/divider-orbit.svg)
+
+The full orbit a unit of work travels in Constella: from a brief that the CEO turns into a plan, through the operator's approval gate, into a real `claude`/`codex` execution loop, past review and test gates, all the way to a delivered Goal. Nothing is faked — every run spends real tokens, books real cost, and edits real files.
+
+---
+
+## 1. When to use 🪐
+
+Read this doc when you want to understand:
+
+- How a typed brief becomes specs, issues and tasks.
+- What the **approval gate** is and why agents never touch code before it.
+- How **Run 24/7** (`plan.auto247`) drives the autonomous loop.
+- What the **review / test / boot gates** do to a finished task.
+- How progress rolls up from checklist items → issue → Goal, and how a Goal auto-completes.
+- How to cancel, archive, reopen or restore a Goal mid-flight.
+
+For the surrounding pieces see [GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md), [AGENTS](./AGENTS.md), [PO_AGENT](./PO_AGENT.md) and [TEST_DEV](./TEST_DEV.md).
+
+---
+
+## 2. How it works 🛰️
+
+The lifecycle has **eight stages**:
+
+```
+Goal → Spec → Issue → Plan → Execution → Review → Test → Done
+```
+
+Two hard gates split it in half:
+
+1. **The approval gate.** Planning produces drafts only. No code runs until the operator approves the plan (`plan.approved = true`). The runner refuses to dispatch any task otherwise — see `runOneTaskBody` in `src/server/runner.ts`:
+
+   > ```ts
+   > const pl = await db.query.plan.findFirst({ where: eq(plan.workspaceId, ws.id) });
+   > if (!pl || !pl.approved) return false; // no plan or unapproved → never auto-run code
+   > ```
+
+2. **The 24/7 gate.** Even after approval, the *autonomous* loop (cron `auto: true`) runs only while **Run 24/7** is on (`plan.auto247 = true`). A manual one-shot run (`auto: false`) only needs approval.
+
+The whole pipeline is driven by four source modules:
+
+| Module | Role |
+| --- | --- |
+| `src/server/planner-core.ts` | Session-less CEO planning core (`generatePlanFor`, `runPlanJob`, `planFromConversationFor`, `startNewWorkFor`). |
+| `src/server/plan-ops.ts` | Approve / un-approve / 24/7 toggle (`approvePlanFor`, `requestPlanChangesFor`, `setAuto247For`). |
+| `src/server/runner.ts` | The real autonomous loop (`tickWorkspace`, `runOneTask`, gates, progress). |
+| `src/server/work-ops.ts` | Goal lifecycle (`cancelGoalFor`, `archiveGoalFor`, park/unpark tasks). |
+
+---
+
+## 3. Main flow 🚀
+
+### Stage 1–4 · Plan (Goal → Spec → Issue → Plan)
+
+A planning run is kicked off through `generatePlanFor(orgId, workspace, opts)`:
+
+1. It picks the CEO agent (`@ada`, by handle, falling back to a CEO/chief-exec role).
+2. It guards against a second concurrent run by inspecting the live **`planner`** event stream (not Ada's flag, which can stick on `working`).
+3. It sets Ada to `status = "working"`, emits a `thinking` event, and detaches the heavy work into `runPlanJob` so it survives the HTTP response.
+
+Inside `runPlanJob`:
+
+- **First-plan analysis.** If an existing project is present (imported repo, copied local dir, or attached `mock/`) and it has not been analyzed yet (`settings.source.analyzed` is unset), `analyzeExistingProject` reads it file-by-file into `specs/SUPER-SPEC.md` first. Runs once per project.
+- **Stack playbook.** The seeded native skills relevant to the chosen stack across Frontend/Backend/CyberSec/CTO are passed to Ada so she plans grounded in the real technologies (see [SKILLS](./SKILLS.md)).
+- Ada runs a real `claude`/`codex` session (timeout `300_000` ms), writes `ARCHITECTURE.md` and `RITUALS.md` (first plan only), and returns **one JSON object**: `{"specs":[…],"issues":[…]}`.
+- Constella persists the result: a **Goal** (born from the first/main spec), each **Spec** (`SPEC-NN`, numbered continuing from existing specs), each **Issue** (sequential keys, `col = "todo"`), and writes the artifacts to disk under `specs/` and `issues/` (the directory is the source of truth).
+- Deterministic PO seeding maps priority → story points + MoSCoW (`high → Must / 8`, `med → Should / 5`, `low → Could / 3`).
+- The first plan sets `plan.stage = 4, approved = false` (the approval gate). **New work** does NOT un-approve the running plan.
+- The plan is surfaced: a room message, an Inbox **approval** item, an operator notification, and (if Telegram is configured) inline **Approve / Start execution / Review / Reject** buttons.
+
+> New work is born from a DM to `@ada` ("build X"), the Planner's **New work** button (`startNewWorkFor`), or a chat conversation (`planFromConversationFor`). See [DM](./DM.md) and [CHAT_COMMANDS](./CHAT_COMMANDS.md).
+
+### Stage 4 → 5 · Approve (the gate)
+
+`approvePlanFor(orgId, ws)` flips the gate and materializes work:
+
+1. `plan.approved = true, stage = 6`; every `issue.approved = true`; every active `spec.approved = true`.
+2. `materializeTasks` converts each issue into an executable **task** row (`col = "todo"`). Idempotent — issues that already have a task are skipped, so a re-approve after a re-plan only materializes the new ones. A **`DOCS-1`** task (`@barbara`) is always ensured last so the build is always documented.
+3. The PO backlog doc `PO/backlog.md` is groomed from the approved issues, and a real PO grooming pass (`groomBacklogFor`, Donald) is fired best-effort to size story points + MoSCoW and flag duplicates/gaps.
+4. Ada narrates in the room; the decision is logged; the Inbox approval item is resolved.
+
+### Stage 5 · Execution (the real loop)
+
+The worker (`bin/worker.mjs`) POSTs `POST /api/cron/tick` (guarded by `x-worker-secret`) roughly every 60s. That calls `tickAll({ execute: true, auto: true })` → `tickWorkspace` → `runOneTask` → `runOneTaskBody` for each active workspace.
+
+`runOneTaskBody` runs **exactly one** pending task per tick:
+
+1. **Gates:** plan approved? (else return) · `auto && !auto247`? (else return) · goal still active?
+2. **Reclaim orphans:** any `doing` task not genuinely in-flight (from a crash/restart) is re-queued to `todo`.
+3. **Pick a task:** an in-progress `doing` task (unless its assignee is already executing elsewhere), else **atomically claim** the next `todo` (compare-and-set on `col`) so two ticks can never grab the same one.
+4. **Budget gate:** if the assignee hit its `dailyCapUsd`, push a budget Inbox item and skip.
+5. **Spawn:** flip the linked issue to `doing`, assemble the context bundle (`assembleAgentPrompt`), and run the real CLI (`runAgentStream`, timeout `240_000` ms). The task's checklist is ticked **live** as the agent streams its reply.
+6. **Book real cost** into `costEntry` (only if the run produced usage).
+
+A concurrency cap (`runningWorkspaces`, default **1** per workspace, override `CONSTELLA_MAX_CONCURRENT_AGENTS` or `settings.agents.maxConcurrent`) prevents the browser tick and the worker tick from launching two CLIs at once.
+
+### Stage 6 · Review · Stage 7 · Test (the completion gates)
+
+On a successful run, before a task is allowed to reach `done`, it passes through gates (in order). Any hard failure holds the task at **`review`** with an Inbox item — it does not silently pass:
+
+| Gate | Source | Condition | On failure |
+| --- | --- | --- | --- |
+| **Boot gate** | `ensureBootable` | task touched a code path | held at `review` + `block` Inbox item ("broke the dev server") |
+| **Test Dev gate** | `runTestDev` | the project dev server is up (`serverUrl`) | held at `review` + `validation` Inbox item |
+| **Review gate** | `reviewTaskChange` | `settings.agents.autoReview` on (default) & code touched | held at `review` + `review` Inbox item (high-sev findings) |
+
+The review gate uses an **independent reviewer** — never the task's own author. It prefers `@whitfield` (CyberSec), then any QA/security role. KB-block proposals (`[[KB-BLOCK …]]`), learnings (`[[REMEMBER …]]`) and research requests (`[[RESEARCH: …]]`) the agent emitted are extracted and processed here too.
+
+### Stage 8 · Done
+
+If all gates pass, `COLUMN_NEXT` advances the task `todo → doing → done`, mirrors it onto the issue, ticks every `taskStep` done, and recomputes goal progress. When a Goal reaches 100%, `recomputeGoalProgress`/`goalRollups` flips it to `status = "done"`, and `fileCeoSummaryIfComplete` files a single **`ceo-summary`** report, notifies the operator, logs the decision, and captures the delivery as `history` in the KB.
+
+On **failure**, the task goes to `blocked` (out of the runnable set, so the loop never retries forever), the agent goes `blocked`, an error report is written, and a `block` Inbox item is pushed.
+
+---
+
+## 4. Key concepts ✦
+
+- **The directory is the source of truth.** Specs (`specs/SPEC-NN.md`), issues (`issues/<key>.md`), the backlog (`PO/backlog.md`) and reports (`Reports/*.md`) all live on disk; the DB indexes them. See [ARCHITECTURE](./ARCHITECTURE.md).
+- **Issue vs Task.** An *issue* is the planned unit on the board; a *task* is its executable mirror that the runner actually runs. `materializeTasks` bridges them (`task.issueId`); the runner mirrors task column moves back onto the issue.
+- **Checklist-driven progress.** Each task carries `taskStep` rows (its TODOs). Issue % = done/total steps (or column fallback); Goal % = the **average** of its issues' %. Computed on read in `goalRollups` — no drift.
+- **Auto-handoff.** When an agent ends its reply by `@mention`ing exactly one teammate, `relayRoomMentions` makes that teammate reply and work (a bounded chain). `@operator` pings you instead. See [TEAM_ROOM](./TEAM_ROOM.md).
+- **Crash recovery.** `reclaimOrphans` re-queues `doing` tasks left stuck by a dead process; `reclaimStaleLocks` drops abandoned per-file locks.
+
+---
+
+## 5. Tables 🗄️
+
+### `plan` (one row per workspace — the gate)
+
+| Column | Type | Meaning |
+| --- | --- | --- |
+| `workspaceId` | text (PK) | the workspace this plan belongs to |
+| `approved` | bool | the approval gate — code runs only when `true` |
+| `auto247` | bool | Run 24/7 — the autonomous cron loop runs only when `true` |
+| `stage` | int (default 4) | pipeline marker: `1` = sent back for revision, `4` = drafted/awaiting approval, `6` = approved |
+
+### `goal`
+
+| Column | Meaning |
+| --- | --- |
+| `status` | `active` \| `cancelled` \| `archived` \| `done` |
+| `progress` | cached rollup % (recomputed by the runner while active; sticky once settled) |
+| `specId` | the main spec the goal was born from |
+| `ownerId` | the CEO agent |
+| `archivePath` | ZIP path when archived |
+| `doneAt` / `cancelledAt` / `archivedAt` / `reopenedAt` | lifecycle timestamps |
+
+### `spec` / `issue` / `task`
+
+| Table | Workflow column | Lifecycle `status` |
+| --- | --- | --- |
+| `spec` | — (`approved` bool) | `active` \| `cancelled` \| `archived` |
+| `issue` | `col`: `todo` \| `doing` \| `blocked` \| `review` \| `done` | `active` \| `cancelled` \| `archived` |
+| `task` | `col`: `triage` \| `todo` \| `doing` \| `blocked` \| `review` \| `done` | — |
+
+`issue` also has `prio` (`low`/`med`/`high`), `moscow` (`Must`/`Should`/`Could`/`Won't`) and `points`. `task` adds `assigneeId`, `goalId`, `issueId`, `createdBy`.
+
+### Column → progress map (`src/server/progress.ts`)
+
+| Column | % |
+| --- | --- |
+| `triage` / `todo` | 0 |
+| `blocked` | 25 |
+| `doing` | 50 |
+| `review` | 80 |
+| `done` | 100 |
+
+---
+
+## 6. Lifecycle diagram 🌌
+
+```mermaid
+flowchart TD
+    B["Brief / DM @ada / New work"] --> P["generatePlanFor → runPlanJob<br/>(CEO @ada, real CLI)"]
+    P --> G["Goal + Specs + Issues<br/>written to disk · stage 4"]
+    G --> GATE{"Operator approves?<br/>(approval gate)"}
+    GATE -- "Reject → requestPlanChangesFor<br/>(stage 1, un-approve)" --> P
+    GATE -- "Approve → approvePlanFor<br/>(stage 6)" --> M["materializeTasks<br/>issues → tasks (todo)<br/>+ DOCS-1, groom backlog"]
+    M --> R24{"Run 24/7 on?<br/>(plan.auto247)"}
+    R24 -- "off" --> IDLE["Tasks wait in todo"]
+    R24 -- "on (cron tick)" --> EXEC["runOneTask:<br/>claim todo → doing<br/>spawn claude/codex"]
+    EXEC --> OK{"Run ok?"}
+    OK -- "no" --> BLK["task → blocked<br/>agent → blocked<br/>block Inbox item"]
+    OK -- "yes" --> BOOT{"Boot gate<br/>(code touched?)"}
+    BOOT -- "broken" --> REV["Held at review<br/>+ Inbox"]
+    BOOT -- "ok" --> TEST{"Test Dev gate<br/>(server up?)"}
+    TEST -- "fail" --> REV
+    TEST -- "pass" --> RG{"Review gate<br/>(autoReview)"}
+    RG -- "high-sev" --> REV
+    RG -- "clean" --> DONE["task → done<br/>mirror issue · tick steps"]
+    DONE --> ROLL["recomputeGoalProgress"]
+    ROLL --> CHECK{"Goal 100%?"}
+    CHECK -- "no" --> EXEC
+    CHECK -- "yes" --> COMPLETE["Goal → done<br/>CEO summary report<br/>history → KB 🚀"]
+```
+
+---
+
+## 7. Step-by-step 🛰️
+
+1. **Describe the work.** DM `@ada` "build X", click **New work** in the Planner, or run `/new-work <brief>`.
+2. **Watch the plan stream.** The Planner's **planner** channel shows Ada analyzing, drafting and writing files.
+3. **Review the drafts.** Open the CEO Planner; read the specs/issues. Reject a single spec/issue to DM its author for a revision, or reject the whole plan (`requestPlanChanges`, rewinds to stage 1).
+4. **Approve.** Click **Approve** (or send `/approve`). Tasks materialize; the board fills with `todo`.
+5. **Turn on Run 24/7.** Flip **Run 24/7** (`/run-247`). The worker now dispatches one task per tick.
+6. **Monitor.** The team room shows each agent's run; the Inbox surfaces blocks/reviews/budgets; progress climbs live.
+7. **Resolve holds.** Anything held at `review` or `blocked` appears in the [INBOX](./INBOX.md) — fix and re-queue.
+8. **Delivery.** When the Goal hits 100% it auto-completes and a CEO summary report is filed.
+
+---
+
+## 8. Examples 🌠
+
+**Start new work from chat (DM):**
+
+```
+You → @ada: build a CSV export button on the reports page, with a unit test
+@ada: Plan ready for review: 2 specs and 4 issues drafted from the brief.
+      Open the CEO Planner and approve to start execution.
+```
+
+**Approve + run via slash commands** (see [CHAT_COMMANDS](./CHAT_COMMANDS.md)):
+
+```
+/approve        # approvePlan — gate opens, tasks materialize
+/run-247        # setAuto247(true) — autonomous loop starts
+/status         # one-line: active goals · open issues · in-flight · 24/7 · plan state
+```
+
+**Pause / send back / stop a goal:**
+
+```
+/pause          # setAuto247(false) — autonomous loop stops (tasks stay)
+/reject         # requestPlanChanges — un-approve, rewind to stage 1
+/cancel         # cancelGoal — kill in-flight runs + park tasks, preserve everything
+/archive        # archiveGoal — ZIP the goal's files + manifest, park execution
+```
+
+---
+
+## 9. Possible states 🪐
+
+### Plan state
+
+| State | Condition |
+| --- | --- |
+| `none` | no plan row |
+| `draft (stage N)` | `approved = false` |
+| `approved` | `approved = true` |
+
+### Run state (Planner, derived)
+
+| State | Meaning |
+| --- | --- |
+| `waiting-approval` | plan not approved yet |
+| `off` | approved, Run 24/7 off |
+| `running` | approved + 24/7 on + runnable issues |
+| `blocked` | approved but no runnable assigned issue |
+| `all-done` | every issue `done` |
+
+### Task / issue column
+
+`triage → todo → doing → review → done`, plus `blocked` (out of the runnable set). A successful autonomous run lands on `done`; `review` is reached only by a failed gate or operator hand-routing.
+
+### Goal status
+
+`active → done` (auto, at 100%); `active → cancelled` / `archived` (operator); `cancelled`/`archived → active` (reopen/restore).
+
+---
+
+## 10. Related integrations 🛰️
+
+- **Telegram** — the plan-ready push carries **Approve / Start execution / Review / Reject** buttons; remote `approvePlanFor` / `setAuto247For` / `cancelGoalFor` via the allowlisted chat. See [TELEGRAM](./TELEGRAM.md).
+- **Public API / MCP** — `POST /v1/plan/approve`, `/plan/reject`, `/execution`, `/work`, `/goals/:id/cancel`, `/goals/:id/archive` reach the same session-less cores. See [PUBLIC_API](./PUBLIC_API.md) and [MCP](./MCP.md).
+- **Inbox** — every gate failure / block / budget cap / approval surfaces here. See [INBOX](./INBOX.md).
+- **KB** — completed tasks, learnings and deliveries are ingested as reusable knowledge. See [KB_RAG](./KB_RAG.md) and [MEMORY_RAG](./MEMORY_RAG.md).
+
+---
+
+## 11. Security 🕳️
+
+- **The approval gate is fail-closed:** no plan or `approved = false` → the runner never spawns a code run.
+- **The cron endpoint is fail-closed:** `POST /api/cron/tick` rejects (401) without a matching `x-worker-secret`.
+- **Budget caps** (`agent.dailyCapUsd`) stop an agent at its daily spend and surface a budget Inbox item instead of overspending.
+- **Command guard** (`guard-hook.mjs`, default on) blocks destructive shell commands; blocked attempts are surfaced once per task in the Inbox.
+- **Secret scrubbing** (`scrubSecrets`) cleans agent output before it lands in the room, the KB or Telegram. See [SECURITY](./SECURITY.md).
+
+---
+
+## 12. Troubleshooting 🔭
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Tasks never run | plan not approved | `/approve` (open the gate) |
+| Approved but idle | Run 24/7 is off, or no worker | `/run-247`; ensure the worker process is up (see [START_MODE](./START_MODE.md)) |
+| Task stuck at `review` | a gate held it (boot/test/review) | check the [INBOX](./INBOX.md) item, fix, re-queue |
+| Task `blocked` | the run errored | read `Reports/error-report.md` + the Inbox detail |
+| Agent paused | hit `dailyCapUsd` | raise the cap in Agent Studio or wait for the daily reset |
+| Planning returns nothing | model produced no parseable JSON | retry; a notification + planner `error` event explain it |
+| Goal stuck below 100% | an issue is `blocked`/`review` | resolve the held task; the average rolls up on the next tick |
+| Ada stuck `working` | a prior plan job died before its `finally` | self-recovers — a fresh `generatePlanFor` detects no live run and restarts |
+
+---
+
+## 13. Related links 🌌
+
+- [GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md) — the data model behind each stage
+- [PO_AGENT](./PO_AGENT.md) — backlog grooming, story points, MoSCoW
+- [AGENTS](./AGENTS.md) — the roster that executes the work
+- [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) — how a run is assembled and spawned
+- [TEST_DEV](./TEST_DEV.md) — the Test Dev / boot gate
+- [INBOX](./INBOX.md) — where holds, blocks and approvals land
+- [TEAM_ROOM](./TEAM_ROOM.md) · [DM](./DM.md) · [CHAT_COMMANDS](./CHAT_COMMANDS.md) — the human-in-the-loop surfaces
+- [TELEGRAM](./TELEGRAM.md) · [PUBLIC_API](./PUBLIC_API.md) · [MCP](./MCP.md) — remote control
+- [ARCHITECTURE](./ARCHITECTURE.md) — the control plane and directory-as-truth model

package/docs/pt/AGENTS.md

@@ -0,0 +1,279 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/AGENTS.md) · [✦ Constella](../../README.pt-BR.md)
+
+# Agentes — O Elenco ✦🛰️
+
+![](../assets/divider-orbit.svg)
+
+As dez estrelas operantes de toda organização Constella. Cada agente é um processo CLI real (`claude`/`codex`) com um papel, um gestor, um modelo, uma temperatura, um teto de orçamento diário e uma persona em disco. Juntos formam a constelação que planeja, constrói, revisa e lança o seu produto.
+
+## Quando usar
+
+- Você quer saber **quem faz o quê** e **quem se reporta a quem** numa organização recém-criada.
+- Você precisa do **handle**, **papel**, **modelo**, **teto diário** e **tier** exatos de um agente.
+- Você está montando o **Org Chart**, reatribuindo um gestor, ou mudando o modelo/orçamento de um agente.
+- Você quer entender os **arquivos de persona** (`.claude/agents/<handle>/…`), **status** e **saúde (health)**.
+
+## Como funciona 🌌
+
+O elenco **nasce do código**, não é digitado por uma pessoa. Três fontes o definem e o materializam:
+
+| Arquivo de origem | Papel |
+|---|---|
+| `src/data/scaffold.ts` (`AGENT_DEFS`) | Definição canônica do elenco + templates de persona/arquivos (`agentMd`, `pulseMd`, `toolsMd`, `skillsMd`). Renderiza os arquivos em disco `.claude/agents/<handle>/…`. |
+| `src/server/onboarding.ts` (`AGENTS`) | Insere as 10 linhas `agent` no banco durante o onboarding (com `tierFloor`, `dailyCapUsd`, `reportsTo`). |
+| `src/server/seed-roster.ts` (`seedRosterForExistingWorkspaces`) | **Backfill** — adiciona qualquer membro de `AGENT_DEFS` ausente num workspace já onboarded (ex.: Vannevar, incluído após os 9 originais). Idempotente; roda uma vez por boot via `reconcileOnBoot`. |
+
+O **diretório é a fonte da verdade**: a identidade de cada agente vive em Markdown sob `.claude/agents/<handle>/`. A linha do agente no banco (`src/db/schema.ts`) o indexa para a UI e o runner. Editar a persona na UI escreve de volta no disco (`saveAgentPersona`, `saveAgentModel` em `src/server/agents.ts`).
+
+> Nota: o seed de demonstração legado `src/db/seed.ts` lista apenas os **9** agentes originais (sem Vannevar). O backfill de boot (`seedRosterForExistingWorkspaces`) fecha essa lacuna, então todo workspace ativo termina com os **10**.
+
+## Fluxo principal — da definição a um agente vivo
+
+```mermaid
+flowchart LR
+  A["AGENT_DEFS<br/>(scaffold.ts)"] --> B["onboarding.ts<br/>insere linhas agent"]
+  A --> C["agentFiles()<br/>renderiza .claude/agents/&lt;handle&gt;/"]
+  B --> D[("tabela agent")]
+  C --> E["Agent.md · pulse.md<br/>tools.md · skills.md"]
+  D --> F["Runner / Org Chart / Studio"]
+  E --> G["assembleAgentPrompt<br/>(persona → execução CLI)"]
+  H["backfill seed-roster.ts<br/>(no boot)"] -. preenche lacunas .-> D
+  H -. escreve .-> E
+```
+
+## Os 10 agentes 🪐
+
+Fonte da verdade: `AGENT_DEFS` em `src/data/scaffold.ts` (espelhado por `AGENTS` em `src/server/onboarding.ts`).
+
+| Nome | Handle | Papel | Reporta a | Modelo | Temp | Teto diário (USD) | Tier | Cor |
+|---|---|---|---|---|---|---|---|---|
+| Ada | `ada` | CEO | — (raiz) | `sonnet` | 0.4 | $15 | critical | `#e0a44e` |
+| Linus | `linus` | CTO | `ada` | `sonnet` | 0.3 | $40 | critical | `#9a5cff` |
+| Donald | `donald` | Product Owner | `ada` | `haiku` | 0.4 | $20 | heavy | `#4fc9b0` |
+| Margaret | `margaret` | Backend | `linus` | `sonnet` | 0.3 | $50 | heavy | `#3fb98f` |
+| Grace | `grace` | Frontend | `linus` | `sonnet` | 0.5 | $45 | heavy | `#5b8def` |
+| Edsger | `edsger` | QA | `linus` | `haiku` | 0.2 | $25 | heavy | `#e8688f` |
+| Werner | `werner` | DevOps | `linus` | `haiku` | 0.3 | $20 | heavy | `#f0a35e` |
+| Barbara | `barbara` | Docs | `ada` | `haiku` | 0.4 | $15 | light | `#b3d97a` |
+| Whitfield | `whitfield` | CyberSec | `linus` | `opus` | 0.2 | $30 | critical | `#c4a0ff` |
+| Vannevar | `vannevar` | Knowledge | `ada` | `haiku` | 0.2 | $10 | light | `#7ac5e0` |
+
+Todos os dez vêm com `provider: cli_claude_code` por padrão. `model` é um alias real da CLI do Claude Code — só `opus`, `sonnet`, `haiku` existem para esse adapter (`CLI_MODELS.cli_claude_code` em `src/server/adapters/cli.ts`).
+
+### Identidades e rituais
+
+Cada agente carrega uma `identity` (quem é) e um `ritual` (o que faz a cada ciclo de trabalho), direto de `AGENT_DEFS`:
+
+| Agente | Identidade | Ritual |
+|---|---|---|
+| Ada | Líder decidida e orientada a resultado. Fala em objetivos, não em tarefas. Protege escopo e orçamento. | Ler os objetivos da empresa, decompor em épicos, delegar aos líderes, revisar o que foi entregue. |
+| Linus | Pensador de sistemas. Equilibra velocidade de entrega contra dívida técnica. | Transformar épicos em tickets, rotear trabalho aos especialistas, desbloquear, revisar PRs. |
+| Donald | Voz do cliente. Implacável quanto a prioridade e clareza. | Refinar o backlog com MoSCoW, planejar a sprint, acompanhar entrega, fechar com retro. |
+| Margaret | Engenheira de servidor pragmática. Valoriza correção, diffs pequenos e testes verdes. | Pegar um ticket, ler o contexto, implementar numa branch, nunca dar push sem suíte passando. |
+| Grace | Engenheira de UI focada em ofício. Cuida de acessibilidade e APIs de componente limpas. | Ler os design tokens, construir o menor componente que funciona, typecheck antes do PR. |
+| Edsger | Portão de qualidade cético. Assume que nada funciona até um teste provar. | Reproduzir, cobrir com teste, rodar a suíte, então liberar o sign-off. |
+| Werner | Operador focado em confiabilidade. Automatiza o tedioso, guarda os leases. | Buildar, fazer deploy de preview, reportar a URL, nunca deixar um ambiente alocado tempo demais. |
+| Barbara | Explicadora paciente. Transforma mudanças em documentação compreensível. | Observar merges, escrever docs com o contexto fresco, verificar cada link. |
+| Whitfield | Revisor adversarial. Pensa como atacante, escreve como auditor. | Auditar cada mudança quanto a manuseio de segredos e injeção, registrar achados com correção concreta. |
+| Vannevar | Guardião da memória semântica da empresa. Indexa todo documento E conversa em embeddings. | Manter o servidor de embeddings saudável; re-indexar docs do workspace e o chat no índice RAG para a recuperação ficar atual. |
+
+## Árvore de reporte — o org chart 🌠
+
+Duas raízes de órbita: **Ada (CEO)** no centro; **Linus (CTO)** carrega a constelação de engenharia. `reportsTo` armazena o **handle do gestor** (handle-space de ponta a ponta — ver `setReportsToByHandle`).
+
+```mermaid
+graph TD
+  ada["Ada · CEO · sonnet · $15 · critical"]
+  linus["Linus · CTO · sonnet · $40 · critical"]
+  donald["Donald · Product Owner · haiku · $20 · heavy"]
+  barbara["Barbara · Docs · haiku · $15 · light"]
+  vannevar["Vannevar · Knowledge · haiku · $10 · light"]
+  margaret["Margaret · Backend · sonnet · $50 · heavy"]
+  grace["Grace · Frontend · sonnet · $45 · heavy"]
+  edsger["Edsger · QA · haiku · $25 · heavy"]
+  werner["Werner · DevOps · haiku · $20 · heavy"]
+  whitfield["Whitfield · CyberSec · opus · $30 · critical"]
+
+  ada --> linus
+  ada --> donald
+  ada --> barbara
+  ada --> vannevar
+  linus --> margaret
+  linus --> grace
+  linus --> edsger
+  linus --> werner
+  linus --> whitfield
+```
+
+- **Subordinados diretos de Ada:** `linus`, `donald`, `barbara`, `vannevar`.
+- **Subordinados diretos de Linus:** `margaret`, `grace`, `edsger`, `werner`, `whitfield`.
+- Tarefas bloqueadas escalam para o `reportsTo` do agente (conforme `.claude/routing.md`).
+
+## Conceitos-chave ✦
+
+### Arquivos de persona (o diretório é o cérebro)
+
+Para cada agente, `agentFiles(def, ctx)` escreve **quatro** arquivos Markdown sob `.claude/agents/<handle>/`:
+
+| Arquivo | Gerador | Conteúdo |
+|---|---|---|
+| `Agent.md` | `agentMd` | Front-matter YAML (`handle`, `name`, `role`, `reportsTo`, `provider`, `model`, `temperature`, `dailyCapUsd`, `tierFloor`) + Identity, Ritual, Responsibilities, Behavior (da temperatura), regras de Decision/Execution, limites de workspace e o **System prompt**. |
+| `pulse.md` | `pulseMd` | Config de liveness — `intervalSec: 30`, `maxMissed: 2`, `wakeOn` (`queued_task`, `mention`), e a legenda de status/health. |
+| `tools.md` | `toolsMd` | Tabela de ferramentas por papel (ex.: CyberSec → `secret-scan`, `review.signoff`, `fs.read`; Knowledge → `rag.reindex`, `rag.index-chat`, `embed.health`). |
+| `skills.md` | `skillsMd` | Os procedimentos vinculados ao agente (de `SKILL_DEFS`) + seu ritual. |
+
+`Agent.md` é **write-through**: edições na UI (Agent Studio) corrigem o front-matter e as seções no lugar (`setFrontMatter`, `setInlineField`, `setSection`) e a linha do banco é atualizada para casar. O diretório vence em caso de conflito.
+
+### Modelo e tier
+
+- **Não é só Claude.** Os valores semente `opus`/`sonnet`/`haiku` são apenas os padrões do adaptador semente `cli_claude_code`. Troque o `adapter` por agente em **Agent Studio → Model** e o **menu de modelos muda junto** — o `ModelPicker` é indexado pelo `adapter` (`cliModelOptions(adapter)`, `src/components/ui/model-picker.tsx`): `cli_codex` → `gpt-5-codex` / `o4-mini`; `cli_openclaw` / `cli_hermes` / `cli_aider` / `cli_opencode` / `cli_copilot` / `cli_cursor` / `cli_cline` / `cli_kilo` → seus ids roteados por provedor; `local_*` → o GGUF carregado; provedores HTTP/router → o catálogo de modelos em cache. A tabela completa de adaptadores está em [MODELS.md](./MODELS.md).
+- `model` é o alias configurado. Para `cli_claude_code` é um de `opus` / `sonnet` / `haiku`.
+- `tierFloor` (`light` | `heavy` | `critical`) é o piso de qualidade do agente — padronizado em `AGENT_DEFS`, persistido na linha `agent` (`tier_floor`, padrão `heavy`). **Os tiers são agnósticos ao provedor:** um modelo de raciocínio de ponta em qualquer provedor (ex.: um Codex/GPT no modo de raciocínio alto, ou um Gemini de topo) mapeia para o tier `critical` / classe-Opus em potência e custo, enquanto modelos menores/mais rápidos (`o4-mini`, um "flash", `haiku`) mapeiam para a ponta `light`.
+- Para etapas críticas de qualidade (revisão de código, segurança, validação final) o runner pode buscar o modelo **mais forte** do provider do agente via `strongestModelFor()` — para `claude` isso resolve em `opus`, e o flagship equivalente para qualquer outro provedor.
+- O menu de modelos troca **automaticamente** ao escolher um provedor; o **teto diário não** — é um orçamento em USD independente que você ajusta (próxima seção) para casar com o tier de custo do modelo.
+- `temperature` **não** seta uma flag de sampling da CLI (a CLI do Claude Code não expõe nenhuma). Em vez disso, `temperatureBehavior(t)` transforma o slider numa **instrução de prompt** concreta injetada em toda execução (`src/data/temperature.ts`).
+
+### Teto diário (limite de orçamento) 🕳️
+
+`dailyCapUsd` é um teto rígido de gasto por agente por dia. O runner chama `agentAtCap(agentId, dailyCapUsd)` (`src/server/runner.ts`); ao atingir, **pausa** o agente e empurra um item de inbox `budget` ("@`<handle>` atingiu o teto diário de orçamento"). Aumente o teto no Agent Studio ou espere o reset diário. Um teto de `0` significa "sem teto".
+
+### Status e saúde (health)
+
+Dois eixos ortogonais na linha `agent`:
+
+| Eixo | Coluna | Valores | Significado |
+|---|---|---|---|
+| **Status** | `status` | `idle` · `working` · `review` · `blocked` | O que o agente está fazendo agora. |
+| **Health** | `health` | `alive` · `stale` · `down` | Se o executor está alcançável. |
+
+A varredura do cron tick (`runner.ts`) define a saúde a partir da disponibilidade do runtime: se o binário CLI do agente está alcançável (`runtimeOk`), a saúde é `alive`; caso contrário `stale`. Agentes ociosos recebem um toque de heartbeat leve (`lastPulse` atualizado, sem spam de linha de pulse); agentes em working/review registram uma linha real de `pulse` via `recordPulse`. O `pulse.md` documenta o contrato de liveness: alive dentro de `intervalSec * maxMissed`, senão stale; falha repetida → `down` (registrado em `Reports/error-report.md`).
+
+## Tabelas 🛰️
+
+### `agent` (`src/db/schema.ts`)
+
+| Coluna | Tipo | Padrão | Notas |
+|---|---|---|---|
+| `id` | text PK | — | Id estável. |
+| `workspaceId` | text | — | FK → `workspace` (cascade). |
+| `handle` | text | — | Nome curto único (`ada`, `linus`, …). |
+| `name` | text | — | Nome de exibição. |
+| `role` | text | — | CEO / CTO / Backend / … |
+| `color` | text | `#e0a44e` | Tom do avatar (usado no fallback de iniciais). |
+| `image` | text | null | Caminho/data-URL opcional do avatar. |
+| `adapter` | text | `cli_claude_code` | Runtime de execução (CLI/HTTP/local). |
+| `model` | text | `sonnet` | Alias de modelo. |
+| `temperature` | real | `0.4` | Conduz a banda de prompt de Behavior. |
+| `dailyCapUsd` | real | `25` | Teto diário de gasto. |
+| `tierFloor` | text enum | `heavy` | `light` / `heavy` / `critical`. |
+| `reportsTo` | text | null | **Handle** do gestor. |
+| `status` | text enum | `idle` | `idle` / `working` / `review` / `blocked`. |
+| `health` | text enum | `alive` | `alive` / `stale` / `down`. |
+| `lastPulse` | timestamp | null | Último heartbeat. |
+| `persona` | json | null | `{ identity, ritual, tone, systemPrompt }`. |
+| `rag` | json | null | Toggles de fonte RAG por agente. |
+| `orgX` / `orgY` | real | null | Coordenadas do card no org-chart. |
+
+### `pulse` (log de heartbeat)
+
+| Coluna | Tipo | Notas |
+|---|---|---|
+| `id` | text PK | — |
+| `agentId` | text | FK → `agent`. |
+| `at` | timestamp | Padrão `unixepoch()`. |
+| `ok` | boolean | Resultado do health-ping. |
+| `latencyMs` | integer | Latência do ping. |
+| `note` | text | ex.: `tick:working`. |
+
+### `agentSkill` (join de habilitação)
+
+| Coluna | Notas |
+|---|---|
+| `agentId` + `skillId` | PK composta. |
+| `auto` | `true` = vínculo gerenciado pelo sistema (reconciliado no boot/mudança de stack); `false` = ativado à mão pelo operador (nunca tocado pelo reconcile). |
+
+## Passo a passo — operar o elenco
+
+1. **Ver o elenco.** Abra o módulo Agents (cada card mostra status, health, modelo). O Org Chart visualiza `reportsTo`.
+2. **Reatribuir um gestor.** Arraste um card no canvas do Org Chart → `setReportsToByHandle(agentHandle, managerHandle)`. Auto-loops e ciclos são rejeitados; passe `null` para destacar (vira raiz/CEO).
+3. **Mudar modelo / orçamento / tier.** No Agent Studio → `saveAgentModel({ adapter, model, temperature, dailyCapUsd, tierFloor })`. A linha do banco e o front-matter do `Agent.md` são atualizados juntos.
+4. **Editar persona.** `saveAgentPersona({ identity, ritual, tone, systemPrompt })` corrige o `Agent.md` (Identity, Ritual, System prompt) em disco.
+5. **Definir um avatar.** `saveAgentImage(agentId, imagePath | null)` (avatares em data-URL; avatares legados `uploads/<id>/` são limpos ao substituir).
+6. **Adicionar um agente ausente.** No boot, `seedRosterForExistingWorkspaces()` faz backfill de qualquer membro de `AGENT_DEFS` ausente no workspace — linha do banco, quatro arquivos de persona e as skills nativas não-provisórias.
+
+## Exemplos
+
+Inspecionar a persona de um agente em disco:
+
+```bash
+cat ~/.constella/organizations/<orgId>/workspace/.claude/agents/linus/Agent.md
+```
+
+Front-matter que você verá (renderizado por `agentMd`):
+
+```yaml
+---
+handle: linus
+name: Linus
+role: CTO
+reportsTo: ada
+provider: cli_claude_code
+model: sonnet
+temperature: 0.3
+dailyCapUsd: 40
+tierFloor: critical
+---
+```
+
+Listar agentes e sua linha de reporte pelo chat:
+
+```
+/agents
+/agent linus
+```
+
+(`/agents` lista o elenco; `/agent <handle>` mostra o detalhe de um agente — ver [CHAT_COMMANDS.md](./CHAT_COMMANDS.md).)
+
+## Estados possíveis
+
+| Aspecto | Valores | Definido por |
+|---|---|---|
+| Status | `idle` · `working` · `review` · `blocked` | Runner / planner conforme o trabalho flui. |
+| Health | `alive` · `stale` · `down` | Varredura do cron tick (alcance do binário) + pulse sweep. |
+| Orçamento | abaixo do teto → roda · no/acima do teto → pausado (item de inbox `budget`) | `agentAtCap()`. |
+| Tier floor | `light` · `heavy` · `critical` | Padrão de `AGENT_DEFS`; editável no Studio. |
+
+## Integrações relacionadas 🚀
+
+- **Skills** — os procedimentos habilitados de cada agente (`agentSkill`, `skills.md`). Ver [SKILLS.md](./SKILLS.md).
+- **Models** — adapters e catálogo de modelos por trás de `adapter`/`model`. Ver [MODELS.md](./MODELS.md).
+- **Workflow** — como os agentes pegam Goals → Specs → Issues → Tasks. Ver [WORKFLOW.md](./WORKFLOW.md).
+- **Team Room / DM** — onde os agentes colaboram e fazem handoff. Ver [TEAM_ROOM.md](./TEAM_ROOM.md), [DM.md](./DM.md).
+- **PO Agent / KB Agent** — o refinamento de Donald e a memória de Vannevar. Ver [PO_AGENT.md](./PO_AGENT.md), [KB_AGENT.md](./KB_AGENT.md).
+
+## Segurança 🕳️
+
+- **Jaula de workspace.** Cada agente roda com `cwd` no workspace da sua organização e é verificado lexicamente + por symlink contra fuga; nada fora do workspace é alcançável. Os limites são declarados em `Agent.md`, `permissions.md` e impostos pelo runner.
+- **Sem segredos inline.** Personas e ferramentas proíbem chaves em texto puro; segredos vêm do vault. A saída é higienizada antes de logs/KB/Telegram.
+- **Tetos de orçamento.** Um agente descontrolado para no seu `dailyCapUsd`; o runner não excede o teto.
+- **Guardas de ciclo/self.** A reatribuição de gestor (`setReportsTo`, `setReportsToByHandle`) rejeita auto-referências e ciclos, então o org chart nunca forma um loop.
+
+## Troubleshooting
+
+| Sintoma | Causa provável | Correção |
+|---|---|---|
+| Um agente aparece **stale/down** | Seu binário CLI não está instalado/alcançável (`runtimeOk` falso). | Instale/repare a CLI `claude`/`codex`; a saúde se recupera no próximo tick. |
+| Agente **pausado no meio do trabalho** | Atingiu seu `dailyCapUsd`. | Aumente o teto no Agent Studio ou espere o reset diário (ver o item de inbox `budget`). |
+| Vannevar ausente numa org antiga | Org onboarded antes do agente Knowledge existir. | O backfill de boot (`seedRosterForExistingWorkspaces`) o adiciona automaticamente na próxima inicialização. |
+| Mudança de gestor não faz nada | Self/ciclo (rejeitado) ou gestor fora deste workspace. | Escolha outro gestor; a mudança é silenciosamente ignorada para alvos inválidos. |
+| `Agent.md` editado mas UI ainda antiga | Atraso de write-through/watcher. | O sync engine re-indexa ao salvar; recarregue após um instante. |
+
+## Links relacionados
+
+- [AI_ARCHITECTURE.md](./AI_ARCHITECTURE.md) — como as execuções de agente são montadas e executadas.
+- [WORKFLOW.md](./WORKFLOW.md) — o ciclo Goal → Spec → Issue → Done.
+- [SKILLS.md](./SKILLS.md) — a biblioteca de skills de que cada agente se vale.
+- [MODELS.md](./MODELS.md) — adapters, aliases de modelo e tiers.
+- [PO_AGENT.md](./PO_AGENT.md) · [KB_AGENT.md](./KB_AGENT.md) — Donald e Vannevar em profundidade.
+- [TEAM_ROOM.md](./TEAM_ROOM.md) · [DM.md](./DM.md) — colaboração entre agentes.
+- [CHAT_COMMANDS.md](./CHAT_COMMANDS.md) — `/agents`, `/agent`, `/status`.