@terreno/mcp 57.0.0-beta.1 → 57.1.0

package/src/docs/versioned/next/implementationPlans/comms-abstraction.md

@@ -1,14 +1,18 @@
 # Implementation Plan: Pluggable communications layer (@terreno/comms)
 
-**Status:** Draft
+**Status:** Approved — Phase 1 gap-fill implemented
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1018
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned
 **Created:** 2026-08-09
+**Approved:** 2026-08-20
 **Program:** [B2B platform](b2b-platform-program.md)
 **Depends on:** none (inbound-webhooks is needed only by adapter delivery-callback phases)
 **RTK deprecation flag:** None — backend-only package
+**Shipped:** Phases 2–3 and most of Phase 1 in #1037; SendGrid adapter in #1050 (separate IP)
+**Remaining:** none — Phase 1 gap-fill landed on this branch
+**Research:** [comms-abstraction-research.md](comms-abstraction-research.md)
 
 ## Goal
 
@@ -26,14 +30,16 @@ consumer apps install only the SDKs they use.
 
 ## Non-Goals
 
-- Any concrete provider SDK integration (see `comms-adapter-*` IPs).
+- Any concrete provider SDK integration (see `comms-adapter-*` IPs). The SendGrid adapter
+  already lives at `@terreno/comms/adapters/sendgrid` under that IP; this IP does not own it.
 - In-app notification center, inbox UI, or user notification preferences
   (`notification-center` item).
 - Password reset / email verification flows (`password-reset-and-email-verification` item
   — a consumer of this layer).
-- Inbound webhook handling (`inbound-webhooks` item); this IP only defines the
-  `DeliveryEvent` type adapters will feed from callbacks.
+- Inbound webhook HTTP handling (`inbound-webhooks` item); this IP ships
+  `recordDeliveryEvent` / `recordOptOut` for adapters to call once those webhooks land.
 - Broadcast/bulk campaign tooling.
+- Admin retry UI and rich explorer filters ([comms-admin-dashboard](comms-admin-dashboard.md)).
 
 ## Decisions
 
@@ -48,6 +54,13 @@ consumer apps install only the SDKs they use.
 | Consumer lifecycle hooks | `CommsApp` options expose `beforeSend` / `onSend` / `onError` / `onRetry` / `onOptOut` / `onDeliveryEvent`. Hooks are awaited but wrapped: a throwing hook is logged (`logger.error`) and never breaks the send. `beforeSend` may mutate or cancel |
 | Error taxonomy | Every `SendResult` failure carries `errorCode` (provider-native code as a string) and `errorClass` (`"permanent"` \| `"transient"` \| `"config"`). Adapters own the mapping; the facade uses `errorClass` to decide its single inline retry (transient only) and the admin dashboard uses it to gate manual retries |
 | Payload retention | `retainPayloadDays` option (default 30) keeps the rendered message on the `CommsMessage` row (post `redactPayload` hook) so the admin dashboard can retry; a TTL-style cleanup clears expired payloads |
+| `onRetry` signature (published) | Keep shipped `(context, result: SendResult)`. Put 1-based `attempt` on `CommsHookContext` (2 = the inline retry). Do not change the callback to `(context, attempt)` |
+| Provider throws | Facade never rethrows from `sendMail` / `sendSms` / `sendPushToUser` / `startVerification` / `checkVerification`. A throwing provider becomes `errorClass: "transient"`, `errorCode: "provider-throw"`, then follows the same retry rules |
+| Push retry | Retry **only tokens** whose first `SendResult` is `errorClass: "transient"` via a second `sendPush`; merge. Do not re-send accepted tokens |
+| Push prune | Deactivate when `errorClass === "permanent"` **or** `isPermanentFailure === true` (shipped alias; adapters may set both) |
+| Delivery / opt-out intake | `CommsService.recordDeliveryEvent` / `recordOptOut` update the matching log row (by `providerMessageId`) and invoke hooks. Missing rows: `logger.warn`, still fire the hook |
+| Payload expiry | `payloadExpiresAt` on the row. Mongo TTL indexes must **not** be used (they would delete the log). `CommsMessage.clearExpiredPayloads()` unsets `payload` only; `logSend` / `appendAttempt` call it best-effort (limit 50) |
+| `checkVerification` | Log a verification row; no inline retry; never persist the code |
 
 ## Architecture
 
@@ -56,12 +69,12 @@ consumer apps install only the SDKs they use.
   src/
     types.ts            # Provider interfaces + message/result types
     commsApp.ts         # CommsApp TerrenoPlugin
-    commsService.ts     # sendMail/sendSms/sendPush/startVerification/checkVerification
+    commsService.ts     # send* + recordDeliveryEvent/recordOptOut
     models/
       commsMessage.ts   # Delivery log
       pushToken.ts      # Device push token registry
     routes/
-      pushTokens.ts     # modelRouter for token registration
+      pushTokens.ts     # custom upsert/list/deactivate + owner read
       commsExplorer.ts  # Admin-only delivery log explorer
     adapters/
       console.ts        # Dev adapters for all four channels
@@ -71,26 +84,39 @@ consumer apps install only the SDKs they use.
 ### Provider interfaces (types.ts)
 
 ```typescript
+export type CommsErrorClass = "config" | "permanent" | "transient";
+export type CommsChannel = "mail" | "push" | "sms" | "verification";
+export type CommsMessageStatus =
+  | "bounced"
+  | "cancelled"
+  | "delivered"
+  | "failed"
+  | "sent";
+
 export interface SendResult {
   providerMessageId?: string;
   accepted: boolean;
   error?: string;
-  errorCode?: string;                              // provider-native code, e.g. "21610", "sendgrid-400"
-  errorClass?: "permanent" | "transient" | "config"; // drives retry eligibility
+  errorCode?: string;
+  errorClass?: CommsErrorClass;
+  isPermanentFailure?: boolean; // alias: treat as errorClass "permanent" when that is unset
+  metadata?: Record<string, unknown>;
 }
 
 export interface MailMessage {
   to: string | string[];
-  from?: string;            // default from CommsApp options
+  from?: string;
   subject: string;
   text?: string;
   html?: string;
   replyTo?: string;
+  templateId?: string;
+  dynamicTemplateData?: Record<string, unknown>;
   metadata?: Record<string, string>;
 }
 
 export interface MailProvider {
-  readonly id: string;      // "console" | "sendgrid" | ...
+  readonly id: string;
   sendMail(message: MailMessage): Promise<SendResult>;
 }
 
@@ -110,7 +136,7 @@ export interface PushMessage {
 
 export interface PushProvider {
   readonly id: string;
-  sendPush(message: PushMessage): Promise<SendResult[]>; // one per token
+  sendPush(message: PushMessage): Promise<SendResult[]>; // one per token, same order
 }
 
 export interface VerificationProvider {
@@ -126,29 +152,34 @@ export interface DeliveryEvent {
   channel: "mail" | "sms" | "push";
   providerMessageId: string;
   status: "delivered" | "bounced" | "failed" | "opened";
-  errorCode?: string;   // provider failure code from the callback, when present
+  errorCode?: string;
+  errorClass?: CommsErrorClass;
   raw?: unknown;
 }
 
 export interface CommsHookContext {
-  channel: "mail" | "sms" | "push" | "verification";
+  channel: CommsChannel;
   provider: string;
-  message: MailMessage | {to: string; body: string} | PushMessage;
+  message?: MailMessage | {to: string; body: string} | PushMessage | {
+    to: string;
+    channel: "sms" | "email";
+  };
   userId?: string;
-  isRetry: boolean;     // true for facade inline retries and admin-dashboard retries
-  messageId?: string;   // CommsMessage._id once the log row exists
+  isRetry: boolean;
+  attempt: number;          // 1 = first provider call, 2 = inline retry
+  messageId?: string;       // CommsMessage._id once the log row exists
 }
 
 export interface OptOutEvent {
   channel: "mail" | "sms";
   to: string;
   provider: string;
-  reason: string;       // e.g. "sms-stop", "unsubscribe", "spam-report"
+  reason: string;           // e.g. "sms-stop", "unsubscribe", "spam-report"
   raw?: unknown;
 }
 ```
 
-Verification start attempts store `metadata.verificationChannel` while recipient values remain
+Verification start attempts store `metadata.verificationChannel`. Recipients stay
 redacted. Verification codes are never persisted.
 
 ### CommsApp (TerrenoPlugin)
@@ -159,18 +190,17 @@ export interface CommsOptions {
   sms?: SmsProvider;
   push?: PushProvider;
   verification?: VerificationProvider;
-  defaultFrom?: string;                       // mail from fallback
-  logMessages?: boolean;                      // default true → CommsMessage
-  retainPayloadDays?: number;                 // default 30; 0 disables retention (and admin retry)
-  redactPayload?: (context: CommsHookContext, payload: unknown) => unknown; // before storage
+  defaultFrom?: string;
+  logMessages?: boolean;                      // default true
+  retainPayloadDays?: number;                 // default 30; 0 stores no payload
+  redactRecipients?: boolean;                 // default true — `to` at rest
+  redactPayload?: (context: CommsHookContext, payload: unknown) => unknown;
 
-  // Lifecycle hooks — all optional, all awaited, all wrapped so a throwing
-  // hook is logged and never breaks (or blocks) the send itself.
   beforeSend?: (context: CommsHookContext) =>
     Promise<{cancel?: boolean; message?: CommsHookContext["message"]} | void>;
   onSend?: (context: CommsHookContext, result: SendResult) => Promise<void>;
   onError?: (context: CommsHookContext, result: SendResult) => Promise<void>;
-  onRetry?: (context: CommsHookContext, attempt: number) => Promise<void>;
+  onRetry?: (context: CommsHookContext, result: SendResult) => Promise<void>;
   onOptOut?: (event: OptOutEvent) => Promise<void>;
   onDeliveryEvent?: (event: DeliveryEvent) => Promise<void>;
 }
@@ -181,10 +211,10 @@ new TerrenoApp({userModel: User})
 ```
 
 `CommsApp.register()` mounts the push-token routes and admin explorer;
-`getCommsService()` (module-level accessor, mirroring how `FeatureFlagsApp` exposes
-evaluation) gives routes and other plugins `sendMail` / `sendSms` / `sendPushToUser` /
-`startVerification` / `checkVerification`. `sendPushToUser(userId, message)` resolves the
-user's active `PushToken`s and prunes tokens the provider reports dead.
+`getCommsService()` (module-level accessor) gives routes and other plugins `sendMail` /
+`sendSms` / `sendPushToUser` / `startVerification` / `checkVerification` /
+`recordDeliveryEvent` / `recordOptOut`. `sendPushToUser(userId, message)` resolves the
+user's active `PushToken`s and prunes tokens the provider reports permanently dead.
 
 Unconfigured channel behavior: in production, throw `APIError({status: 501, title:
 "Comms channel not configured"})`; in development, fall back to the console adapter with a
@@ -192,22 +222,54 @@ Unconfigured channel behavior: in production, throw `APIError({status: 501, titl
 
 ### Hook order and semantics
 
-For every send (including retries) the facade runs:
+For every send (including the inline retry) the facade runs:
 
-1. `beforeSend` — may replace the message (`{message}`) or cancel (`{cancel: true}`,
-   logged as a `CommsMessage` with status `cancelled`). The consuming app uses this for
-   quiet hours, per-user notification preferences, and suppression lists.
-2. Provider `send*` → on transient failure (`errorClass: "transient"`), `onRetry` fires
-   and the facade retries once inline.
+1. `beforeSend` — once, **before the first** provider call. May replace the message
+   (`{message}`) or cancel (`{cancel: true}` → `CommsMessage` with `status: "cancelled"`,
+   no provider call). Quiet hours, preferences, and suppression lists use this hook.
+2. Provider `send*` → on `errorClass: "transient"` (or a wrapped provider throw),
+   `onRetry(context, failedResult)` fires with `context.attempt === 2` and `isRetry: true`,
+   then the facade retries once.
 3. `onSend` (accepted) or `onError` (final failure) — `onError` receives the full
-   `SendResult` (`errorCode`, `errorClass`) so apps can alert, escalate, or mark domain
-   objects without polling the delivery log.
-4. Asynchronously, adapters feed `onDeliveryEvent` (delivery callbacks) and `onOptOut`
-   (STOP replies, unsubscribes, spam reports) once their webhook phases land.
+   `SendResult`.
+4. Later, adapters call `recordDeliveryEvent` / `recordOptOut`, which fire
+   `onDeliveryEvent` / `onOptOut`.
+
+`checkVerification` skips `beforeSend` and inline retry. It still logs and fires
+`onSend` / `onError`.
 
 Hooks are observation and shaping points, not error channels: exceptions thrown inside a
-hook are caught, logged with `logger.error`, and recorded in `CommsMessage.metadata` —
-they never change the send outcome.
+hook are caught, logged with `logger.error`, and recorded in `CommsMessage.metadata.hookErrors`
+— they never change the send outcome. A throwing `beforeSend` is treated as “no mutation,
+do not cancel.”
+
+### Attempt logging
+
+One `CommsMessage` row per send invocation (not per retry):
+
+1. After attempt 1, `logSend` creates the row (`attempts[0]`, `attemptCount: 1`).
+2. After the inline retry, `appendAttempt` pushes `attempts[1]` and updates top-level
+   `status`, `error`, `errorCode`, `errorClass`, `providerMessageId`, `attemptCount`,
+   `lastAttemptAt`.
+3. Cancelled sends create a row with `status: "cancelled"`, empty `attempts`, no provider.
+
+`logSend` and `appendAttempt` never throw.
+
+### Payload stored per channel
+
+After `redactPayload` (identity if unset), when `retainPayloadDays > 0`:
+
+| Channel | `payload` |
+|---|---|
+| mail | `{to, from, subject, text, html, replyTo, templateId, dynamicTemplateData}` |
+| sms | `{to, body}` |
+| push | `{title, body, data, badge, sound}` (tokens omitted) |
+| verification start | `{channel}` only |
+| verification check | none |
+| cancelled | the mutated-or-original message, same shape as the channel |
+
+`payloadExpiresAt = now + retainPayloadDays`. Expired payload is treated as absent for
+retry even before cleanup runs.
 
 ## Models
 
@@ -216,7 +278,7 @@ and live per the five-type pattern (`CommsMessageDocument`, etc.).
 
 **PushToken** — `userId` (ref User, required, indexed), `token` (string, required, unique),
 `platform` ("ios" | "android" | "web"), `deviceId` (string, optional), `active` (boolean,
-default true), `lastSeenAt` (date).
+default true), `lastSeenAt` (date). Shipped.
 
 **CommsMessage** — `channel` ("mail" | "sms" | "push" | "verification"), `provider`
 (string), `to` (string, redacted-at-rest for sms/mail per option), `subject` (string,
@@ -224,11 +286,12 @@ optional), `userId` (ref User, optional), `status` ("sent" | "failed" | "deliver
 "bounced" | "cancelled"), `providerMessageId` (string, indexed), `error` (string,
 optional), `errorCode` (string, indexed), `errorClass` ("permanent" | "transient" |
 "config"), `templateId` (string, optional), `attempts` (array of `{at, provider,
-providerMessageId, errorCode, error}` — one entry per facade attempt including the inline
-retry), `attemptCount` (number), `lastAttemptAt` (date), `retriedFromId` / `retriedById`
-(ref CommsMessage — links between an original and its admin-dashboard retries), `payload`
-(Mixed, retained per `retainPayloadDays` after `redactPayload`, cleared on expiry),
-`metadata` (Mixed). Static `logSend()` mirrors `AIRequest.logRequest`.
+providerMessageId, errorCode, errorClass, error}` — one entry per facade attempt including
+the inline retry), `attemptCount` (number), `lastAttemptAt` (date), `retriedFromId` /
+`retriedById` (ref CommsMessage — written later by admin-dashboard retries; schema exists
+now), `payload` (Mixed, retained per `retainPayloadDays` after `redactPayload`, cleared on
+expiry), `payloadExpiresAt` (date), `metadata` (Mixed). Statics: `logSend()`,
+`appendAttempt()`, `clearExpiredPayloads()`.
 
 These fields exist so the [comms-admin-dashboard](comms-admin-dashboard.md) IP can filter
 on error codes/classes, show per-attempt history, and re-send from the retained payload
@@ -250,6 +313,8 @@ The explorer uses `createOpenApiBuilder`, modeled on `addAiRequestsExplorerRoute
 deliberately minimal here — the [comms-admin-dashboard](comms-admin-dashboard.md) IP upgrades it
 with error-code/class filtering, free-text search, a detail route, stats, and retry endpoints.
 
+No HTTP routes for `recordDeliveryEvent` / `recordOptOut` in this IP.
+
 ## Notifications
 
 None beyond the feature itself.
@@ -263,14 +328,18 @@ None in this IP. example-frontend gains a settings row that registers the Expo p
 
 1. **Package + contracts:** `@terreno/comms` package scaffold, `types.ts`, console
    adapters, `CommsMessage` + logging, `commsService`, unit tests.
+   **Shipped** including dashboard-ready fields, hooks, payload retention, and
+   channel-wide transient retry.
 2. **CommsApp + routes:** plugin registration, `PushToken` model + routes, admin explorer,
-   OpenAPI, supertest coverage.
+   OpenAPI, supertest coverage. **Shipped.**
 3. **Integration:** example-backend registers `CommsApp` (console adapters), seed docs,
    `docs/reference/comms.md`, catalog entries, publish wiring in `publish-on-tag.yml`.
+   **Shipped.**
 
 ## Feature Flags & Migrations
 
-None. New collections only; no existing data touched.
+None. New collections only; no existing data touched. Remaining schema fields are additive
+on `CommsMessage` (`cancelled` status value, `attempts`, payload fields, retry refs).
 
 ## Activity Log & User Updates
 
@@ -280,7 +349,8 @@ updates.
 ## Not Included / Future Work
 
 - Adapter IPs: `comms-adapter-expo-push`, `comms-adapter-twilio-sms`,
-  `comms-adapter-twilio-verify`, `comms-adapter-sendgrid`.
+  `comms-adapter-twilio-verify`, `comms-adapter-sendgrid` (Phase 1 of SendGrid already
+  shipped).
 - Admin operations dashboard (rich filtering, log digging, manual retries) —
   [comms-admin-dashboard](comms-admin-dashboard.md); this IP only ships the fields and
   hooks it needs.
@@ -288,15 +358,20 @@ updates.
   point they will plug into).
 - Queue-backed sending with automatic scheduled retries — arrives with `job-queues`;
   until then sends are inline with one transient-error retry plus manual admin retries.
+- Webhook HTTP for delivery callbacks — `inbound-webhooks` plus adapter Phase 2.
 
 ## Files to Create / Modify
 
-- `comms/` (new workspace package: `package.json`, `tsconfig.json`, `biome.jsonc`, `src/*`
-  as in Architecture)
-- Root `package.json` — workspace entry + scripts (`comms:compile|lint|test`)
-- `example-backend/src/server.ts` — register `CommsApp`
-- `docs/reference/comms.md`, `.cursor/rules/comms/00-comms.mdc` (via rulesync)
-- `.github/workflows/publish-on-tag.yml`, new `comms-ci` workflow
+Remaining roast (gap-fill):
+
+- `comms/src/types.ts`, `commsService.ts`, `models/commsMessage.ts`, `modelTypes.ts`
+- Tests for hooks, retry-per-channel, attempts, payload expiry
+- `docs/reference/comms.md`, `.rulesync/rules/comms/00-comms.md` (then `bun run rules`)
+
+Already shipped:
+
+- `comms/` package scaffold, console adapters, `CommsApp`, routes, CI/publish
+- Root `package.json` scripts, example-backend registration
 
 ## Task List
 
@@ -307,12 +382,15 @@ See [docs/tasks/comms-abstraction.md](../tasks/comms-abstraction.md).
 - [x] A Terreno app with only console adapters can call `sendMail`, `sendSms`,
       `sendPushToUser`, and `startVerification`/`checkVerification` in development, each
       producing a logger line and a `CommsMessage` row.
-- [ ] `beforeSend` can cancel and mutate; `onSend`/`onError` fire with the final
-      `SendResult`; `onRetry` fires on the inline transient retry — and a hook that throws
-      is logged without changing the send outcome (test per hook).
-- [ ] Failed sends record `errorCode` and `errorClass` on both the `SendResult` and the
-      `CommsMessage` row; only `transient` failures trigger the inline retry.
-- [ ] `CommsMessage.attempts` holds one entry per attempt with per-attempt error data;
+- [x] `beforeSend` can cancel and mutate; `onSend`/`onError` fire with the final
+      `SendResult`; `onRetry` fires on the inline transient retry with
+      `context.attempt === 2` — and a hook that throws is logged without changing the send
+      outcome (test per hook, including `onOptOut` / `onDeliveryEvent` via the record
+      methods).
+- [x] Failed sends record `errorCode` and `errorClass` on both the `SendResult` and the
+      `CommsMessage` row; only `transient` failures trigger the inline retry; provider
+      throws become transient and do not propagate.
+- [x] `CommsMessage.attempts` holds one entry per attempt with per-attempt error data;
       `payload` is retained post-redaction and cleared after `retainPayloadDays`.
 - [x] `POST /comms/pushTokens` registers a device token for the authenticated user;
       re-posting the same token updates rather than duplicates; other users cannot list or
@@ -321,3 +399,15 @@ See [docs/tasks/comms-abstraction.md](../tasks/comms-abstraction.md).
 - [x] Production apps with an unconfigured channel get a 501 `APIError`, not a silent no-op.
 - [x] `@terreno/comms` core has zero provider SDKs in `dependencies`.
 - [x] All routes appear in `/openapi.json` and the generated SDK compiles.
+- [x] Push retries re-send only transient-failed tokens; permanent failures deactivate
+      tokens via `errorClass` or `isPermanentFailure`.
+- [x] `recordDeliveryEvent` updates status by `providerMessageId`; `recordOptOut` fires
+      `onOptOut` without sending.
+
+## Named assumptions (finish pass)
+
+1. Original Decisions table stands; remaining work implements the IP rather than shrinking
+   it to today’s partial code.
+2. Published `onRetry(context, result)` stays; `attempt` is added on context.
+3. Roadmap issue #1018 already exists; Blend does not open a second issue. Maintainer can
+   move Project status when roast of remaining tasks starts.

package/src/docs/versioned/next/implementationPlans/comms-adapter-sendgrid.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Comms adapter — transactional email (SendGrid)
 
-**Status:** Draft
+**Status:** In progress — Phase 1 send path implemented; Phase 2 gated on inbound-webhooks
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1022
 **Priority:** High
 **Effort:** Small batch
@@ -135,22 +135,22 @@ See [docs/tasks/comms-adapter-sendgrid.md](../tasks/comms-adapter-sendgrid.md).
 
 ## Acceptance Criteria
 
-- [ ] `sendMail` delivers text/html mail with from-address fallback chain (provider option
+- [x] `sendMail` delivers text/html mail with from-address fallback chain (provider option
       → `CommsApp.defaultFrom`), and passes `templateId`/`dynamicTemplateData` through when
       given.
-- [ ] Sandbox mode is on by default under test and produces accepted results without real
+- [x] Sandbox mode is on by default under test and produces accepted results without real
       sends.
-- [ ] SendGrid errors surface as `accepted: false` with the SendGrid error message and a
+- [x] SendGrid errors surface as `accepted: false` with the SendGrid error message and a
       correct `errorCode`/`errorClass` per the classification table; nothing throws
       through the facade.
-- [ ] 401/403 classify as `config` and `logger.error` at send time; 429/5xx classify as
+- [x] 401/403 classify as `config` and `logger.error` at send time; 429/5xx classify as
       `transient` and retry once; other 4xx are `permanent` and never retried.
-- [ ] Each accepted send captures the `x-message-id` and stores a `metadata.consoleUrl`
+- [x] Each accepted send captures the `x-message-id` and stores a `metadata.consoleUrl`
       Email Activity deep link.
-- [ ] Consumer `onError` fires with the classified `SendResult` on every failed send
+- [x] Consumer `onError` fires with the classified `SendResult` on every failed send
       (mocked-client test).
-- [ ] Missing API key fails fast at `CommsApp` registration with a clear error.
-- [ ] Apps not using the adapter do not install `@sendgrid/mail`.
+- [x] Missing API key fails fast at `CommsApp` registration with a clear error.
+- [x] Apps not using the adapter do not install `@sendgrid/mail`.
 - [ ] (Phase 2) Event webhook updates `CommsMessage.status` per the mapping table only
       for signature-verified payloads; bounce/dropped reasons land as `errorCode`.
 - [ ] (Phase 2) `spamreport`/`unsubscribe` events fire `onOptOut`; later sends to the

package/src/docs/versioned/next/implementationPlans/comms-admin-dashboard.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Comms admin dashboard (errors, retries, log digging)
 
 **Status:** Draft
-**Roadmap issue:** *(not yet seeded — see [roadmap-seed-issues.md](../explanation/roadmap-seed-issues.md))*
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1091
 **Priority:** High
 **Effort:** Medium batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/consent-forms.md

@@ -1,5 +1,9 @@
 # Implementation Plan: Consent Forms System
 
+**Status:** Complete
+**Closed:** 2026-08-20 — Shipped via `ConsentApp`, `ConsentForm`/`ConsentResponse` models, and `@terreno/ui` consent screens (`ConsentNavigator`, `ConsentFormScreen`, `useConsentForms`).
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1078
+
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 
 ## **Models**

package/src/docs/versioned/next/implementationPlans/design-blend-skill.md

@@ -1,5 +1,6 @@
 # Implementation Plan: design-blend Skill
 
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1083
 ## Goal
 
 Create a new `design-blend` skill that converts a Claude design file into a Terreno implementation blueprint and execution steps, with these hard constraints:

package/src/docs/versioned/next/implementationPlans/docs-site-and-versioning.md

@@ -1,5 +1,6 @@
 # Implementation Plan: Documentation Site, Versioned Docs, and Docs-Maintenance Skills
 
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1086
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 
 ## Overview

package/src/docs/versioned/next/implementationPlans/feature-flags-openfeature.md

@@ -1,5 +1,6 @@
 # Implementation Plan: OpenFeature Adoption for `@terreno/feature-flags`
 
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1082
 ## Goal
 
 Migrate `@terreno/feature-flags` (backend) and `@terreno/rtk`'s `useFeatureFlags` (frontend) to be built on top of the OpenFeature SDKs (`@openfeature/server-sdk`, `@openfeature/react-sdk`) while preserving:

package/src/docs/versioned/next/implementationPlans/feature-flags.md

@@ -1,5 +1,9 @@
 # Implementation Plan: Feature Flags & A/B Testing
 
+**Status:** Deferred
+**Closed:** 2026-08-20 — Superseded by [feature-flags-openfeature.md](./feature-flags-openfeature.md) (OpenFeature provider, live updates). This document is retained for historical context only.
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1098
+
 > **OpenFeature migration:** For the OpenFeature-based provider, `/flagConfiguration`, live updates, and RTK hook details, see [feature-flags-openfeature.md](./feature-flags-openfeature.md) and the task list [feature-flags-openfeature.md](../tasks/feature-flags-openfeature.md).
 
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*

package/src/docs/versioned/next/implementationPlans/infra-mcp-research.md

@@ -1,6 +1,7 @@
 # Research: Infrastructure MCP server (privileged tools gateway)
 
 **Status:** Complete — decisions made, IP written: [infra-mcp.md](infra-mcp.md)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1090
 **Created:** 2026-08-09
 
 ## Scope statement

package/src/docs/versioned/next/implementationPlans/infra-mcp.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Infrastructure MCP server (`@terreno/infra-mcp`)
 
-**Status:** Draft — blocked on the RBAC module ([rbac-permissions.md](rbac-permissions.md)) landing in `@terreno/api`
+**Status:** Draft — unblocked; RBAC module is Complete ([rbac-permissions.md](rbac-permissions.md))
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1090
 **Branch:** TBD
 **Owner:** TBD
 **Created:** 2026-08-09
@@ -228,7 +229,7 @@ No new frontend package. Admin surfaces reuse `@terreno/admin-backend` + `@terre
 
 - **No data migrations** — all collections are new.
 - Rollout is additive: new package, new Cloud Run service. Nothing existing changes until Phase 2's cloud-agent credential switch, which is coordinated: keep `GCP_SA_*` injection until the MCP path is verified, then remove.
-- Blocked dependency: the RBAC module PR must merge first (Phase 1 RBAC wiring consumes `createAccess`, `rbacUserPlugin`, `rbacRouter`, default-role seeding).
+- RBAC dependency: the RBAC module is Complete ([rbac-permissions.md](rbac-permissions.md)). Phase 1 wiring consumes `createAccess`, `rbacUserPlugin`, `rbacRouter`, default-role seeding.
 
 ## Activity Log & User Updates
 
@@ -249,7 +250,6 @@ No new frontend package. Admin surfaces reuse `@terreno/admin-backend` + `@terre
 - `package.json` (root) — workspace entry, catalog: zod 4, `@modelcontextprotocol/server`, `@better-auth/oauth-provider`, `@better-auth/mcp`, Google API clients.
 - `terraform/main.tf`, `variables.tf`, `outputs.tf` — `infra_mcp_service` module instance + runtime SA IAM.
 - `.cursor/rules/infra-mcp/00-infra-mcp.mdc`, `AGENTS.md`/`CLAUDE.md` package lists, docs site page.
-- `docs/implementationPlans/PLAN_INDEX.md` — register this IP.
 - `ROADMAP.md` + `docs/explanation/roadmap-seed-issues.md` — roadmap entry and ready-to-paste tracking issue (done); `scripts/issueAreaLabels.ts` + bug-report package dropdown when the package lands.
 
 ## Task List

package/src/docs/versioned/next/implementationPlans/mcp-boost-parity.md

@@ -1,5 +1,6 @@
 # Implementation Plan: MCP Server — Boost Parity (Docs Search, Local Runtime Tools, Per-Package Guidelines, Upgrade Prompts)
 
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1085
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 
 ## Overview

package/src/docs/versioned/next/implementationPlans/migrate-cicd-to-circleci-research.md

@@ -1,6 +1,7 @@
 # Research: Migrate CI/CD to CircleCI
 
 **Status:** Research complete — decisions recorded in IP `migrate-cicd-to-circleci.md`  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1088
 **Date:** 2026-08-17  
 **Repo:** FlourishHealth/terreno (`master` @ `1e3e79a6`)  
 **Branch:** `cursor/migrate-cicd-circleci-2b6d`

package/src/docs/versioned/next/implementationPlans/migrate-cicd-to-circleci.md

@@ -1,8 +1,8 @@
 # Implementation Plan: Migrate CI/CD to CircleCI
 
-**Status:** Draft — decisions recorded; awaiting Approval  
+**Status:** In progress — Phase 1–3 CI config landed (deploys deferred per request)  
 **Discussion:** _(none)_  
-**Roadmap issue:** _(pending — hand off via `roadmap-item` when Approved)_  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1088
 **Linear:** _(none)_  
 **Priority:** High  
 **Effort:** Large (cross-cutting infra; many workflows)  

package/src/docs/versioned/next/implementationPlans/model-router-actions.md

@@ -1,5 +1,9 @@
 # Implementation Plan: modelRouter Actions
 
+**Status:** Deferred
+**Closed:** 2026-08-20 — Not pursued; custom `endpoints` callbacks remain the supported pattern for non-CRUD routes.
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1097
+
 ## Goal
 
 Add first-class support for **actions** in `modelRouter` — URLs that perform a named operation rather than CRUD. Actions live either at `/resource/action` (collection scope) or `/resource/:id/action` (instance scope). They inherit modelRouter's permissions system, are wrapped in `asyncHandler` + the standard error envelope automatically, and appear in the generated OpenAPI spec without extra wiring.

package/src/docs/versioned/next/implementationPlans/model-router-mcp.md

@@ -1,5 +1,6 @@
 # Implementation Plan: modelRouter MCP Tools
 
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1092
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 
 ## Overview
@@ -17,7 +18,8 @@ This makes every Terreno app instantly AI-native: any model becomes callable by
 - Auth-agnostic: works with both JWT and Better Auth
 - Tool naming: `{prefix}_list`, `{prefix}_read`, `{prefix}_create`, `{prefix}_update`, `{prefix}_delete`
 - Populate is an option on the read tool, not a separate tool
-- Also exports `getMCPTools()` returning Vercel `ai` SDK `CoreTool` objects for direct in-process use
+- Also exports `getMCPTools()` from `@terreno/ai` returning Vercel `ai` SDK `CoreTool` objects for direct in-process use
+- Custom tools via `registerMCPTool` (example: `users_todo_statuses`)
 
 **Related work:** The `ai-multimodal-tools-mcp` branch has `MCPService` (MCP client) and `AIService` in `@terreno/ai` — that's the consumer of what this plan builds.
 
@@ -112,7 +114,7 @@ Generated from model name, field names/types, and `queryFields`. Example:
 
 ### CoreTool Export
 
-`getMCPTools()` exported from `@terreno/api` returns all registered MCP tools as `Record<string, CoreTool>` for direct use with the Vercel `ai` SDK's `streamText()` / `generateText()`.
+`getMCPTools()` exported from `@terreno/ai` returns all registered MCP tools as `Record<string, CoreTool>` for direct use with the Vercel `ai` SDK's `streamText()` / `generateText()`.
 
 ## Notifications
 
@@ -175,8 +177,7 @@ No activity logging specific to this feature. MCP tool calls go through the same
 ## Not Included / Future Work
 
 - **Rate limiting** — structured for future hooks but not implemented
-- **MCP resources/prompts** — only tools generated from modelRouter
-- **Custom MCP tools** — use modelRouter's `endpoints` for custom routes; MCP-specific custom tools deferred
+- **MCP resources/prompts** — only tools generated from modelRouter plus `registerMCPTool`
 - **Array operation tools** — handled via update, no dedicated push/patch/delete array tools
 - **WebSocket transport** — HTTP/SSE only
 - **Admin dashboard** — use `getMCPTools()` programmatically or MCP client tool listing

package/src/docs/versioned/next/implementationPlans/offline-mode.md

@@ -1,6 +1,8 @@
 # Implementation Plan: Offline Mode
 
-**Status:** Approved for implementation tasking
+**Status:** Deferred
+**Closed:** 2026-08-20 — Superseded by [@terreno/syncdb](syncdb-local-first.md) local-first outbox and offline-capable sync.
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1096
 **Priority:** High
 **Effort:** Medium