# Build plan Where PIG stands, audited against the tree rather than against the last version of this document. The original plan was 24 tasks in three waves with real dependency edges, so that work could be handed to several people (or several agents) at once without them colliding. **Every one of those tasks has shipped.** What follows is the audit, then the work that is actually left — which is a different and shorter list, and mostly not new code. --- ## Where PIG stands Live at primeintellectgrowth.com. Around 45k lines of TypeScript including tests, 403 unit tests across five packages plus critical-path E2E suites (`apps/api/e2e`, `apps/piggy/e2e`), green CI, 47 tables, 15 migrations. - The ontology and margin engine, with the `allocations` join at the centre - Both pipelines; capacity availability, matching, holds and idle alerts - Write paths for accounts, contacts, both deal sides, commitments, allocations, holds, contracts, calendar entries and activities - RBAC: eleven capabilities resolved from team and role, enforced on every write and shared with the browser — see the caveat under **Left to do** - Auth: Supabase or any OIDC provider behind one interface; invite-gated registration, profile creation, sign-out - Import: CSV and .xlsx with mapping, dry-run preview and idempotent commit; Notion and Google Sheets as OAuth sources onto the same mapping step - Piggy: lease-based queue worker with `SKIP LOCKED` claims, renewable leases, capped exponential backoff and `agent_runs`; plus a private chat server behind the API, running Prime Agent (`@earendil-works/pi-coding-agent`) over the CRM tools with no shell, filesystem or Python, and a write surface that proposes before it writes — see AGENTS.md §6 - MCP server (9 tools, stdio), `pig` CLI, Prime Intellect client, demo dataset - Slack and Buzz notification adapters behind one notifier interface - Growth (customer lifecycle projection) and the GTM calendar - Docker, Compose, Caddy, `deploy.sh` with rollback, and tag-to-ship CD — including Piggy, which ships and rolls back with the app when `PIGGY_ENABLED` is on rather than being started by hand --- ## Audit of the original plan Verified by reading the tree on 2026-08-13. Every row was checked; none was believed on the strength of the previous version of this file. ### Wave 0 — Foundation | | Task | Status | |---|---|---| | **F1** | shadcn primitive set | **Done.** 22 primitives in `apps/web/src/components/ui`, including everything the plan listed | | **F2** | Shared API write-path convention | **Done.** `apps/api/src/lib/mutation.ts` — ontology-derived zod schemas, one transaction per write, automatic activity logging, consistent error shape | | **F3** | RBAC | **Done.** `packages/core/src/permissions.ts` — eleven capabilities, ranked roles, shared by API and browser. Reads were added later and are *not yet enforced*; see below | ### Wave 1 | | Task | Status | |---|---|---| | **A1** | Allocation + commitment write API | **Done.** `routes/capacity-writes.ts`, availability invariant enforced server-side | | **A2** | API keys | **Done.** `routes/api-keys.ts` — mint, list, revoke; plaintext shown once | | **A3** | Auth-provider seam | **Done.** `lib/auth-provider.ts`; OIDC is a full second implementation, not a stub | | **A4** | Piggy | **Done.** `apps/piggy` — worker, queue, provider, tools. See the gap on task kinds below | | **A5** | Slack adapter | **Done.** `routes/slack.ts` + `services/slack.ts`; signed-request verification, channel links, capacity slash command | | **A6** | Buzz adapter | **Done.** `routes/buzz.ts`, same notifier interface, mounted only when `BUZZ_RELAY_URL` is set | | **A7** | `pig` CLI | **Done.** `apps/cli` — `me`, `accounts`, `deals`, `commitments`, `allocations`, `capacity`, with `--json` | | **A8** | Data table + ⌘K palette | **Done.** `components/DataTable.tsx`, `components/CommandPalette.tsx` | | **A9** | `SourcedValue` + fact review | **Done.** `components/SourcedValue.tsx`, `pages/FactReview.tsx`, `routes/facts.ts` | | **A10** | Contracts UI | **Done.** `pages/Contracts.tsx` over `contracts`, `sla_terms`, `sla_metric_targets`, `contract_obligations` | | **A11** | Record create/edit sheets | **Done.** `components/RecordSheets.tsx` | | **A12** | Capacity tiers | **Done.** `SECURITY_TIERS = ['government', 'secure_cloud', 'community_cloud']` with a rank comparison, so a requirement is satisfied only from at or above its tier | | **A13** | Admin settings | **Done.** `routes/admin-settings.ts`, `components/AdminSettings.tsx` | | **A14** | Import framework | **Done.** `routes/imports.ts`, `services/tabular-import.ts` — CSV and .xlsx, mapping, preview, idempotent commit, gated on `data:import` | | **A15** | Notion import | **Done.** `routes/notion-import.ts` | | **A16** | Google Sheets import | **Done.** `routes/google-sheets.ts` | ### Wave 2 | | Task | Status | |---|---|---| | **B1** | Allocation UI | **Done.** `components/AllocationSheet.tsx`, reachable from the matcher | | **B2** | Piggy chat UI | **Done.** `components/PiggyChat.tsx` + `PiggyDock.tsx`, streaming with separate reasoning and tool-call events | | **B3** | Slack/Buzz connection settings | **Done.** `components/IntegrationSettings.tsx`, `routes/integration-settings.ts` | | **B4** | Critical-path E2E | **Done.** `apps/api/e2e/critical-path.test.ts`, run by CI against a real Postgres | ### Built since, and not in the original plan | Feature | Where | |---|---| | Read-authorisation policy table and governance test | `routes/read-guards.ts`, `lib/read-guard.ts` — **written, tested, not mounted** | | GTM calendar: thirteen event kinds across nine tables, three-month timeline | `routes/calendar.ts`, `services/calendar.ts`, `pages/Calendar.tsx`. This is what finally surfaced `export_authorizations` and `compliance_artifacts`, which had indexed `expires_at` columns and no UI at all | | Growth / customer lifecycle projection | `services/customer-lifecycle.ts`, `pages/Growth.tsx` | | Learn: member curriculum plus a code-gated public track | `routes/learn.ts` (**not mounted**), `pages/Learn.tsx` | | HubSpot: OAuth, connections, sync jobs, webhooks, seven tables | `routes/hubspot.ts`, `routes/hubspot-webhook.ts` (**neither mounted**) | | Notification outbox | `services/notification-outbox.ts` | | Tag-to-ship CD with a host-side release poller and rollback | `.gitea/workflows/ci.yml`, `scripts/autodeploy.sh`, `deploy/pig-autodeploy.*` | | Three-pane application shell with a docked agent | `components/Shell.tsx`, `AppHeader.tsx`, `AppSidebar.tsx` | | Piggy re-platformed onto Prime Agent, embedded as a Node library with `noTools: 'all'` and an allowlist | `apps/piggy/src/agent/*` — session, models.json, prompt, tool bridge | | Piggy writes, behind an approval rendezvous, as the calling user's own principal | `apps/piggy/src/write-tools.ts`, `chat-server.ts`, `packages/core/src/piggy-protocol.ts` | | Persisted conversations and the `/piggy` workspace | `piggy_conversations` + `piggy_messages` (migration 0014), `routes/piggy-conversations.ts`, `pages/Piggy.tsx` | --- ## Left to do In rough order of value. The first four are all "wire up something that already exists", which is a strange shape for a backlog and worth taking seriously because that is exactly the kind of work that stays undone. **1. Mount `createReadGuardRoutes`.** The read half of the permission model — `book:read`, `economics:read`, `team:read` — has a policy table, middleware, and a governance test that fails when a GET appears with no rule covering it. None of it runs, because `app.ts` never mounts it. Until it does, any authenticated member reads supplier cost, break-even price and every margin total regardless of team or role. Registration order is load-bearing: Hono runs matched handlers in the order they were registered, so the guard must be mounted before the handlers it guards. **2. Mount `learn.ts`.** `/learn` is in the navigation and every one of its API paths answers 404. **3. Enqueue the other six agent task kinds.** `AGENT_TASK_KINDS` declares eight. Only `enrich_account` and `enrich_contact` are ever written to `agent_tasks`, both from record creation in `routes/records.ts`. `write_brief`, `match_capacity`, `detect_idle_capacity`, `summarise_pipeline`, `watch_renewal` and `research_supplier` have no producer anywhere. The worker is generic and complete; the gap is entirely on the enqueue side, and each one is a few lines in the service that already computes the underlying answer. **4. Mount the HubSpot routes, or delete them.** Seven `hubspot_*` tables, an OAuth flow, sync cursors, jobs and a verified webhook endpoint, all written, all tested, all unreachable. Whichever way this goes it should not stay in this state — dead-but-tested code reads as shipped to anyone grepping the repo. **5. Row-level or team-scoped reads.** Every read returns the whole book. This is why read capabilities are platform-wide, and it is the honest reason the permission model says so out loud. It is also the thing to build before PIG serves a company where that is not acceptable. **6. What is left on Piggy, now that it writes.** The chat agent has five write tools, each running through `executeMutation` as the calling user, and a proposal-and-approval step in `confirm` mode. Four things remain: - **A stage change Piggy makes raises no Slack notification.** The API route passes a `NotificationOutbox` into `updateDemandDealMutationDefinition`; `apps/piggy/src/write-tools.ts` does not, because the outbox is wired in the API server and Piggy runs in its own process. A move made in chat is therefore silent in Slack. Known gap, not a decision. - **No tool creates a guarded kind yet.** `requiresApproval` stops contracts, commitments, allocations and compliance in every mode, and nothing currently proposes one, so that rule is enforced and unexercised. Whoever adds the first such tool should read `packages/core/src/piggy-protocol.ts` before writing a line of it. - **The queue worker is still on the hand-rolled provider.** `apps/piggy/src/provider.ts` speaks OpenAI-completions directly; only the chat path runs on Prime Agent. Two model paths, two budgets, two sets of environment variables. - **`PIGGY_ENABLED` is `false` in production.** Everything above is shipped and switched off; turning it on is `.env` plus a deploy. **7. `ANTHROPIC_API_KEY` is declared in `apps/api/src/lib/config.ts` and read by nothing** — remove it or use it. (`POSTGRES_PASSWORD` and `PIG_SETTINGS_ENCRYPTION_KEY` were missing from `.env.example`, which made the documented `cp .env.example .env` fail at the first compose command. Both are in it now, along with every Piggy key.) **8. A remote MCP transport.** The server is stdio only; there is no Streamable HTTP transport and no `/mcp` endpoint on the API, so every user runs the server locally. The package is also unpublished, so `npx @pig/mcp` does not work and the documented install command has to be a path into a clone. Not started at all, and deliberately: email or calendar ingestion, forecasting, quota and attainment, invoicing or billing reconciliation, multi-tenancy, and any native mobile application. --- ## On the component library Three gaps were identified in an early review of the front end. All three have since been acted on. **The primitive set was too thin — 9 at the time.** PIG now has 22, including the ones that mattered: `data-table`, `command`, `sheet`, `drawer`, `sidebar`, `form`. The agent-chat compositions (`message`, `reasoning`, `thinking-indicator`) are ours, written inside `PiggyChat.tsx`. **`SourcedValue` / `Provenance` had to exist** — a dotted underline on any agent-derived value, with a tooltip carrying the claim, the reasons, when it was observed and the source URL. PIG already held that data in `facts` and surfaced none of it. It does now. **Mobile is a lead, and the ratio has held:** PIG is 63 `.tsx` files with safe-area handling, a bottom tab bar, a sidebar Sheet and a hard rule that no route may scroll sideways at 393px. Most tools in this category are effectively desktop-only. **Where a primitive is a shadcn/ui original, install it from upstream**, where it is canonical and current — not lifted out of somebody else's repository. Compositions we write ourselves. --- ## Prime Intellect API — verified facts Confirmed against the live API, not assumed. **Two different hosts.** `api.primeintellect.ai` is the compute/pods API (availability, pods, billing). Inference is `api.pinference.ai/api/v1`, which is OpenAI-compatible (`/chat/completions`, `/models`, and an Anthropic-style `/messages`). PIG's config carries both separately — `PRIME_API_BASE` and `PIGGY_INFERENCE_BASE`. **`prices.onDemand` is the TOTAL FOR THE NODE, not per-GPU.** Verified: datacrunch lists 1× A100 at 1.79 and 2× A100 at 3.58. `gpuMemory` is likewise a node total (640 for 8× 80GB). This was a real bug — an 8-GPU node read eight times too expensive — and is **fixed**: `packages/prime/src/map.ts` divides both by `gpuCount` at the boundary and keeps the node totals in `raw` for reconciliation. Anything new that reads an upstream price must do the same. **Piggy's default model:** `nvidia/nemotron-3-nano-30b-a3b` ($0.05/$0.20 per Mtok). It is a *hybrid reasoning* model that thinks aloud by default and will ramble or truncate under a tight `max_tokens`. It needs **`reasoning_effort: "none"`** for tool use, routing, extraction and classification — roughly one second, terse output. Measured on the agent path: with the harness's default thinking level the same question cost 6,195 output tokens and returned an empty answer; with the effort pinned to `none` it cost 149. On the agent path that parameter is not passed by hand — it comes from the `thinkingLevelMap` on the model entry in `apps/piggy/src/agent/models.json`, and a model without one sends no reasoning parameter at all. Read **AGENTS.md §6.5** before changing `PIGGY_AGENT_MODEL` or `PIGGY_AGENT_THINKING`. **Billing** is pay-as-you-go against a shared balance, not a per-model whitelist. Check with `GET /api/v1/billing/wallet`. **The user-agent concern did not reproduce** — both a browser UA and PIG's own returned 200. Worth remembering it was once an issue if a 403 ever appears. ## Open questions - **Which inference host for on-prem?** Settled in shape, but no longer one answer. The **queue worker** reads `PIGGY_MODEL` and `PIGGY_INFERENCE_BASE` from the environment at boot. The **chat agent** reads its base URL and its five models from `apps/piggy/src/agent/models.json`, which is compiled into the image, so pointing it at another OpenAI-compatible endpoint means editing that file rather than setting a variable. Nothing is read from `platform_settings` on either path. What the user *can* choose at runtime is which of the five models answers, and the mode — both ride on the request rather than on configuration. A customer pointing either at their own endpoint is still untested. - **Who may import?** Currently team admins and platform admins (`data:import`, minimum role `admin`, all teams). Easy to loosen, unpleasant to tighten after the fact. - **Which key does PIG get?** The existing Prime Intellect key is broad and never expires. PIG's sync should hold a separate one scoped to `Availability → Read`.