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, 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.