pig/docs/build-plan.md

# 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, 261 unit tests across five packages plus a critical-path E2E suite,
green CI, 47 tables, 13 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 read-only chat
  server behind the API
- 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

---

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

---

## 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. Piggy writes.** Interactive chat is read-only by design for now. The
queue-side agent writes only to `facts`. A write path for the chat agent needs
the same evidence discipline plus a confirmation step, and should not be added
casually.

**7. Fill in `.env.example`.** `POSTGRES_PASSWORD` and
`PIG_SETTINGS_ENCRYPTION_KEY` are both load-bearing and both missing from it.
`ANTHROPIC_API_KEY` is declared in `apps/api/src/lib/config.ts` and read by
nothing — remove it or use it.

**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`. Pass **`reasoning_effort:
"none"`** for tool use, routing, extraction and classification — roughly one
second, terse output. Leave reasoning on only for genuine maths or logic, where
it arrives in a separate `reasoning_content` field while `content` stays clean.

**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: the model *name* is
  admin-selectable at runtime, the *host* is `PIGGY_INFERENCE_BASE` in the
  environment. What is untested is a customer pointing it at their own
  OpenAI-compatible endpoint.
- **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`.