@terreno/mcp 56.0.0-beta.0 → 57.0.0-beta.1

package/src/docs/versioned/next/reference/test.md

@@ -0,0 +1,108 @@
+# @terreno/test
+
+Shared Bun test helpers for Terreno backend packages: in-memory MongoDB lifecycle, auth env defaults, HTTP fixtures, and log silencing.
+
+## Install
+
+```bash
+bun add -d @terreno/test mongoose
+```
+
+`mongoose` is a peer dependency (>= 8.0.0).
+
+## Commands
+
+From the `@terreno/test` package directory:
+
+```bash
+bun run compile    # Compile TypeScript
+bun run test       # Run package tests
+bun run lint       # Lint code
+```
+
+Consumers typically run `bun test` in their own package with a `bunfig.toml` preload (see below).
+
+## Preload pattern
+
+Add a `bunfig.toml` preload that wires MongoDB and test env before any test file runs. Example from `admin-backend/bunfig.toml`:
+
+```toml
+[test]
+preload = ["./src/tests/bunSetup.ts"]
+root = "./src"
+```
+
+Example preload (`admin-backend/src/tests/bunSetup.ts`):
+
+```typescript
+import {registerSimpleMongoPreload} from "@terreno/test";
+
+process.env.TERRENO_TEST_USE_MEMORY_MONGO = "true";
+
+registerSimpleMongoPreload({
+  testEnv: {
+    tokenIssuer: "terreno-admin-backend.test",
+  },
+});
+```
+
+The `@terreno/api` package uses a two-file preload (`api/bunfig.toml`): `./src/tests/testEnv.ts` then `./src/tests/bunSetup.ts`, which calls `registerBackendPreload` or `registerSimpleMongoPreload` depending on fixture-cache settings.
+
+Import the memory-Mongo flag alone when you only need the env var:
+
+```typescript
+import "@terreno/test/preload/memoryMongo";
+```
+
+That sets `TERRENO_TEST_USE_MEMORY_MONGO=true` before other preload logic runs.
+
+## Test environment
+
+Call `setTerrenoTestEnv()` from a preload or `beforeEach` to apply canonical auth secrets and validate required vars (via internal `setupTestEnvironment()`):
+
+```typescript
+import {setTerrenoTestEnv} from "@terreno/test";
+
+setTerrenoTestEnv({
+  tokenIssuer: "my-package.test",
+  tokenSecret: "secret",
+  refreshTokenSecret: "refresh",
+  sessionSecret: "session",
+});
+```
+
+Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRET`, `NODE_ENV=test`, `TZ=UTC`.
+
+## Environment variables
+
+| Variable | Effect |
+|----------|--------|
+| `TERRENO_TEST_USE_MEMORY_MONGO` | When `"true"`, `registerSimpleMongoPreload` starts `mongodb-memory-server` if `TERRENO_TEST_MONGODB_URI` is unset. |
+| `TERRENO_TEST_MONGODB_URI` | External MongoDB URI. Takes priority over in-memory server in `startMongoServer` and `registerSimpleMongoPreload`. |
+| `BUN_TEST_DISABLE_DB` | When `"true"`, `registerBackendPreload` skips all Mongo `beforeAll`/`afterAll` hooks (no DB startup). |
+
+`startMongoServer` also publishes the resolved URI to `TERRENO_TEST_MONGO_URI` and honors `TERRENO_TEST_USE_REPLSET=true` for replica-set memory servers.
+
+## Exported helpers
+
+| Export | Description |
+|--------|-------------|
+| `registerBackendPreload` | Full lifecycle: memory/external Mongo, optional transactions, Sentry mock, log silencing. |
+| `registerSimpleMongoPreload` | Lightweight connect-once pattern (used by most packages). |
+| `setTerrenoTestEnv` | Apply and validate auth test env vars. |
+| `startMongoServer` / `stopMongoServer` | Start or stop shared in-memory Mongo and connect mongoose. |
+| `getMongoServerUri` | Resolved URI after `startMongoServer`. |
+| `getBaseServer` | Build an Express app for supertest from route registrars. |
+| `authAsUser` | Login helper returning auth headers for supertest. |
+| `createMongoTestCache` | Fixture-cache controller for fast `@terreno/api` tests. |
+| `registerLogSilencing` / `createLogSilencer` | Suppress Winston noise in tests. |
+| `registerSentryBunMock` | Mock `@sentry/bun` in preload. |
+| `ensureTestMongooseConnected` | Connect mongoose to test URI with retries. |
+| `waitForDocument` / `waitForDocuments` | Poll until documents match a query. |
+| `startTestTransaction` / `abortTestTransaction` | Per-test mongoose transactions when enabled. |
+
+## Conventions
+
+- Preload once per package via `bunfig.toml`; do not start Mongo in individual test files.
+- Prefer `registerSimpleMongoPreload` unless you need transactions or fixture caching (`registerBackendPreload`).
+- Never mock `@terreno/api` or Mongoose models in package tests — use the real stack against memory Mongo.

package/src/docs/versioned/next/roadmap.md

@@ -0,0 +1,9 @@
+# Roadmap
+
+Terreno's public roadmap lives on GitHub:
+
+- **[ROADMAP.md](https://github.com/FlourishHealth/terreno/blob/master/ROADMAP.md)** — generated from the Terreno Roadmap project board (also in the repo root)
+- **[Roadmap process](explanation/roadmap-process.md)** — Discussions, triage, Linear bridge, maintainer setup
+- **[GitHub Discussions](https://github.com/FlourishHealth/terreno/discussions)** — Ideas, Q&A, RFCs
+
+To propose work, start an [Ideas discussion](https://github.com/FlourishHealth/terreno/discussions/new?category=ideas) rather than opening a tracking issue directly.

package/src/docs/versioned/next/tasks/README.md

@@ -0,0 +1,42 @@
+# Task lists
+
+Bot-consumable execution checklists, one per implementation plan (IP). A task file is
+the second half of the pair described in
+[`docs/implementationPlans/README.md`](../implementationPlans/README.md):
+
+- **IP** (`docs/implementationPlans/<slug>.md`) — the design: what and why.
+- **Task list** (`docs/tasks/<slug>.md`) — the steps: the concrete, ordered work.
+
+The filename slug matches the IP it belongs to.
+
+## Task shape
+
+Each task is a checkbox with four fields so it can be picked up and verified independently:
+
+```markdown
+- [ ] **Task 1.1**: Short title
+  - Description: what to implement
+  - Files: expected files to create or modify
+  - Depends on: none | other task IDs
+  - Acceptance: how to verify it is done
+```
+
+Group tasks by phase (`### Phase 1: …`). Order them by dependency — models first, then
+APIs, then UI. Blend-style runs may append a **Plan vs Actual** log to the same file after
+each task.
+
+## What lives here vs elsewhere
+
+| Concern | Home |
+| ------- | ---- |
+| Design, scope, acceptance criteria | the IP (`docs/implementationPlans/`) |
+| Concrete task steps and their status | this directory |
+| Public status and target | GitHub roadmap issue / Project (roadmap-enabled repos) |
+| Sprint estimates and assignees | Linear |
+
+Do not copy the full checklist into a GitHub issue or Linear. Create linked GitHub child
+issues only for tasks that outside contributors should be able to claim independently; the
+task file stays the source of truth for scope and acceptance.
+
+The docs site excludes this directory, so link to task files with full GitHub URLs from
+pages that render on the site.

package/src/docs/versioned/next/tasks/agentic-sdlc-plugin.md

@@ -14,25 +14,25 @@ See: [`docs/implementationPlans/agentic-sdlc-plugin.md`](../implementationPlans/
 
 ## Phase 1: Decide and sanitize
 
-- [ ] **Task 1.1**: Audit the plugin for repo- and org-specific content
+- [x] **Task 1.1**: Audit the plugin for repo- and org-specific content
   - Description: Grep all five skills for Flourish-specific and monorepo-specific content: `rg -n -i "phi|hipaa|flourish|dcb3|example-frontend|admin-spa|bun run|docs/implementationPlans"` across `plugins/`. Produce a table: file, line, category (org-specific / repo-path / hardcoded value / tool assumption), and the proposed replacement. Include the `.cursor-plugin/*.json` files (owner email, marketplace description). Do not change anything yet.
   - Files: none (findings in the PR body)
   - Depends on: none
   - Acceptance: every hit is categorized with a proposed replacement; the table covers all five skills plus both JSON files.
 
-- [ ] **Task 1.2**: Generalize sensitive-data handling
+- [x] **Task 1.2**: Generalize sensitive-data handling
   - Description: Per IP question AP2, replace PHI/HIPAA-specific language with generalized sensitive-data language across `terreno-1-blend`, `terreno-4-pour`, and `terreno-5-dialin`. The rule must survive the rewrite: PR text, review replies, and attached evidence media must not contain sensitive data (PHI, PII, credentials, customer data). Keep it concrete — a vague "be careful with data" is not a usable instruction for an agent.
   - Files: `plugins/terreno-planning/skills/terreno-1-blend/SKILL.md`, `terreno-4-pour/SKILL.md`, `terreno-5-dialin/SKILL.md`
   - Depends on: Task 1.1
   - Acceptance: `rg -n -i "phi|hipaa" plugins/` returns nothing; each rewritten rule names the specific artifacts it applies to (PR body, comments, screenshots, recordings) and the data categories.
 
-- [ ] **Task 1.3**: Fix the hardcoded branch suffix
+- [x] **Task 1.3**: Fix the hardcoded branch suffix
   - Description: `terreno-4-pour` documents the branch convention as `cursor/<descriptive-name>-dcb3`. The suffix is per-agent-run, not a fixed literal, so this will produce wrong branch names. Replace it with a description of the convention (a `cursor/` prefix plus the run-specific suffix the agent was given) and instruct the agent to use the suffix from its own run instructions rather than any literal in the skill.
   - Files: `plugins/terreno-planning/skills/terreno-4-pour/SKILL.md`
   - Depends on: Task 1.1
   - Acceptance: no literal run suffix appears anywhere in `plugins/`; the convention is described such that an agent in any run produces a correctly-suffixed branch.
 
-- [ ] **Task 1.4**: Clean up plugin metadata
+- [x] **Task 1.4**: Clean up plugin metadata
   - Description: Update `.cursor-plugin/marketplace.json` and `plugins/terreno-planning/.cursor-plugin/plugin.json`: adjust the marketplace description per the AP1 decision (it currently says "Team marketplace"), review whether a personal email is the right contact for a public plugin versus a role address, and add a field or README note declaring which Terreno versions the plugin targets (IP question AP7). Add `plugins/terreno-planning/LICENSE` matching the root license.
   - Files: `.cursor-plugin/marketplace.json`, `plugins/terreno-planning/.cursor-plugin/plugin.json`, `plugins/terreno-planning/LICENSE` (new)
   - Depends on: Task 1.1
@@ -99,7 +99,7 @@ See: [`docs/implementationPlans/agentic-sdlc-plugin.md`](../implementationPlans/
   - Acceptance: under 150 lines; every coffee name is glossed; the installation steps were performed from a fresh state; the quickstart matches a run you completed.
 
 - [ ] **Task 4.2**: Write `docs/explanation/agentic-sdlc.md`
-  - Description: The conceptual case, no commands. Cover: the process layer versus the MCP tool layer, and why both are needed; why planning is a separate stage with a question-first gate (agents confidently plan the wrong thing); why review happens in a **fresh context** rather than by asking the implementing agent to check its own work; why verification is a separate stage from implementation; why the frontend gate demands evidence rather than a claim; and why flaky CI must be classified rather than guessed at. Then an honest limits section: what the pipeline does not do, where a human must decide, and the 15-minute review timeout. Reuse the mermaid diagram from the IP.
+  - Description: The conceptual case, no commands. Cover: the process layer versus the MCP tool layer, and why both are needed; why planning is a separate stage with a question-first gate (agents confidently plan the wrong thing); why review happens in a **fresh context** rather than by asking the implementing agent to check its own work; why verification is a separate stage from implementation; why the frontend gate demands evidence rather than a claim; and why flaky CI must be classified rather than guessed at. Then an honest limits section: what the pipeline does not do, where a human must decide, and why the review loop persists through slow CI but stops when no autonomous action can advance a terminal failure. Reuse the mermaid diagram from the IP.
   - Files: `docs/explanation/agentic-sdlc.md` (new), `docs/explanation/README.md`
   - Depends on: Task 4.1
   - Acceptance: no commands; all six design rationales explained; a limits section naming at least three things the pipeline will not do; linked from the explanation index.

package/src/docs/versioned/next/tasks/billing-stripe.md

@@ -0,0 +1,75 @@
+# Tasks: Stripe billing and subscriptions
+
+IP: [billing-stripe](../implementationPlans/billing-stripe.md)
+
+## Phase 1 — Package + models
+
+- [ ] **Task 1.1**: Scaffold `@terreno/billing` package
+  - Description: workspace package mirroring `feature-flags/`; root scripts
+  - Files: `billing/package.json`, `billing/tsconfig.json`, root `package.json`
+  - Depends on: none
+  - Acceptance: compile + lint pass
+- [ ] **Task 1.2**: Models (BillingCustomer, BillingSubscription, BillingEvent)
+  - Description: per IP with unique indexes and descriptions
+  - Files: `billing/src/models/*`
+  - Depends on: 1.1
+  - Acceptance: unit tests incl. unique-index violations
+- [ ] **Task 1.3**: Plan config validation
+  - Description: `plans` option schema (Zod), duplicate/missing price detection at startup
+  - Files: `billing/src/billingApp.ts`
+  - Depends on: 1.1
+  - Acceptance: bad config fails fast with clear error
+
+## Phase 2 — Checkout + portal + entitlements
+
+- [ ] **Task 2.1**: Customer creation + checkout/portal session routes
+  - Description: `POST /billing/checkoutSession` (IsOrgAdmin), `POST /billing/portalSession`, `GET /billing/plans`
+  - Files: `billing/src/billingApp.ts`
+  - Depends on: 1.2, orgs-and-teams Phase 3
+  - Acceptance: mocked-Stripe supertest incl. permission denials
+- [ ] **Task 2.2**: `getEntitlements` + `planSegment` + `RequiresPlan`
+  - Description: cache-backed entitlement service; feature-flag segment factory; permission
+  - Files: `billing/src/billingService.ts`
+  - Depends on: 1.2
+  - Acceptance: zero inline Stripe calls asserted; flag targeting test with FeatureFlagsApp
+- [ ] **Task 2.3**: `GET /billing/subscription`
+  - Description: org subscription + entitlements for members
+  - Files: `billing/src/billingApp.ts`
+  - Depends on: 2.2
+  - Acceptance: supertest member/non-member
+
+## Phase 3 — Webhook sync (gated on inbound-webhooks)
+
+- [ ] **Task 3.1**: Stripe webhook route with signature verification
+  - Description: raw-body route via inbound-webhooks; reject unsigned
+  - Files: `billing/src/stripeSync.ts`
+  - Depends on: inbound-webhooks IP
+  - Acceptance: signed/unsigned fixture tests
+- [ ] **Task 3.2**: Idempotent event handlers
+  - Description: checkout.session.completed, subscription created/updated/deleted, invoice paid/payment_failed → model sync via `BillingEvent`
+  - Files: `billing/src/stripeSync.ts`
+  - Depends on: 3.1
+  - Acceptance: replay of same event id is a no-op; cancellation downgrades after webhook
+- [ ] **Task 3.3**: Dunning email
+  - Description: `paymentFailed` template through comms when configured
+  - Files: `billing/src/stripeSync.ts`, `comms/src/templates.ts`
+  - Depends on: 3.2, comms-abstraction
+  - Acceptance: template send asserted on payment_failed fixture
+
+## Phase 4 — UI + example + docs
+
+- [ ] **Task 4.1**: Plan picker + billing settings screens
+  - Description: example-frontend screens per IP; SDK regen
+  - Files: `example-frontend/app/**`, `store/openApiSdk.ts`
+  - Depends on: Phase 2
+  - Acceptance: UI verification evidence per verify-ui-changes (Stripe test mode)
+- [ ] **Task 4.2**: example-backend registration + seeds + docs
+  - Description: env-gated BillingApp; test-mode setup guide; how-to + reference docs
+  - Files: `example-backend/src/server.ts`, `docs/how-to/add-billing.md`, `docs/reference/billing.md`
+  - Depends on: Phase 2
+  - Acceptance: docs build + `bun run rules:check` pass
+- [ ] **Task 4.3**: CI + publish wiring
+  - Description: billing-ci workflow; publish-on-tag entry
+  - Files: `.github/workflows/*`
+  - Depends on: 1.1
+  - Acceptance: CI green

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

@@ -0,0 +1,90 @@
+# Tasks: Pluggable communications layer (@terreno/comms)
+
+IP: [comms-abstraction](../implementationPlans/comms-abstraction.md)
+
+## Phase 1 — Package + contracts
+
+- [x] **Task 1.1**: Scaffold `@terreno/comms` workspace package
+  - Description: `comms/` package with tsconfig/biome/bun test setup mirroring `feature-flags/`; root workspace entry + `comms:*` scripts
+  - Files: `comms/package.json`, `comms/tsconfig.json`, `comms/biome.jsonc`, root `package.json`
+  - Depends on: none
+  - Acceptance: `bun run comms:compile` and `bun run comms:lint` pass
+- [ ] **Task 1.2**: Provider interfaces and message types
+  - Description: `MailProvider`, `SmsProvider`, `PushProvider`, `VerificationProvider`, `SendResult` (incl. `errorCode`/`errorClass`), `DeliveryEvent`, `CommsHookContext`, `OptOutEvent` per IP
+  - Status: base provider/message contracts shipped; `errorCode`/`errorClass`, `CommsHookContext`, and `OptOutEvent` remain
+  - Files: `comms/src/types.ts`
+  - Depends on: 1.1
+  - Acceptance: types compile and are exported
+- [x] **Task 1.3**: Console adapters
+  - Description: dev adapters for all four channels logging via `logger.info`
+  - Files: `comms/src/adapters/console.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: each adapter returns `accepted: true` and logs
+- [ ] **Task 1.4**: `CommsMessage` model + `logSend`
+  - Description: delivery log model with five-type pattern, `description` on every field, plugins, static `logSend` that never throws; dashboard-ready fields (`errorCode`, `errorClass`, `attempts[]`, `attemptCount`, `lastAttemptAt`, `retriedFromId`/`retriedById`, `templateId`, retained `payload`)
+  - Files: `comms/src/models/commsMessage.ts` + tests
+  - Depends on: 1.1
+  - Acceptance: send logging survives a forced model error (logged, not thrown); attempts append per attempt
+  - Status: model and non-throwing `logSend` shipped; dashboard-ready fields remain
+- [ ] **Task 1.5**: `commsService` send facade
+  - Description: `sendMail`/`sendSms`/`sendPushToUser`/`startVerification`/`checkVerification`; template render helper; unconfigured-channel behavior (501 in prod, console fallback in dev); inline retry on `errorClass: "transient"` only
+  - Status: send facade, templates, and unconfigured-channel behavior shipped; inline transient retry remains
+  - Files: `comms/src/commsService.ts`, `comms/src/templates.ts` + tests
+  - Depends on: 1.2, 1.3, 1.4
+  - Acceptance: unit tests cover happy path + unconfigured channel in both env modes; permanent failures do not retry
+- [ ] **Task 1.6**: Lifecycle hooks
+  - Description: `beforeSend` (mutate/cancel), `onSend`, `onError`, `onRetry`, `onOptOut`, `onDeliveryEvent` wiring in the facade; every hook wrapped so a throw is logged and never changes the send outcome
+  - Files: `comms/src/commsService.ts` + tests
+  - Depends on: 1.5
+  - Acceptance: one test per hook (fires with correct context) plus one throwing-hook test per hook
+- [ ] **Task 1.7**: Payload retention + redaction
+  - Description: `retainPayloadDays` (default 30) storage of rendered payload post-`redactPayload`; expiry cleanup clears `payload` without touching the log row
+  - Files: `comms/src/commsService.ts`, `comms/src/models/commsMessage.ts` + tests
+  - Depends on: 1.4, 1.5
+  - Acceptance: payload stored redacted; expired payload cleared; `retainPayloadDays: 0` stores nothing
+
+## Phase 2 — CommsApp + routes
+
+- [x] **Task 2.1**: `PushToken` model
+  - Description: model per IP with unique token upsert semantics
+  - Files: `comms/src/models/pushToken.ts` + tests
+  - Depends on: 1.1
+  - Acceptance: duplicate token registration updates the existing row
+- [x] **Task 2.2**: `CommsApp` TerrenoPlugin
+  - Description: options wiring, `getCommsService()` accessor, route mounting on `register()`
+  - Files: `comms/src/commsApp.ts` + tests
+  - Depends on: 1.5, 2.1
+  - Acceptance: plugin registers on `TerrenoApp` and service accessor returns configured providers
+- [x] **Task 2.3**: Push token routes
+  - Description: custom idempotent registration/list/deactivation endpoints plus modelRouter owner read; persisted `userId` scoping
+  - Files: `comms/src/routes/pushTokens.ts` + supertest
+  - Depends on: 2.2
+  - Acceptance: acceptance criteria bullets 2 pass under supertest
+- [x] **Task 2.4**: Admin delivery explorer
+  - Description: `GET /comms/messages` admin-only, paginated, filtered; OpenAPI builder
+  - Files: `comms/src/routes/commsExplorer.ts` + supertest
+  - Depends on: 2.2
+  - Acceptance: non-admin gets 403; filters work
+- [x] **Task 2.5**: `sendPushToUser` token resolution + pruning
+  - Description: resolve active tokens per user; deactivate tokens whose `SendResult` reports permanent failure
+  - Files: `comms/src/commsService.ts` + tests
+  - Depends on: 2.1, 1.5
+  - Acceptance: dead token is `active: false` after a failed send
+
+## Phase 3 — Integration + docs
+
+- [x] **Task 3.1**: example-backend registration
+  - Description: register `CommsApp` with console adapters; env-gated
+  - Files: `example-backend/src/server.ts`
+  - Depends on: 2.2
+  - Acceptance: backend boots; `/comms/pushTokens` in `/openapi.json`
+- [x] **Task 3.2**: Reference docs + rules
+  - Description: `docs/reference/comms.md`, rulesync source rule, `bun run rules`
+  - Files: `docs/reference/comms.md`, `.rulesync/**`
+  - Depends on: 2.x
+  - Acceptance: `bun run rules:check` passes
+- [x] **Task 3.3**: CI + publish wiring
+  - Description: `comms-ci` workflow; add `@terreno/comms` to `publish-on-tag.yml`
+  - Files: `.github/workflows/comms-ci.yml`, `.github/workflows/publish-on-tag.yml`
+  - Depends on: 1.x
+  - Acceptance: CI green on the PR

package/src/docs/versioned/next/tasks/comms-adapter-expo-push.md

@@ -0,0 +1,29 @@
+# Tasks: Comms adapter — Expo push notifications
+
+IP: [comms-adapter-expo-push](../implementationPlans/comms-adapter-expo-push.md)
+
+- [ ] **Task 1**: `ExpoPushProvider` implementation
+  - Description: token validation, chunked send, ticket collection per IP
+  - Files: `comms/src/adapters/expoPush.ts`
+  - Depends on: comms-abstraction Phase 1
+  - Acceptance: mocked-client tests pass, one `SendResult` per token
+- [ ] **Task 2**: Receipt polling → `DeliveryEvent` + dead-token marking
+  - Description: poll receipts after configurable delay; map `DeviceNotRegistered` to permanent failure
+  - Files: `comms/src/adapters/expoPush.ts`
+  - Depends on: Task 1
+  - Acceptance: dead token deactivated in test
+- [ ] **Task 3**: Dependency moves
+  - Description: optional peer `expo-server-sdk` on comms; remove from `@terreno/api`
+  - Files: `comms/package.json`, `api/package.json`, root catalog if needed
+  - Depends on: Task 1
+  - Acceptance: `bun install` + full compile pass; api tests unaffected
+- [ ] **Task 4**: example-frontend token registration + dev test-send
+  - Description: register token on login via `POST /comms/pushTokens`; profile dev row triggers `sendPushToUser`
+  - Files: `example-frontend/app/_layout.tsx` or profile screen, `example-backend` dev route
+  - Depends on: Task 1, comms-abstraction Phase 2
+  - Acceptance: UI verification per verify-ui-changes with screenshots
+- [ ] **Task 5**: Docs
+  - Description: adapter section in `docs/reference/comms.md` with env/config table
+  - Files: `docs/reference/comms.md`
+  - Depends on: Task 1
+  - Acceptance: docs build passes

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

@@ -0,0 +1,39 @@
+# Tasks: Comms adapter — transactional email (SendGrid)
+
+IP: [comms-adapter-sendgrid](../implementationPlans/comms-adapter-sendgrid.md)
+
+## Phase 1 — Send path
+
+- [ ] **Task 1.1**: `SendGridMailProvider` with config + sandbox mode
+  - Description: constructor/env config, from-address fallback chain, sandbox default under test
+  - Files: `comms/src/adapters/sendgrid.ts`
+  - Depends on: comms-abstraction Phase 1
+  - Acceptance: mocked-client tests for text/html/template sends
+- [ ] **Task 1.2**: Error classification
+  - Description: HTTP status → `errorCode`/`errorClass` per the IP table (400 permanent, 401/403 config, 429/5xx transient); full response body into `CommsMessage.metadata`; never throws
+  - Files: `comms/src/adapters/sendgrid.ts`
+  - Depends on: 1.1
+  - Acceptance: unverified-sender (config), bad-address (permanent), and 429 (transient) fixtures assert `errorClass`; permanent skips the inline retry
+- [ ] **Task 1.3**: Dashboard metadata + hooks coverage
+  - Description: capture `x-message-id`; `metadata.consoleUrl` Email Activity deep link; `onError` fires with the classified `SendResult`
+  - Files: `comms/src/adapters/sendgrid.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: accepted-send test asserts message id + consoleUrl; failed-send test asserts onError invocation
+- [ ] **Task 1.4**: Peer dep + registration + docs
+  - Description: optional peer `@sendgrid/mail`; env-gated example-backend registration with fail-fast; reference + env docs incl. sender-verification checklist
+  - Files: `comms/package.json`, `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
+  - Depends on: 1.1
+  - Acceptance: boot without key skips registration; compile passes without the SDK installed
+
+## Phase 2 — Delivery events + opt-outs (gated on inbound-webhooks)
+
+- [ ] **Task 2.1**: Event Webhook route
+  - Description: ECDSA signature verification via inbound-webhooks; event mapping per the IP table → `DeliveryEvent`; `x-message-id` prefix correlation
+  - Files: `comms/src/adapters/sendgrid.ts`, webhook registration
+  - Depends on: inbound-webhooks IP
+  - Acceptance: signed fixtures per event type update `CommsMessage.status` (+ `errorCode` for bounce/dropped); unsigned rejected 401
+- [ ] **Task 2.2**: Opt-out events
+  - Description: `spamreport`/`unsubscribe`/`group_unsubscribe` → `OptOutEvent` → consumer `onOptOut`
+  - Files: `comms/src/adapters/sendgrid.ts` + tests
+  - Depends on: 2.1
+  - Acceptance: spamreport fixture fires `onOptOut`; subsequent `dropped` classified `permanent`

package/src/docs/versioned/next/tasks/comms-adapter-twilio-sms.md

@@ -0,0 +1,39 @@
+# Tasks: Comms adapter — Twilio SMS
+
+IP: [comms-adapter-twilio-sms](../implementationPlans/comms-adapter-twilio-sms.md)
+
+## Phase 1 — Send path
+
+- [ ] **Task 1.1**: `TwilioSmsProvider` with config resolution
+  - Description: constructor/env config, messaging-service-first sender selection
+  - Files: `comms/src/adapters/twilioSms.ts`
+  - Depends on: comms-abstraction Phase 1
+  - Acceptance: mocked-client tests cover both sender configs
+- [ ] **Task 1.2**: E.164 validation + error classification
+  - Description: `libphonenumber-js` normalization; Twilio error-code → `errorCode`/`errorClass` map per the IP table (unknown codes → `transient`); full error payload into `CommsMessage.metadata`; Twilio SDK calls wrapped with `withApiErrorHandling`
+  - Files: `comms/src/adapters/twilioSms.ts`
+  - Depends on: 1.1
+  - Acceptance: invalid number → 400 before API call; fixtures for at least one code per class (e.g. 21610 permanent, 20429 transient, 20003 config) assert `errorClass`; permanent failures skip the inline retry
+- [ ] **Task 1.3**: Dashboard metadata + hooks coverage
+  - Description: `metadata.consoleUrl` deep link per message SID; `onError` fires with the classified `SendResult`
+  - Files: `comms/src/adapters/twilioSms.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: failed-send test asserts consoleUrl and onError invocation
+- [ ] **Task 1.4**: Peer dep + example-backend registration + docs
+  - Description: optional peer `twilio`; env-gated registration; reference + env-var docs
+  - Files: `comms/package.json`, `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
+  - Depends on: 1.1
+  - Acceptance: compile + boot without twilio installed when unconfigured
+
+## Phase 2 — Delivery callbacks + opt-outs (gated on inbound-webhooks)
+
+- [ ] **Task 2.1**: Status callback route
+  - Description: webhook endpoint with Twilio signature verification via inbound-webhooks framework; status mapping per IP table incl. `ErrorCode` propagation
+  - Files: `comms/src/adapters/twilioSms.ts`, webhook registration
+  - Depends on: inbound-webhooks IP
+  - Acceptance: signed payload updates `CommsMessage.status` (+ `errorCode` on failure); unsigned rejected 401
+- [ ] **Task 2.2**: STOP/START opt-out handling
+  - Description: inbound keyword webhook → `OptOutEvent` → consumer `onOptOut`; opt-in (START) emitted symmetrically
+  - Files: `comms/src/adapters/twilioSms.ts`, webhook registration + tests
+  - Depends on: 2.1
+  - Acceptance: STOP fixture fires `onOptOut` with `reason: "sms-stop"`; 21610 on later sends classified `permanent`

package/src/docs/versioned/next/tasks/comms-adapter-twilio-verify.md

@@ -0,0 +1,19 @@
+# Tasks: Comms adapter — Twilio Verify (OTP)
+
+IP: [comms-adapter-twilio-verify](../implementationPlans/comms-adapter-twilio-verify.md)
+
+- [ ] **Task 1**: `TwilioVerifyProvider` start/check
+  - Description: provider per IP with config resolution and status mapping
+  - Files: `comms/src/adapters/twilioVerify.ts`
+  - Depends on: comms-abstraction Phase 1
+  - Acceptance: mocked-client tests for approved/pending/expired/max-attempts
+- [ ] **Task 2**: Redacted logging + error classification
+  - Description: `CommsMessage` rows with channel `verification`, fully redacted destination, no codes, and verification channel metadata on start; `errorCode`/`errorClass` mapping (rate-limit transient, expired/max-attempts permanent, bad SID config); rows flagged non-retryable; `onError` fires on failures
+  - Files: `comms/src/adapters/twilioVerify.ts`
+  - Depends on: Task 1
+  - Acceptance: log assertion tests prove no code/full destination in any row; failure fixtures assert class + onError
+- [ ] **Task 3**: Registration + docs
+  - Description: env-gated example-backend registration; fail-fast on missing service SID; reference + env docs
+  - Files: `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
+  - Depends on: Task 1
+  - Acceptance: boot without config skips registration; with partial config throws at startup

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

@@ -0,0 +1,52 @@
+# Tasks: Comms admin dashboard (errors, retries, log digging)
+
+IP: [comms-admin-dashboard](../implementationPlans/comms-admin-dashboard.md)
+
+## Phase 1 — Backend routes
+
+- [ ] **Task 1.1**: Upgrade explorer to `commsDashboard.ts` list + detail
+  - Description: rich filters (channel/provider/status/errorClass/errorCode/userId/to/templateId/dates/`q`), pagination, `GET /comms/messages/:id` with attempts + metadata + retained payload
+  - Files: `comms/src/routes/commsDashboard.ts` + supertest
+  - Depends on: comms-abstraction Phase 2 (incl. hooks/error-taxonomy additions)
+  - Acceptance: every filter covered by a supertest case; non-admin 403
+- [ ] **Task 1.2**: `retryMessage` facade + retry route
+  - Description: retryability validation (status, errorClass, payload retention, channel configured, not verification), linked rows via `retriedFromId`/`retriedById`, hooks fire with `isRetry: true`, acting admin recorded
+  - Files: `comms/src/commsService.ts`, `comms/src/routes/commsDashboard.ts` + tests
+  - Depends on: 1.1
+  - Acceptance: each non-retryable reason returns 400 with its stable `code`; successful retry creates a linked row
+- [ ] **Task 1.3**: `retryMany` + `/comms/stats`
+  - Description: bulk retry with cap + skipped reasons; aggregation by channel × provider × status with day buckets and failure rate
+  - Files: `comms/src/routes/commsDashboard.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: stats counts match list totals for the same filter/range; cap enforced
+
+## Phase 2 — Admin screens
+
+- [ ] **Task 2.1**: `CommsDashboardScreen`
+  - Description: stats cards, filter bar (URL-persisted), DataTable with status badges + inline retry
+  - Files: `admin-frontend/src/comms/CommsDashboardScreen.tsx`, `CommsStatusBadge.tsx`, `useCommsDashboardApi.tsx` + tests
+  - Depends on: 1.1, 1.3
+  - Acceptance: loading/error/empty states; filters round-trip through the URL
+- [ ] **Task 2.2**: `CommsMessageDetail`
+  - Description: attempt timeline, provider console links, JSON viewer for payload/metadata, confirmed retry button with disabled-reason tooltips
+  - Files: `admin-frontend/src/comms/CommsMessageDetail.tsx` + tests
+  - Depends on: 1.2, 2.1
+  - Acceptance: non-retryable rows show the specific reason; retry navigates to the new row
+- [ ] **Task 2.3**: Example app + admin-spa wiring
+  - Description: expo-router screens under `app/admin/comms/`, admin-spa nav entry, `bun run sdk`
+  - Files: `example-frontend/app/admin/comms/*`, `example-frontend/store/openApiSdk.ts`, admin-spa nav
+  - Depends on: 2.1, 2.2
+  - Acceptance: frontend verification in the running example app with screenshots on the PR
+
+## Phase 3 — Bulk retry UI + docs
+
+- [ ] **Task 3.1**: "Retry all failed" flow
+  - Description: filtered bulk retry with count confirmation modal; skipped-reason summary toast
+  - Files: `admin-frontend/src/comms/CommsDashboardScreen.tsx` + tests
+  - Depends on: 1.3, 2.1
+  - Acceptance: confirmation shows the exact count; result summarizes retried/skipped
+- [ ] **Task 3.2**: Docs + rules
+  - Description: dashboard section in comms reference, admin reference update, rulesync
+  - Files: `docs/reference/comms.md`, `docs/reference/admin.md`, `.rulesync/**`
+  - Depends on: 2.x
+  - Acceptance: `bun run rules:check` passes

package/src/docs/versioned/next/tasks/deploy-to-gcp.md

@@ -14,31 +14,31 @@ See: [`docs/implementationPlans/deploy-to-gcp.md`](../implementationPlans/deploy
 
 ## Phase 1: Generalize the how-to guides
 
-- [ ] **Task 1.1**: Write `docs/how-to/deploy-backend-to-cloud-run.md`
+- [x] **Task 1.1**: Write `docs/how-to/deploy-backend-to-cloud-run.md`
   - Description: New guide covering: prerequisites (gcloud installed and authenticated, billing enabled, required APIs — `run`, `artifactregistry`, `secretmanager`, `compute`); creating an Artifact Registry repo; building and pushing the backend image; creating Secret Manager secrets for `MONGO_URI`, `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRET`, and `BETTER_AUTH_SECRET`; creating the runtime service account with least-privilege roles; the `gcloud run deploy` invocation with `--session-affinity`, `--timeout`, `--min-instances`, `--set-secrets`, and `--set-env-vars`; and verification via `curl $SERVICE_URL/health`. Use placeholder variables throughout. Read `example-backend/src/server.ts` and `docs/reference/environment-variables.md` to get the env var list right — do not copy it from this task description without checking.
   - Files: `docs/how-to/deploy-backend-to-cloud-run.md` (new)
   - Depends on: none
   - Acceptance: `rg -i flourish docs/how-to/deploy-backend-to-cloud-run.md` returns nothing; every env var named exists in `docs/reference/environment-variables.md` or the backend source; every `gcloud` flag used appears in `gcloud run deploy --help`.
 
-- [ ] **Task 1.2**: Add the production constraints section
+- [x] **Task 1.2**: Add the production constraints section
   - Description: Add a "Production constraints" section to the backend guide as a symptom → cause → fix table covering at minimum: (a) websockets disconnect every few requests → no session affinity → add `--session-affinity`; (b) long-lived socket connections drop at 5 minutes → default request timeout → raise `--timeout`; (c) realtime and live feature flags stop working → MongoDB is not a replica set → use Atlas or a replica set, because change streams require one; (d) first request after idle is slow and sockets churn → scaled to zero → `--min-instances=1`; (e) browser requests fail CORS → `corsOrigin` in `setupServer` and Better Auth `trustedOrigins` do not include the web origin. Verify claim (c) against `feature-flags` live-update code before writing it.
   - Files: `docs/how-to/deploy-backend-to-cloud-run.md`
   - Depends on: Task 1.1
   - Acceptance: all five rows present with a concrete symptom; the change-streams claim is verified against the source and the source path is cited in the guide.
 
-- [ ] **Task 1.3**: Write `docs/how-to/deploy-web-to-gcs-cdn.md`
+- [x] **Task 1.3**: Write `docs/how-to/deploy-web-to-gcs-cdn.md`
   - Description: New guide covering: building the web bundle (`bunx expo export -p web` — confirm the exact command against `example-frontend/package.json` scripts), the requirement to set `EXPO_PUBLIC_API_URL` at build time because it is inlined into the bundle, creating and configuring the GCS bucket with public read and `notFoundPage=index.html` for client-side routing, the five CDN resources (backend bucket, URL map, static IP, HTTP(S) proxy, forwarding rule), pointing DNS at the IP, and cache invalidation after each deploy. Include a note that this is a static-only path and link [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md) for the SSR future.
   - Files: `docs/how-to/deploy-web-to-gcs-cdn.md` (new)
   - Depends on: none
   - Acceptance: no Flourish strings; the export command matches an actual script in `example-frontend/package.json`; the guide explains why `EXPO_PUBLIC_API_URL` must be set before building, not after.
 
-- [ ] **Task 1.4**: Write the architecture explainer
+- [x] **Task 1.4**: Write the architecture explainer
   - Description: Create `docs/explanation/deployment-architecture-gcp.md` explaining the reference topology (reuse the mermaid diagram from the IP), what each component is responsible for, why Cloud Run rather than App Engine or GKE, why Atlas rather than self-hosted Mongo, and the tradeoffs of static web hosting versus a server-rendered deployment. Keep it conceptual — no commands.
   - Files: `docs/explanation/deployment-architecture-gcp.md` (new)
   - Depends on: Task 1.1, Task 1.3
   - Acceptance: contains the topology diagram; contains no shell commands; explains at least three explicit tradeoffs.
 
-- [ ] **Task 1.5**: Rewire the existing GCP how-to and index
+- [x] **Task 1.5**: Rewire the existing GCP how-to and index
   - Description: Replace `docs/how-to/deploy-to-gcp.md` with a short index page linking the two new guides and the explainer, preserving the old anchor names where practical so existing links do not break. Update `docs/how-to/README.md` to list the new guides. Check `website/` for any hardcoded reference to the old page path and update it.
   - Files: `docs/how-to/deploy-to-gcp.md`, `docs/how-to/README.md`, `website/` (as needed)
   - Depends on: Task 1.1, Task 1.3, Task 1.4
@@ -58,27 +58,27 @@ See: [`docs/implementationPlans/deploy-to-gcp.md`](../implementationPlans/deploy
   - Depends on: Task 2.1
   - Acceptance: `rg -n "terraform/" --glob '!infra/**' --glob '!terraform/**'` shows no stale paths pointing at moved files; the `cd.yml` workflow references the new location; `bun run rules:check` exits 0 after regenerating rules.
 
-- [ ] **Task 2.3**: Parameterize the GCS hosting script
-  - Description: Rewrite `scripts/setup-gcs-hosting.sh` to require `--project`, `--site-name`, and `--bucket` arguments (or positional equivalents) with a usage message and a check that all are present. Remove every hardcoded Flourish project, bucket, and service-account value. Keep the resource-creation logic intact. Add a `--dry-run` flag that prints commands without executing them.
+- [x] **Task 2.3**: Parameterize the GCS hosting script
+  - Description: Rewrite `scripts/setup-gcs-hosting.sh` to require `--project`, `--site-name`, `--bucket`, and `--domain` arguments (or positional equivalents) with a usage message and a check that all are present. Remove every hardcoded Flourish project, bucket, and service-account value. Keep the resource-creation logic intact, with HTTPS as the only public serving path. Add a `--dry-run` flag that prints commands without executing them.
   - Files: `scripts/setup-gcs-hosting.sh`
   - Depends on: Task 1.3
-  - Acceptance: running with no arguments prints usage and exits non-zero; `--dry-run` produces commands containing the supplied values and no Flourish strings; `rg -i flourish scripts/setup-gcs-hosting.sh` returns nothing.
+  - Acceptance: running with no arguments prints usage and exits non-zero; `--dry-run` produces HTTPS commands containing the supplied values, no port 80 forwarding rule, and no Flourish strings; `rg -i flourish scripts/setup-gcs-hosting.sh` returns nothing.
 
 ## Phase 3: The `deploy-gcp` skill
 
-- [ ] **Task 3.1**: Author the skill
+- [x] **Task 3.1**: Author the skill
   - Description: Create `.rulesync/skills/deploy-gcp/SKILL.md` with frontmatter (`name: deploy-gcp`, a `description` that names the trigger phrases "deploy to GCP", "deploy to Cloud Run", "ship the backend", and `targets: ['*']`). Body sections in this order: When to use / When not to use; Preflight checks (project layout detection, `gcloud config get-value project`, required APIs, replica-set verification of `MONGO_URI`); **Plan and confirm** — print target project, region, service name, and every resource to be created or updated, then stop and require explicit user confirmation before any mutating command; Backend deploy steps; Frontend deploy steps; Verification (`curl $SERVICE_URL/health` expecting `"healthy":true`, fetch web root); Troubleshooting (link the reference file). Include an explicit prohibition: never deploy to a project the user did not name in the request, and never create or modify secrets without echoing which secret names will change.
   - Files: `.rulesync/skills/deploy-gcp/SKILL.md` (new)
   - Depends on: Task 1.1, Task 1.3
   - Acceptance: frontmatter has `name`, `description`, and `targets`; the confirmation gate appears before the first mutating command; every command in the skill also appears in the how-to guides (no skill-only knowledge).
 
-- [ ] **Task 3.2**: Add the troubleshooting reference
+- [x] **Task 3.2**: Add the troubleshooting reference
   - Description: Create `.rulesync/skills/deploy-gcp/references/troubleshooting.md` containing the symptom → cause → fix table from Task 1.2 plus deploy-time failures: image push permission denied, secret access denied at cold start, Cloud Run revision failing health checks because `PORT` is not read from the environment, and CDN serving a stale bundle after deploy. For each, give the exact log line or error message the user will see.
   - Files: `.rulesync/skills/deploy-gcp/references/troubleshooting.md` (new)
   - Depends on: Task 3.1
   - Acceptance: at least nine rows; each row quotes an actual error string rather than paraphrasing.
 
-- [ ] **Task 3.3**: Generate skill mirrors
+- [x] **Task 3.3**: Generate skill mirrors
   - Description: Run `bun run rules` and commit every generated file under `.cursor/skills/`, `.claude/skills/`, `.devin/skills/`, `.github/skills/`, and `.agents/skills/`. Do not hand-edit generated files.
   - Files: generated skill mirrors
   - Depends on: Task 3.1, Task 3.2