claude
99d165b5e5
Piggy answered in raw markdown, threw away every tool result it streamed, and fought the reader's scroll on every token. The three surfaces that made it worth having — what it read, how it reasoned, what it cost — were all on the wire and none of them reached the screen. The transcript is now composed of five parts under components/piggy: answers render through streamdown, the container sticks to the bottom without pinning the reader there, tool steps say what they read and link to the record, and each turn carries its model and token count. Three lifecycle bugs went with them: Stop left a permanent spinner, a truncated stream was indistinguishable from thinking, and a failed send destroyed the message it failed to send. Underneath, the inference path grew timeouts, jittered retries on 429 and 5xx, tolerance of the malformed frames a 30B model emits, and an agent_runs row per turn so chat spend is observable. The system prompt now states that a field ending in Cents is cents — without it nemotron renders costPerGpuHourCents: 189 as "$189 per GPU-hour", which is a 100x error on the most scrutinised number in the room. The demo book was arithmetically incoherent: every deal's value contradicted its own allocation revenue by up to 3.6x, nothing had ever closed, no customer had any paper, and the marketplace was empty. Deal value is now derived from the allocation, the book clears 5.3% across five blocks with one deliberately underwater, and the renewal, compliance and agent-provenance machinery finally has rows to act on. A --clear that deleted every obligation, SLA term and capacity request in the database regardless of origin is scoped to the demo's own ids. Around that: accounts have a detail page, ⌘K searches the book, Settings can mint the API keys it always claimed to, and deploy.sh actually ships the agent instead of silently skipping its compose profile. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
228 lines
13 KiB
Markdown
228 lines
13 KiB
Markdown
# 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 —
|
||
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` |
|
||
|
||
---
|
||
|
||
## 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. `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`. 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: both the model and
|
||
the host are environment values — `PIGGY_MODEL` and `PIGGY_INFERENCE_BASE`,
|
||
read once at Piggy's boot. Nothing about the agent is selectable at runtime;
|
||
`apps/piggy` never reads `platform_settings`, so a change means editing `.env`
|
||
and restarting the container. What is untested is a customer pointing the base
|
||
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`.
|