# 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`.
