constellai 0.3.0

package/docs/en/GITHUB.md

@@ -0,0 +1,341 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/GITHUB.md) · [✦ Constella](../../README.md)
+
+# GitHub 🛰️
+
+![](../assets/divider-orbit.svg)
+
+The launch bay that connects a constellation's workspace to a real Git remote. Two distinct flight paths leave from here: **Commit GitHub** (the full control-plane workspace → its bound `origin`) and **Export Clean Source** (only the product, stripped of Constella's internal layer → a separate repo). Both pass through the same secret-scan airlock.
+
+> Source of truth: [`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. When to use 🌠
+
+- You connected a GitHub account during onboarding (or want to connect/replace one now).
+- An agent (or you) finished work and you want **real local git history** plus a **push to a remote**.
+- You want to publish **only the product** — without `.claude/`, planning docs, or any internal control files — to a public/separate repo.
+- You need to verify there are no leaked secrets before anything leaves the ship.
+
+---
+
+## 2. How it works 🌌
+
+Every workspace lives at the org root on disk (`orgRoot(org.id)`). The GitHub module operates on that directory as a **normal git repository**:
+
+- `ensureRepo(cwd)` runs `git init -b main` on first use and drops a default `.gitignore` so `git add -A` never stages `node_modules/`, `.next/`, `dist/`, build output, `.env*`, `uploads/`, or `.testdev/`.
+- Authentication uses a **GitHub token** resolved by `ghToken(workspaceId, userId)`:
+  1. **Vaulted PAT** (`getSecret(workspaceId, "github_pat")`) — preferred.
+  2. **OAuth access token** — the user's GitHub `account.accessToken` from better-auth, usable for git **only** if the OAuth app was granted the `repo` scope.
+- The token is **redacted from every captured string** (`redact()` splits on the token and replaces it with `***`) so it can never leak into a notification, the Inbox, or the UI.
+- All GitHub API calls go through `ghApi(token, path)` against `https://api.github.com` with a 12s timeout and `User-Agent: constella`.
+
+### Two flight paths
+
+| Path | Function | Source dir | Target | Strips internal layer? | Push style |
+|------|----------|-----------|--------|------------------------|------------|
+| **Commit GitHub** | `commitPush()` in `github.ts` | the live workspace (`orgRoot`) | the **bound** `origin` repo | No — commits the whole workspace (minus `.gitignore`) | `git push HEAD:<branch>` |
+| **Export Clean Source** | `exportCleanSource()` in `prepare-deploy.ts` | a **temp** clean tree | a **separate** repo (`owner/repo`) | Yes — only `isCleanProductPath` survives | `git push -f HEAD:<branch>` |
+
+---
+
+## 3. Main flow 🚀
+
+### Connect
+
+```
+connectGitHub(pat)
+  → trim + length check
+  → GET https://api.github.com/user  (verify the token actually works; 401 → error)
+  → delete any existing github_pat row → putSecret(ws, "github_pat", token)
+  → bind { login, repo: undefined, defaultBranch: undefined } to workspace.settings.github
+```
+
+The repo binding is **cleared on (re)connect** so a different account can't push to the previous account's repo.
+
+### Bind a repo
+
+```
+setRepo("owner/repo")
+  → normalize (strip https://github.com/ and .git)
+  → ghToken() must reach GET /repos/owner/repo  (404 → "token can't access it")
+  → ensureRepo(cwd) → git remote add|set-url origin https://github.com/owner/repo.git
+  → persist settings.github = { repo, defaultBranch }
+```
+
+`createRepo({ name, private })` is a shortcut: it `POST`s `/user/repos` then calls `setRepo` on the new full name.
+
+### Commit + push
+
+`commitPush({ repo, branch, message, delegated?, force? })` runs three safety gates **before** touching git, then commits and (optionally) pushes / opens a PR. See [§4](#4-key-concepts-) and the diagram in [§8](#8-mermaid-diagrams-).
+
+### Export clean source
+
+`exportCleanSource({ repo, token?, branch?, message? })` copies only the clean product into a temp dir, scans it, and force-pushes to a **different** repo. It never touches the workspace's own `origin`.
+
+---
+
+## 4. Key concepts 🪐
+
+### PAT vs OAuth token
+
+| | Vaulted PAT (`github_pat`) | OAuth `account.accessToken` |
+|---|---|---|
+| Stored where | `vault` table, AES-256-GCM (`CONSTELLA_VAULT_KEY`) | better-auth `account` row |
+| Set by | `connectGitHub()` / onboarding | GitHub OAuth sign-in |
+| Used for git push? | Yes | Only if granted `repo` scope |
+| Precedence | **First** (preferred) | Fallback when no PAT |
+| Per-company | Yes — vaulted per `workspaceId` | Per user account |
+
+`ghToken()` always returns the PAT if present, otherwise the OAuth token, otherwise `null` ("Connect GitHub first").
+
+### `setRepo` binding — the per-company guard
+
+The chosen repo is recorded in `workspace.settings.github.repo` (and `defaultBranch`). This binding is later checked at commit time so an agent can never push to a repo this company's token shouldn't reach. Binding **fails** if the bound token can't `GET /repos/owner/repo`.
+
+### `refreshGitStatus` — reconciling the working tree
+
+`file.gitStatus` is never populated by the watcher; `refreshGitStatus()` runs the **real** `git status --porcelain -z --untracked-files=all` and reconciles the `file` table so the GitHub + Code modules show actual changes.
+
+- `-z` → NUL-separated **raw** paths (renames/copies consume an extra old-path field; non-ASCII names stay intact).
+- Each entry maps to a one-letter code: `U` (untracked `?`), `D` (deleted), `A` (added), else `M` (modified).
+- `.git/` and `node_modules/` paths are skipped.
+- Files no longer changed get their `gitStatus` cleared back to `""`.
+- A per-workspace in-memory lock (`refreshing` Set) prevents two concurrent renders from racing the reconcile and inserting duplicate rows.
+
+### Commit GitHub vs Export Clean Source
+
+- **Commit GitHub** = honest local git history for the *whole workspace*, pushed to the *bound* `origin`. The control-plane layer (`.claude/`, planning dirs) is committed too (it is part of your private repo).
+- **Export Clean Source** = a *clean tree* — only files that pass `isCleanProductPath()` — force-pushed to a *separate* repo. This is the path for publishing the deliverable product without exposing Constella's internals.
+
+`isCleanProductPath(rel)` rejects any path whose top dir is in `DENY_TOP` (`.claude`, `DOCS`, `PO`, `Reports`, `specs`, `issues`, `mock`, `uploads`, `archives`, `.testdev`, `node_modules`, `.git`, `.next`, `dist`, `build`, `out`, `coverage`, `.cache`, `.turbo`, `vendor`), anything under `.constella`, and any `SENSITIVE` file (`.env*`, private keys, `*.pem/.key/.p12/...`, credentials JSON, dumps/db/logs) — **except** harmless env templates matching `ALLOW_ENV` (`.env.example|.sample|.template|.dist`).
+
+### Secret scan — the shared airlock
+
+Both paths call `scanForSecrets(cwd)` from `git-scan.ts`. It scans the files that *would* be committed (the working-tree change set; gitignored files are already excluded by `git status`).
+
+- **Must-never-commit files** by name: `.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` — except `ALLOW_FILE` templates.
+- **High-confidence content patterns**: AWS access key, GitHub token, OpenAI/Anthropic key, Google API key, Slack token, private key block, JWT, DB URL with credentials, Telegram bot token, and a generic hardcoded-secret pattern.
+- The generic pattern is suppressed for obvious **placeholders** (`your_`, `xxx`, `<...>`, `change_me`, `example`, `placeholder`, `***`, `dummy`, `todo`, `redacted`, `...`).
+- Findings are **redacted** in the preview (`first4•••last2`).
+- Files over 2 MB and binary files (containing `\0`) are skipped; scan caps at 3000 files / 300 findings.
+
+---
+
+## 5. Tables 🌌
+
+### `vault` (relevant ref)
+
+| Column | Value for GitHub |
+|--------|------------------|
+| `ref` | `github_pat` |
+| `ciphertext` | AES-GCM ciphertext of the PAT |
+| `iv` | per-secret IV |
+
+### `workspace.settings.github` (JSON)
+
+| Field | Meaning |
+|-------|---------|
+| `login` | GitHub username of the connected account |
+| `repo` | bound `owner/repo` (the per-company binding) |
+| `defaultBranch` | repo default branch (from the API) |
+
+### `file.gitStatus`
+
+| Code | Meaning |
+|------|---------|
+| `""` | no change |
+| `M` | modified |
+| `A` | added / staged-new |
+| `U` | untracked |
+| `D` | deleted |
+
+### `deploy_run.lastExport` (set by `exportCleanSource`)
+
+| Field | Meaning |
+|-------|---------|
+| `ok` | export succeeded |
+| `sha` | short commit SHA of the clean tree |
+| `copied` | number of clean files pushed |
+| `repo` / `branch` | export target |
+| `at` | timestamp |
+
+### `PushResult` (return of `commitPush`)
+
+| Field | Meaning |
+|-------|---------|
+| `ok` | a real commit landed |
+| `committed` | local commit created |
+| `sha` | short HEAD sha |
+| `pushed` | reached the remote |
+| `prUrl` | PR URL (delegated path only) |
+| `nothing` | working tree had nothing to commit |
+| `blocked` | a safety gate stopped the commit |
+| `secrets` | secret-scan findings when blocked |
+
+---
+
+## 6. Step-by-step 🛰️
+
+### Commit the workspace to its bound repo
+
+1. **Connect** a PAT (`connectGitHub`) or sign in with GitHub OAuth (`repo` scope).
+2. **Bind** a repo with `setRepo("owner/repo")` (or `createRepo`).
+3. (Optional) **Refresh** status — `refreshGitStatus()` populates the change list; `draftCommitMessage()` proposes a Conventional-Commit subject from `A`/`M`/`D` counts.
+4. **Scan** on demand with `scanWorkspace()` (no commit) to preview findings.
+5. **Commit + push** with `commitPush({ repo, branch, message })`. Pass `delegated: true` to also open a PR via `gh pr create --fill`. Pass `force: true` to bypass the secret-scan gate *after review*.
+
+### Export only the product
+
+1. Run **Prepare Deploy** (or `previewCleanExport()`) to see the clean tree + a pre-export scan.
+2. Call `exportCleanSource({ repo: "myorg/my-app-public" })` — or `/export-source myorg/my-app-public` in chat.
+3. The clean tree is built in a temp dir, secret-scanned, committed, and **force-pushed** to the separate repo. `deploy_run.lastExport` records the result.
+
+---
+
+## 7. Examples 🌠
+
+### Slash commands
+
+```
+/github                      # refresh git status, report changed file count (Werner)
+/export-source myorg/app-pub # export the clean product to a separate repo
+/prepare-deploy              # run the full production-prep pipeline
+```
+
+`/github` (handled in `src/server/commands.ts`) calls `refreshGitStatus()` and posts the changed-file count from Werner (DevOps).
+
+### Commit gate messages (real strings)
+
+```
+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
+```
+
+### Authenticated push URL
+
+`commitPush` rewrites the HTTPS origin to inject the PAT only at push time:
+
+```
+https://github.com/owner/repo.git
+→ https://x-access-token:<PAT>@github.com/owner/repo.git   (used for `git push`, redacted everywhere else)
+```
+
+---
+
+## 8. Mermaid diagrams 🪐
+
+### Commit GitHub vs Export Clean Source
+
+```mermaid
+flowchart TD
+  subgraph WS["Workspace on disk (orgRoot)"]
+    A[".claude / DOCS / PO / specs / issues / mock"]
+    B["product source + README + .env.example"]
+  end
+
+  WS --> P{Which path?}
+
+  P -->|"Commit GitHub<br/>commitPush()"| G1["Gate 1: PAT for this company?"]
+  G1 --> G2["Gate 2: origin == bound repo?"]
+  G2 --> G3["Gate 3: scanForSecrets()"]
+  G3 -->|"findings"| BLK1["BLOCKED → Inbox + notifyOps"]
+  G3 -->|"clean (or force)"| C1["git add -A → commit → push HEAD:branch"]
+  C1 --> C2["delegated? gh pr create --fill"]
+  C1 --> ORIGIN["bound origin repo<br/>(whole workspace)"]
+
+  P -->|"Export Clean Source<br/>exportCleanSource()"| E1["buildCleanTree → temp dir<br/>(isCleanProductPath filter)"]
+  E1 --> E2["git init + add -A"]
+  E2 --> E3["scanForSecrets() — final gate"]
+  E3 -->|"findings"| BLK2["BLOCKED → Inbox + notifyOps"]
+  E3 -->|"clean"| E4["commit → push -f HEAD:branch"]
+  E4 --> SEP["separate repo<br/>(product only)"]
+```
+
+### Token resolution
+
+```mermaid
+flowchart LR
+  T["ghToken(ws, user)"] --> V{"vault github_pat?"}
+  V -->|yes| PAT["use vaulted PAT"]
+  V -->|no| OA{"GitHub OAuth account?"}
+  OA -->|yes| TOK["use account.accessToken<br/>(needs 'repo' scope to push)"]
+  OA -->|no| NULL["null → 'Connect GitHub first'"]
+```
+
+---
+
+## 9. Possible states 🕳️
+
+### Commit gates (in order)
+
+| Gate | Trigger | Result |
+|------|---------|--------|
+| **1. PAT configured** | no `github_pat` for this workspace | `blocked` — "GitHub isn't configured for this company" |
+| **2. Repo bound + origin match** | no `settings.github.repo` / no origin, or mismatch | `blocked` — re-select the repo |
+| **3. Secret scan** | any finding (and `force` not set) | `blocked`, `secrets[]`, Inbox card + ops notification |
+
+After gates pass: `committed` → optional `pushed` → optional `prUrl`. A `nothing-to-commit` working tree returns `nothing: true`.
+
+### Push rejection
+
+A rejected / non-fast-forward push (`rejected | non-fast-forward | fetch first | merge conflict | failed to push`) is **not** silently dropped — it raises an Inbox `block` card ("Push rejected — \<repo\>") so the operator pulls + resolves.
+
+### Export states
+
+| State | Cause |
+|-------|-------|
+| `ok: false, error: "Use the form owner/repo."` | malformed target |
+| `ok: false, error: "...token can't access it."` | `GET /repos/...` returned 404 |
+| `blocked: true, secrets[]` | final scan found a secret |
+| `ok: true, pushed: true, sha, copied` | clean force-push landed |
+| `error: "Nothing to export yet..."` | `buildCleanTree` copied 0 files |
+
+---
+
+## 10. Related integrations 🌌
+
+- **Vault** — stores `github_pat` encrypted; see [SECURITY](./SECURITY.md).
+- **Inbox** — receives `block` cards for secret findings + push rejections; see [INBOX](./INBOX.md).
+- **Prepare Deploy** — the pipeline that builds, validates, and gates the clean export; see [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) and [DEPLOY](./DEPLOY.md).
+- **Agents** — Werner (DevOps) is the default deploy/commit agent; see [AGENTS](./AGENTS.md).
+- **Chat commands** — `/github`, `/export-source`, `/prepare-deploy`; see [CHAT_COMMANDS](./CHAT_COMMANDS.md).
+- **Onboarding** — initial GitHub import / connect; see [ONBOARDING](./ONBOARDING.md).
+
+---
+
+## 11. Security 🕳️
+
+- **Token never logged.** `redact()` strips the PAT from every captured stdout/stderr before it reaches the UI, Inbox, or notifications. The authenticated push URL (`x-access-token:<PAT>@...`) is only constructed in-memory for the `git push` call.
+- **Per-company isolation.** The PAT is vaulted by `workspaceId`; binding is verified against the token; commit Gate 2 ensures `origin` equals the bound repo — you can't push another org's repo.
+- **Mandatory secret scan.** Commit Gate 3 and the export final-gate both run `scanForSecrets`. The `force` flag only bypasses the *commit* scan and is intended for *post-review* use.
+- **Clean export strips internals.** `isCleanProductPath` removes the entire Constella control layer and all sensitive files before anything is pushed to a separate repo.
+- **Safe `.gitignore`.** `ensureRepo` guarantees deps/build/secrets are never staged by `git add -A`.
+
+See [SECURITY](./SECURITY.md) for the full vault + scrub model.
+
+---
+
+## 12. Troubleshooting 🛰️
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| "Connect GitHub first." | no PAT and no OAuth token | run `connectGitHub` with a `repo`-scoped PAT |
+| "Invalid token (401). ...needs the 'repo' scope." | PAT lacks `repo` scope or is wrong | regenerate with `repo` scope |
+| "Repo not found, or this company's token can't access it." | `GET /repos/owner/repo` 404 | check the repo name + that the token's account has access |
+| "Origin (X) doesn't match this company's configured repo (Y)." | origin and binding diverged | call `setRepo` to re-bind |
+| Commit `blocked` with `secrets[]` | scan found a secret/sensitive file | remove it (or move into `.env`), or `force` after review |
+| "Push rejected — \<repo\>" in Inbox | remote moved ahead / conflict | pull + resolve, then push again |
+| GitHub module shows "No changes" but files changed | `file.gitStatus` not reconciled | trigger `refreshGitStatus()` (Refresh button / `/github`) |
+| "committed locally — connect a GitHub PAT to push" | commit landed, no credentials to push | connect a PAT |
+| "Nothing to export yet..." | no clean product files found | add product source outside the internal dirs |
+
+---
+
+## 13. Related links 🌠
+
+- [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)
+- [✦ Back to the Docs index](./README.md)

package/docs/en/GOALS_SPECS_ISSUES.md

@@ -0,0 +1,303 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/GOALS_SPECS_ISSUES.md) · [✦ Constella](../../README.md)
+
+# Goals, Specs, Issues, Plans — The Work Constellation 🌌🪐
+
+![](../assets/divider-orbit.svg)
+
+The data model and state machines behind every unit of work. A **Goal** is an orbit; **Specs** are its charts; **Issues** are the manoeuvres; **Tasks** are the burns the engine actually fires; the **Plan** is the launch gate the operator opens. This page documents the real tables, columns, status enums and the transitions between them.
+
+## Short description
+
+Constella turns a brief into a structured, state-aware delivery pipeline: `Goal → Spec → Issue → Plan → Execution → Review → Test → Done`. The CEO agent (Ada) drafts specs and issues; the operator approves the plan; approved issues are *materialized* into executable tasks the runner picks up. Cancelling or archiving a goal cascades to its children so nothing settled keeps reading as pending.
+
+## When to use
+
+- You want to understand **what each entity is**, what columns it has and how rows relate.
+- You need the exact **status enums** and **kanban columns** for `goal`, `spec`, `issue`, `task` and `plan`.
+- You're debugging why a cancelled goal still shows pending work, or why a re-approved plan only created *some* tasks.
+- You want to know what the **SUPER-SPEC** is and when it is written.
+
+## How it works 🛰️
+
+Every entity is a row in the SQLite database (`src/db/schema.ts`), scoped to a `workspaceId` (one workspace per organization). The directory on disk is the source of truth for the human-readable artifacts (`specs/*.md`, `issues/*.md`, `specs/SUPER-SPEC.md`); the tables index them and carry the lifecycle state.
+
+The pipeline is driven by three modules:
+
+| Module | File | Responsibility |
+| --- | --- | --- |
+| Planner | `src/server/planner-core.ts` | `generatePlanFor` / `runPlanJob` / `planFromConversationFor` — the CEO drafts the Goal + specs + issues |
+| Plan ops | `src/server/plan-ops.ts` | `approvePlanFor` / `requestPlanChangesFor` / `setAuto247For` — the approval gate |
+| Work ops | `src/server/work-ops.ts` | `cancelGoalFor` / `archiveGoalFor` + cascade helpers — goal lifecycle |
+| Materialize | `src/server/materialize.ts` | `materializeTasks` — turn approved issues into executable `task` rows |
+
+All four are `server-only` cores keyed by an explicit `(orgId, workspaceId)`, so they can be called from a session action **or** from the channels with no session (the Telegram remote control, the public API).
+
+## Main flow 🌠
+
+```
+brief / DM "@ada build X"
+   └─ generatePlanFor → runPlanJob (Ada, detached, "planner" channel)
+        ├─ (first plan, existing project) analyzeExistingProject → specs/SUPER-SPEC.md
+        ├─ insert goal (from the MAIN/first spec)
+        ├─ insert spec rows  + write specs/SPEC-NN.md
+        ├─ insert issue rows + write issues/<key>.md   (col=todo, approved=false)
+        └─ push Inbox "Approve plan"
+   └─ operator approves → approvePlanFor
+        ├─ plan.approved=true, stage=6
+        ├─ issue.approved=true, spec.approved=true (active specs)
+        ├─ materializeTasks → one task per issue (idempotent)
+        └─ groom PO backlog
+   └─ Run 24/7 (plan.auto247=true) → runner pulls tasks → Review → Test → Done
+```
+
+## Key concepts 🕳️
+
+- **The Goal is born from the MAIN spec.** `runPlanJob` treats the first spec in the model's output as the main spec; the `goal.specId` points at it, and every drafted spec/issue gets the goal's id (`goalId`).
+- **Lifecycle is independent of the workflow column.** `spec.status` / `issue.status` (`active | cancelled | archived`) are *separate* from `issue.col` (the kanban lane). Cancelling a goal flips the children's `status`, never their `col`, so the board history survives.
+- **`approved` is a boolean, not a status.** A spec or issue can be `approved=true` while still `active`. The approval gate lives on the singleton `plan` row.
+- **Tasks are the only thing the runner executes.** Issues are plans; tasks are work. `materializeTasks` bridges them and is idempotent via `task.issueId`.
+- **Disk is the source of truth.** Spec/issue keys are renumbered to *continue* from existing ones so a second "New work" plan never overwrites `specs/SPEC-01.md` on disk.
+
+## Tables 🪐
+
+### `goal` — a unit of work (an orbit)
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `id` | text PK | |
+| `workspaceId` | text FK → workspace | indexed `goal_ws_idx` |
+| `title` / `description` | text | |
+| `ownerId` | text FK → agent | usually Ada (the CEO) |
+| `progress` | int | cached rollup 0–100, recomputed by the runner |
+| `parentId` | text | optional parent goal |
+| `status` | enum | `active \| cancelled \| archived \| done` (default `active`) |
+| `specId` | text | the **main** spec this goal was born from |
+| `archivePath` | text | ZIP path when archived |
+| `createdAt` / `updatedAt` / `doneAt` / `cancelledAt` / `archivedAt` / `reopenedAt` | timestamp | nullable lifecycle stamps |
+
+Provenance is tracked in `goal_file` (PK `goalId + path`, `op = created | edit`) so an archive ZIP can include *only* the files this goal produced.
+
+### `spec` — a chart
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `id` | text PK | |
+| `workspaceId` | text FK | |
+| `key` | text | e.g. `SPEC-01` (renumbered to continue from existing) |
+| `title` / `summary` / `body` | text | |
+| `authorId` | text FK → agent | the role the CEO assigned as author |
+| `approved` | bool | default `false` |
+| `goalId` | text | parent goal |
+| `status` | enum | `active \| cancelled \| archived` (default `active`) |
+| `createdAt` / `updatedAt` | timestamp | |
+
+### `issue` — a manoeuvre
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `id` | text PK | |
+| `workspaceId` | text FK | |
+| `specId` | text FK → spec | `onDelete: cascade` |
+| `goalId` | text | parent goal |
+| `key` | text | sequential, continuing from existing issues |
+| `title` | text | |
+| `prio` | enum | `low \| med \| high` (default `med`) |
+| `col` | enum | `todo \| doing \| blocked \| review \| done` (kanban lane, default `todo`) |
+| `moscow` | enum | `Must \| Should \| Could \| Won't` (derived from `prio`) |
+| `points` | int | story points (derived: high→8, med→5, low→3) |
+| `assigneeId` | text FK → agent | the role the CEO assigned |
+| `approved` | bool | default `false` |
+| `status` | enum | `active \| cancelled \| archived` (default `active`) |
+| `createdAt` / `updatedAt` | timestamp | |
+
+### `task` — an engine burn (the executable unit)
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `id` | text PK | |
+| `workspaceId` | text FK | |
+| `key` / `title` / `description` | text | |
+| `col` | enum | `triage \| todo \| doing \| blocked \| review \| done` (default `triage`) |
+| `prio` | enum | `low \| med \| high` |
+| `assigneeId` | text FK → agent | |
+| `goalId` | text FK → goal | |
+| `issueId` | text FK → issue | the issue it was materialized from (idempotency key) |
+| `createdBy` | enum | `operator \| agent` |
+| `createdAt` / `updatedAt` | timestamp | |
+
+Sub-steps live in `task_step` (`text`, `done`, `active`, `ord`) — seeded from the issue's `## Checklist` and the basis for live progress.
+
+### `plan` — the launch gate (one row per workspace)
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `workspaceId` | text **PK** | one plan per workspace |
+| `approved` | bool | default `false` |
+| `auto247` | bool | 24/7 autonomous execution toggle |
+| `stage` | int | pipeline stage marker (default `4`) |
+| `createdAt` / `updatedAt` | timestamp | |
+
+Note the difference in cardinality: there is exactly **one** `plan` row per workspace (PK is `workspaceId`), but **many** goals/specs/issues/tasks.
+
+## Entity relationships diagram
+
+```mermaid
+erDiagram
+    WORKSPACE ||--|| PLAN : "has one (gate)"
+    WORKSPACE ||--o{ GOAL : contains
+    GOAL ||--o{ SPEC : "parent of"
+    GOAL ||--o{ ISSUE : "parent of"
+    GOAL ||--o{ GOAL_FILE : "provenance"
+    SPEC ||--o{ ISSUE : "groups (cascade delete)"
+    ISSUE ||--o| TASK : "materialized into"
+    TASK ||--o{ TASK_STEP : "checklist"
+    GOAL ||--o| SPEC : "born from (specId)"
+    AGENT ||--o{ GOAL : owns
+    AGENT ||--o{ SPEC : authors
+    AGENT ||--o{ ISSUE : assigned
+    AGENT ||--o{ TASK : assigned
+```
+
+## Status transitions 🌠
+
+### Goal state machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> active : runPlanJob inserts goal
+    active --> done : all issues 100% (auto-complete, sticky)
+    active --> cancelled : cancelGoalFor
+    active --> archived : archiveGoalFor (ZIP)
+    cancelled --> active : reopenGoal
+    archived --> active : restoreGoal (re-extract ZIP)
+    done --> [*]
+```
+
+`progress` and `status` drift **only while active**. Once a goal settles (`done`/`cancelled`/`archived`) its `%` is sticky — a later blocked or added issue can't make a "Done" goal read 62%. Auto-completion is compare-and-set: only the first writer that still sees the goal `active` stamps `done` + `doneAt` (`src/server/progress.ts`).
+
+### Spec / Issue lifecycle (status) — cascades from the parent goal
+
+```mermaid
+stateDiagram-v2
+    [*] --> active
+    active --> cancelled : goal cancelled (setGoalChildrenStatus)
+    active --> archived : goal archived
+    cancelled --> active : goal reopened
+    archived --> active : goal restored
+```
+
+### Issue / Task kanban column (workflow, independent of status)
+
+```mermaid
+stateDiagram-v2
+    [*] --> triage : task default
+    triage --> todo
+    todo --> doing : runner claims
+    doing --> review : work done
+    doing --> blocked : parkGoalTasks / agent stuck
+    blocked --> todo : unparkGoalTasks
+    review --> done : QA sign-off
+    done --> [*]
+```
+
+> Issues use the columns `todo · doing · blocked · review · done`. Tasks add a leading `triage` lane.
+
+### Plan gate
+
+```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)
+```
+
+## Step-by-step 🚀
+
+1. **A brief arrives** — the standing workspace brief (`.claude/BRIEF.md`), a DM to `@ada`, or `/new-work` / `/new-goal`.
+2. **`generatePlanFor`** marks Ada `working` and kicks off `runPlanJob` detached on the persistent node server (streams to the `planner` channel).
+3. **First-plan analysis** (only when an existing project is present and not yet analyzed): `analyzeExistingProject` reads the project file-by-file and writes `specs/SUPER-SPEC.md`, then flags `settings.source.analyzed = true`.
+4. **Ada drafts** a single JSON object of `specs[]` + `issues[]`. The first spec is the **main** spec.
+5. **Persist** — insert the `goal` (title from `opts.goalTitle` / main spec / objective), then specs (keys renumbered to continue), then issues (`col=todo`, `points`/`moscow` derived from `prio`). Write `specs/SPEC-NN.md` and `issues/<key>.md` to disk.
+6. **Inbox + Telegram** — an `approval` inbox item (`refType=plan`) is pushed; if Telegram is configured, the plan is sent to the phone with Approve / Start execution / Review / Reject buttons.
+7. **Operator approves** (`approvePlanFor`): `plan.approved=true, stage=6`, issues + active specs flip `approved=true`, `materializeTasks` creates one task per un-materialized issue, and the PO backlog (`PO/backlog.md`) is groomed.
+8. **Run 24/7** (`setAuto247For(true)`) — the runner pulls `todo` tasks, advances them through `doing → review → done`, mirrors progress back onto issues and goals.
+9. **Cancel / archive** when needed — `cancelGoalFor` / `archiveGoalFor` stop everything and cascade the children's status.
+
+## Examples
+
+**New work from a DM** (handled by `planFromConversationFor` → `generatePlanFor`):
+
+```
+@ada build a billing dashboard with Stripe and a CSV export
+```
+
+**Approve from a slash command** ([CHAT_COMMANDS](./CHAT_COMMANDS.md)):
+
+```
+/approve          # approvePlanFor: approve plan/specs/issues + materialize tasks
+/run-247          # setAuto247For(true)
+/reject <reason>  # requestPlanChangesFor — back to Ada, stage rewinds to 1
+/cancel           # cancelGoalFor — stop + park, reopen later
+/archive          # archiveGoalFor — ZIP the goal's source + manifest
+```
+
+**Issue → task materialization** (`materializeTasks`, idempotent): re-approving after a re-plan creates tasks **only** for issues without a `task.issueId`, so existing work is never duplicated.
+
+## Possible states
+
+| Entity | Field | Values |
+| --- | --- | --- |
+| 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` |
+
+## The SUPER-SPEC 🌌
+
+When onboarding imports an existing project (a GitHub repo, a copied local directory, or an attached `mock/`), the **first** plan run does not draft blindly. `analyzeExistingProject` (`src/server/analyze.ts`) runs a real agent pass with the workspace as `cwd`, reads docs → manifests → source file-by-file, and writes `specs/SUPER-SPEC.md` with sections such as *Overview & purpose, Architecture & layers, Tech stack & dependencies, Directory / module map, Frontend, Backend, Data model & database, Auth & security, Integrations, Business rules & key flows, What is mock/stubbed vs real, Gaps to make it production-real*.
+
+The plan then reads the SUPER-SPEC in full and **extends** the existing system — it never scaffolds a second separate prototype. The analysis runs once per project (`settings.source.analyzed`).
+
+## Related integrations
+
+- **PO grooming** — on approve, every issue is copied into `backlog_item` (MoSCoW + points) and `PO/backlog.md` is rewritten. See [PO_AGENT](./PO_AGENT.md).
+- **Inbox** — the plan-approval decision surfaces as an actionable item (`refType=plan`). See [INBOX](./INBOX.md).
+- **Decisions log** — approve/cancel/archive each append a `decision` row. See [TEAM_ROOM](./TEAM_ROOM.md).
+- **Telegram remote** — the same session-less cores power `/approve`, `/cancel`, etc. from the phone. See [TELEGRAM](./TELEGRAM.md).
+- **Runner / execution** — tasks flow through review and test. See [WORKFLOW](./WORKFLOW.md), [TEST_DEV](./TEST_DEV.md).
+
+## Security 🔒
+
+- All lifecycle cores are `server-only` and keyed by an explicit `(orgId, workspaceId)` — **never** exposed as unauthenticated RPC endpoints. Every caller (session action, Telegram allowlist, public API PAT) must already be authorized for the workspace.
+- `ownGoal(wsId, goalId)` verifies the goal belongs to the workspace before any mutation.
+- Archive/restore ZIP extraction normalizes paths and refuses to write outside the workspace root (`abs !== root && !abs.startsWith(root + sep)`), part of the FS jail. See [SECURITY](./SECURITY.md).
+
+## Troubleshooting 🕳️
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Cancelled goal still shows pending issues | child `status` not cascaded | `cancelGoalFor` calls `setGoalChildrenStatus`; reopen + re-cancel if a row was edited directly |
+| Re-approve created no new tasks | all issues already have a `task.issueId` | expected — `materializeTasks` is idempotent; only new issues materialize |
+| "Done" goal stuck below 100% | sticky cached progress | by design once settled; reopen to recompute while `active` |
+| Plan won't approve | no `plan` row / specs not `active` | `approvePlanFor` only approves `spec.status = active`; ensure a plan exists |
+| Ada stuck "working", no plan | a prior job died before its `finally` | `generatePlanFor` self-recovers by checking the live `planner` event stream |
+| Second "New work" overwrote SPEC-01 | should not happen | keys are renumbered to continue from existing specs/issues on disk |
+
+## Related links
+
+- [WORKFLOW](./WORKFLOW.md) — the end-to-end execution ritual
+- [PO_AGENT](./PO_AGENT.md) — backlog grooming, story points, MoSCoW
+- [AGENTS](./AGENTS.md) — the roster (Ada is the CEO/planner)
+- [INBOX](./INBOX.md) — operator approvals and decisions
+- [CHAT_COMMANDS](./CHAT_COMMANDS.md) — `/approve`, `/cancel`, `/archive`, `/new-work`
+- [DM](./DM.md) — starting new work from a direct message
+- [TEAM_ROOM](./TEAM_ROOM.md) — where the CEO narrates the plan
+- [ARCHITECTURE](./ARCHITECTURE.md) — the data layer and sync engine
+- [TELEGRAM](./TELEGRAM.md) — remote control of the same cores