@terreno/mcp 57.0.0 → 57.1.0

package/src/docs/versioned/next/implementationPlans/admin-only-research.md

@@ -1,5 +1,9 @@
 # Research: Serving Admin from a Terreno App (Opt-In, No Separate SPA Deploy)
 
+**Status:** Complete
+**Closed:** 2026-08-20 — Research incorporated into [admin-only.md](admin-only.md); shipped as `@terreno/admin-spa`.
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1075
+
 ## Summary
 
 Terreno already has the building blocks for an admin UI — `@terreno/admin-backend` mounts `/admin/*` API routes (config, per-model CRUD, search, scripts, version-config) and `@terreno/admin-frontend` ships React Native components designed to be embedded in a consumer's Expo Router app. The gap is the **deploy surface**: today consumers either bundle admin into their main Expo app (bloats user bundles, requires ~7 route files) or build a separate Expo Web app and host it on GCS/Netlify (one more pipeline to maintain).

package/src/docs/versioned/next/implementationPlans/admin-only.md

@@ -1,6 +1,8 @@
 # Admin-Only: Serve Admin SPA From a Terreno Backend (Opt-In)
 
-**Status:** Draft
+**Status:** Complete
+**Closed:** 2026-08-20 — Shipped as `@terreno/admin-spa` (`AdminSpaServeApp`, pre-built Expo web export, Better Auth same-origin). See `admin-spa/` and `admin-only-research.md`.
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1075
 **Branch:** `admin-only`
 **Owner:** Josh Gachnang
 **Created:** 2026-05-11

package/src/docs/versioned/next/implementationPlans/admin-script-runner.md

@@ -1,6 +1,7 @@
 # Admin Script Runner — Maintenance Scripts via `AdminApp`
 
 **Status:** Implemented (ships with Admin UI v2 work; documented here as its own IP)  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1077
 **Related:** [`admin-ui-v2-django-parity.md`](./admin-ui-v2-django-parity.md) (home `scriptRunner` widget, background-task patterns)  
 **Primary packages:** `@terreno/api` (`BackgroundTask`, script types), `@terreno/admin-backend`, `@terreno/admin-frontend`, `admin-spa`, `example-backend`
 

package/src/docs/versioned/next/implementationPlans/admin-ui-v2-django-parity.md

@@ -1,6 +1,7 @@
 # Admin UI v2 — Django-Parity Admin (Config-Driven Shell)
 
 **Status:** Implemented (phased tasks complete; acceptance criteria verified in-repo)  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1076
 **Branch:** Landed via `cursor/admin-ui-v2-backend-a736` (PR #782)  
 **Owner:** Josh Gachnang  
 **Created:** 2026-06-15  

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

@@ -1,178 +1,208 @@
-# Implementation Plan: Publish and Document the Agentic SDLC Plugin
+# Implementation Plan: Loop-Engineering Lifecycle Plugin
 
-**Status:** Draft — key decisions recorded (2026-07-29)
+**Status:** In Progress
+**Approved:** 2026-08-22
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1006
 **Priority:** High
-**Effort:** Big batch
-**Owner:** unassigned
+**Owner:** agent
 **Created:** 2026-07-27
 **Program:** [OSS launch](oss-launch-program.md)
-**Depends on:** [`positioning-django-rails-universal`](positioning-django-rails-universal.md) (shared copy blocks), [`oss-governance-baseline`](oss-governance-baseline.md) (license coverage for `plugins/`)
-**RTK deprecation flag:** **Partial** — the pipeline's frontend-verification gates name `rtk/` in their path lists and must be updated to name `syncdb/` after PR #869.
 
 ## Goal
 
-Terreno ships a five-stage agentic SDLC pipeline as an installable Cursor plugin, and **nobody outside the team knows it exists.** `.cursor-plugin/marketplace.json` declares a team marketplace; `plugins/terreno-planning/` contains five skills that take work from a raw request all the way to a mergeable PR. There is no `plugins/README.md`, no page in `docs/`, no mention in `README.md` or `AGENTS.md`, and the marketplace is scoped to the team.
+Evolve Terreno's existing planning plugin into five reusable, bounded lifecycle
+transitions optimized for repeated fresh agent invocations:
 
-This matters more than a normal documentation gap. The pipeline is the most concrete evidence for the AI-native pillar. Any framework can claim "works great with AI"; very few ship an opinionated, reviewed, test-driven delivery process as installable tooling. In the Django/Rails analogy it is the missing half of `manage.py`: not just "generate a model" but "take this ticket to a mergeable PR with tests and independent review".
-
-The audit that produced this program missed the plugin entirely. If an agent reading the whole repository missed it, every prospective user will too.
+```text
+Grow (shape) → Pick (build) → Roast (prove) → Brew (submit) → Taste (react)
+```
 
-## Non-Goals
+The outer loop owns invocation, persistence, waiting, retry, stop, and escalation.
+Lifecycle skills own how one stage is performed. Repository skills own how this codebase
+works. Roast owns independent acceptance proof. State/evidence bridge fresh invocations.
+
+This is a refactor of the existing strong workflow, not a parallel implementation.
+
+## Scope
+
+- Canonical five plugin skills and migration from former names
+- Explicit transition contracts for every stage
+- Shared machine-readable result and execution-state schemas
+- Supporting-skill discovery/composition
+- Repository-specific detail removed from portable stages
+- Brew exits after PR setup
+- Taste performs one reactive iteration and exits
+- Outer-loop reference including small-feature and CI/review scenarios
+- Static validation for names, status values, transitions, portability, and loop bounds
+- Documentation, metadata, and generated integrations
+
+## Non-scope
+
+- A daemon/hosted scheduler implementation
+- Automatic merging
+- Copying Terreno's repository skills into the plugin
+- Persisting chain-of-thought or conversational transcripts
+- Hundreds of generic micro-skills
+
+## Decisions
+
+| ID | Decision |
+| --- | --- |
+| AP1 | Public reusable plugin; repository-specific knowledge remains local |
+| AP2 | Sensitive-data rules cover credentials, customer data, PII/PHI, and evidence media |
+| AP3 | Canonical stages are Grow, Pick, Roast, Brew, Taste |
+| AP4 | Stages discover supporting skills by description; exact skill names are never universal dependencies |
+| AP5 | Taste is one observe/act/emit iteration; the outer loop owns waiting and reinvocation |
+| AP6 | Shared results use stable YAML shaped by JSON Schema; statuses are `PASS`, `FAIL`, `BLOCKED`, `PENDING` |
+| AP7 | Existing repository state convention wins; fallback reuses loop-owned `.terreno/pipeline/<slug>.json`, not committed by default |
+| AP8 | Brew emits PR/head state and exits; direct Taste invocation is standalone compatibility only |
+| AP9 | No deprecated command aliases: old implementation-Roast conflicts with new verification-Roast and no maintained alias mechanism exists |
+| AP10 | Plugin major version is `2.0.0` because lifecycle semantics and command names are breaking |
 
-- Redesigning the pipeline. The five stages work; this is packaging, documentation, and positioning.
-- Porting the pipeline to every agent runtime. Cursor is the reference; note what would be required for others.
-- Replacing the repo's existing `.rulesync/skills/` (`submit`, `autobot`, `check-watcher`, `respond-to-review`) — but the overlap needs resolving, because right now two pipelines cover similar ground.
-- Building a plugin marketplace of our own.
+## Architecture
 
-## Blocking questions
+```text
+                 OUTER LOOP
+       invoke / persist / wait / retry
+           stop / route / escalate
+                     |
+                     v
+ GROW → PICK → ROAST → BREW → TASTE
+ shape  build   prove   submit  react once
+                     |
+     repository skills + IP/task/state + evidence
+```
 
-**Recorded 2026-07-29** (see program [P11](oss-launch-program.md#blocking-questions-program-level)).
+### Ownership
 
-| # | Question | Decision |
-|---|----------|----------|
-| AP1 | Marketplace public or team-only? | **A** — public at launch (gated on portability) |
-| AP2 | PHI/HIPAA handling | **B** — generalize to "sensitive data (PHI, PII, secrets)" |
-| AP3 | Stage names | **Coffee theme retained.** New five-stage flow: **grow → harvest → roast → brew → taste**. Skills: `/terreno-1-grow`, `/terreno-2-harvest`, `/terreno-3-roast`, `/terreno-4-brew`, `/terreno-5-taste`. **Aliases required** in docs and skill frontmatter (see mapping below) |
-| AP4 | Consumer apps or monorepo only? | **B** — must work in consumer apps |
-| AP5 | Overlap with `submit` / `autobot` | **A** — deprecate `submit` and `autobot` in favor of the plugin. **Fold all `autobot` behavior into Taste (`/terreno-5-taste`)**. Taste should be **self-contained** (inline the full submit → CI → review loop) rather than delegating to other skills — delegation has been unreliable inside the plugin (sub-agents and cross-skill calls do not always resolve). Accept larger skill files / context cost over broken orchestration |
-| AP6 | Agent runtimes | **B** — Cursor + rulesync-generated variants |
-| AP7 | Plugin versioning | **A** — independent versioning; declare compatible Terreno versions |
+| Layer | Owns |
+| --- | --- |
+| Outer loop | when, who, next stage, persistence, waiting, retry, stop, escalation |
+| Lifecycle plugin | portable stage procedure, invariants, evidence, transitions |
+| Repository skills | commands, frameworks, package conventions, safety rules, gotchas |
+| Roast | requirement → method → evidence → verdict |
+| State/evidence | durable facts required by a fresh invocation |
 
-### Stage mapping (rename + aliases)
+### State transition table
 
-| # | New name | Role | Replaces | Aliases (docs + deprecated skill names) |
-|---|----------|------|----------|----------------------------------------|
-| 1 | **grow** | Plan — IP + tasks, blocking questions first | blend | `plan`, `blend`, `terreno-1-blend` |
-| 2 | **harvest** | Implement — strict TDD, drift detection | roast (implement) | `implement`, `terreno-2-roast` |
-| 3 | **roast** | Verify — independent evidence in fresh context | cupping | `verify`, `cupping`, `terreno-3-cupping` |
-| 4 | **brew** | Submit — checks, commit, push, draft PR, evidence | pour | `submit`, `pour`, `terreno-4-pour` |
-| 5 | **taste** | Review loop — CI + bot/human comments until mergeable; **includes former `autobot`** | dialin | `review`, `dialin`, `terreno-5-dialin` |
+| Stage | PASS | FAIL | BLOCKED/PENDING |
+| --- | --- | --- | --- |
+| Grow | Pick | Grow with artifact defects | Human/external gate |
+| Pick | Roast | Pick with new evidence-based hypothesis | Human/external gate |
+| Roast | Brew | Pick with exact failed criteria | Classify environment/external/human |
+| Brew | Taste | Pick/Roast/Brew according to evidence | Human/access gate |
+| Taste | Merge-ready | Focused Taste retry only with new evidence | `PENDING`: loop waits then Taste; `BLOCKED`: named gate |
 
-## Architecture
+## Shared result contract
 
-### The pipeline
-
-```mermaid
-flowchart LR
-  REQ["Request<br/>ticket / spec / idea"]
-  G["/terreno-1-grow<br/>(plan)"]
-  H["/terreno-2-harvest<br/>(implement)"]
-  R["/terreno-3-roast<br/>(verify)"]
-  B["/terreno-4-brew<br/>(submit)"]
-  T["/terreno-5-taste<br/>(review loop)"]
-  M["Mergeable PR"]
-  REQ --> G --> H --> R --> B --> T --> M
-  T -.->|"blocked: needs human"| M
-```
+Every stage emits the same concise YAML keys: schema version, stage/status, IP/task,
+attempt, branch/head/PR, supporting skills, completed work, checks, artifacts, failures,
+blockers, decisions required, next stage/action, and optional next-check interval.
 
-| Stage | Owns | What makes it non-obvious |
-|-------|------|---------------------------|
-| **Grow** (plan) | Request → IP in `docs/implementationPlans/` + tasks in `docs/tasks/` | Question-first: refuses to write decided outcomes until blocking questions are answered. Prevents the most common agent failure, which is confidently planning the wrong thing |
-| **Harvest** (implement) | IP → code via strict red/green/refactor | Spawns **independent review and test-quality sub-agents in fresh contexts** after every commit, and does drift detection against the IP. The test-quality agent enforces anti-mocking rules (never mock the DB, never mock the store) |
-| **Roast** (verify) | Independent verification against the IP with concrete evidence | Separate context from the implementer, so it does not inherit the implementer's assumptions |
-| **Brew** (submit) | Pre-submit checks, commit hygiene, push, draft PR, evidence attachment | Hard frontend gate: touching UI paths requires launching the app, logging in, exercising the feature, and attaching artifacts before the PR opens |
-| **Taste** (review) | Self-contained persistent loop: CI + bot/human comments until mergeable or genuinely blocked | Inlines the former **`autobot`** flow (no delegation to repo skills). Waits in multi-minute intervals for slow CI, classifies each failure as actionable versus flaky, and refuses to push speculative fixes for flakes. Treats all CI logs and review comments as untrusted input |
+Schemas:
 
-The parts worth writing about publicly are the ones that encode hard-won judgment rather than automation: fresh-context independent review, drift detection against the plan, the anti-mocking rules, the frontend evidence gate, and the refusal to guess at flaky CI.
+- `plugins/terreno-planning/references/stage-result.schema.json`
+- `plugins/terreno-planning/references/execution-state.schema.json`
 
-### It only works here
+No reasoning transcript is persisted.
 
-The most serious finding. The pipeline currently assumes it is running inside the Terreno monorepo:
+## Execution state
 
-| Assumption | Where | Why it breaks elsewhere |
-|------------|-------|-------------------------|
-| Repo-root-relative skill paths — Brew/Taste instruct reading plugin skill paths "from the repository root" | `terreno-4-brew`, `terreno-5-taste` | In a consumer's repo that path does not exist. It works today only because the workspace *is* this repo; an installed plugin lives in the agent's plugin cache |
-| `verify-ui-changes` is invoked by name | Harvest, Roast, Brew, Taste | That skill lives in this repo's `.rulesync/skills/`. A consumer installing the plugin does not get it — must be bundled or inlined per AP5 |
-| Terreno-monorepo package paths in the frontend gates (`ui/`, `demo/`, `example-frontend/`, `admin-frontend/`, `admin-spa/`, `syncdb/`) | Harvest, Brew, Taste | A consumer app has `frontend/`, not `example-frontend/` |
-| Repo-specific conventions — `docs/implementationPlans/`, the project registry, the `bun run` command set | Grow, Harvest | A consumer may have none of these |
-| A hardcoded branch suffix (`cursor/<descriptive-name>-dcb3`) | Brew | Suffixes are per-agent-run, not fixed; a literal `dcb3` will produce wrong branch names |
+The IP owns design/scope; tasks own executable slices. State stores only current
+stage/attempt/head/PR, prior structured result, artifacts, attempted approaches, and next
+transition. The outer loop preserves/transports it between fresh invocations.
 
-Fixing this is the difference between "our internal process, published" and "tooling Terreno users can adopt". It means parameterizing paths, bundling or declaring the skill dependencies, and detecting project layout instead of assuming it.
+State files are excluded from Brew commits unless a repository explicitly tracks them.
+After a PR exists, each Taste invocation also reconstructs current truth from the PR and
+current head rather than trusting stale state.
 
-### Overlap with existing repo skills
+## Stage contracts
 
-| Plugin stage | Repo skill (deprecated) |
-|--------------|-------------------------|
-| Brew | `.rulesync/skills/submit/`, `commit/`, `create-pr/` |
-| Taste | `.rulesync/skills/autobot/`, `check-watcher/`, `respond-to-review/` — **logic inlined into Taste; skills deprecated** |
-| Grow | `.rulesync/skills/ip/`, `design-blend/` |
-| Harvest | `.rulesync/skills/implement/` |
+### Grow
 
-Per AP5, **`submit` and `autobot` are deprecated** once Taste ships self-contained. Do not document two parallel pipelines.
+Researches repository facts, distinguishes human decisions from discoverable facts and
+low-risk conventional details, grills only genuine decisions, then writes approved,
+implementation-ready IP/tasks. Every acceptance criterion maps to verification.
 
-### Positioning
+### Pick
 
-The pipeline belongs in the **AI-native** pillar, alongside the MCP server. They are complementary and the distinction should be stated plainly:
+Implements one slice with Specify → Encode failing test → Fulfill → Clean the Kitchen.
+It consumes prior Roast/Taste evidence, preserves verified behavior, records failed
+approaches, runs independent implementation and test-quality reviews, and emits evidence
+for Roast.
 
-- **MCP server** = the *tool* layer. What an agent can see and do: search docs, generate conventional code, read merged logs, inspect client state, drive the running app.
-- **SDLC plugin** = the *process* layer. How an agent should sequence work: plan before coding, test-drive, review in a fresh context, verify independently, gate on evidence, then own the review loop.
+### Roast
 
-In the Django/Rails comparison table, this fills the row that currently reads "MCP server tools + skills — agent-driven rather than CLI-driven". Better framing: Django gives you `manage.py startapp`; Terreno gives you a reviewed path from ticket to mergeable PR.
+Runs independently, preferably in fresh context. It builds a requirement/evidence matrix
+and executes objective checks. It does not normally fix implementation code. `FAIL`
+returns exact expected/actual evidence to Pick.
 
-## Models / APIs / Notifications / UI
+### Brew
 
-None.
+Requires Roast proof, runs repository-defined final checks/review, commits/pushes, applies
+the PR template, attaches evidence, records PR/current head, and exits. It does not wait
+for CI or execute Taste.
 
-## Phases
+### Taste
 
-1. **Decide and sanitize** — answer AP2, generalize PHI language, remove Flourish specifics, fix the hardcoded branch suffix.
-2. **Rename stages** — grow/harvest/roast/brew/taste with aliases; bump plugin minor version (AP3).
-3. **Make it portable** — parameterize paths, bundle `verify-ui-changes` (or equivalent), detect project layout (AP4).
-4. **Consolidate Taste** — inline `autobot` + review-loop behavior; deprecate `submit`/`autobot` repo skills (AP5).
-5. **Document** — `plugins/README.md`, docs-site explainer and how-to, per-stage reference with alias callouts.
-6. **Position** — README, docs landing, comparison table, agent context files.
-7. **Distribute** — publish the marketplace; generate non-Cursor variants via rulesync (AP6).
+Reads current-head CI, mergeability, and unresolved review signals once. It classifies,
+performs one bounded set of actionable fixes, verifies/pushes if changed, emits
+`PASS`/`PENDING`/`BLOCKED`/`FAIL`, and exits. The outer loop schedules another invocation.
 
-## Feature Flags & Migrations
+## Supporting skills
 
-None. Renaming or aliasing stages (AP3) is a breaking change for anyone with the plugin installed — bump the plugin minor version and note it in `plugins/README.md`.
+Every stage inventories skills exposed by the harness/repository and loads those whose
+descriptions match the affected domains. Useful project skills may describe APIs, UI,
+data, schemas, prompts, test environments, deployment, documentation, or verification.
+No exact name is hard-required globally.
 
-## Not Included / Future Work
+If repository policy requires a capability and it is missing, the stage returns
+`BLOCKED`. If no skill applies, the stage infers conventions from repository instructions,
+code, tests, scripts, and analogous changes.
 
-- A healthcare-specific plugin variant retaining explicit PHI handling (AP2 option C).
-- Additional stages (design review, release, incident response).
-- Telemetry on stage usage or success rates.
-- Publishing to a public Cursor plugin directory beyond this repo's marketplace, if one exists.
+## Retry semantics and human gates
 
-## Files to Create / Modify
+Engineering retries are bounded and hypothesis-driven. Each attempt retains exact failure
+evidence and attempted approaches. Changing external state may be observed indefinitely
+by repeated fresh Taste invocations, but no lifecycle skill waits internally.
 
-**Create**
+Human gates include product semantics, architecture/security/data ownership, destructive
+or irreversible operations, permissions, public compatibility, major scope expansion,
+and policy-required approval. `BLOCKED` names the decision, evidence, options/tradeoffs,
+and recommended default.
 
-- `plugins/README.md`
-- `docs/explanation/agentic-sdlc.md`
-- `docs/how-to/use-the-terreno-plugin.md`
-- `docs/reference/sdlc-plugin.md`
-- `plugins/terreno-planning/LICENSE`
+## Compatibility migration
 
-**Modify**
+| Retired | Canonical |
+| --- | --- |
+| `terreno-1-blend` | `terreno-1-grow` |
+| `terreno-2-roast` (implementation) | `terreno-2-pick` |
+| `terreno-3-cupping` | `terreno-3-roast` (verification) |
+| `terreno-4-pour` | `terreno-4-brew` |
+| `terreno-5-dialin` | `terreno-5-taste` |
 
-- `plugins/terreno-planning/skills/*/SKILL.md` (all five: sanitization, portability, delegation)
-- `plugins/terreno-planning/.cursor-plugin/plugin.json`, `.cursor-plugin/marketplace.json`
-- `README.md`, `docs/README.md`, `docs/explanation/positioning.md`
-- `AGENTS.md` / `.rulesync/rules/00-root.md`, `CLAUDE-consumer.md`
-- `.rulesync/skills/submit/SKILL.md`, `autobot/SKILL.md` (cross-reference the plugin)
-- `scripts/check-license-coverage.ts` (cover `plugins/`)
-- `.rulesync/skills/build-terreno-app/SKILL.md` (use the pipeline if public)
+Former Grind orchestration becomes an outer-loop feature profile. Former plugin code
+review becomes a shared reference. Neither remains a sixth plugin skill.
 
-## Task List
+## Acceptance criteria
 
-See [`docs/tasks/agentic-sdlc-plugin.md`](../tasks/agentic-sdlc-plugin.md).
+- Exactly five canonical lifecycle skill directories exist.
+- Every stage has explicit preconditions, inputs, procedure, supporting skills, evidence,
+  success/failure/blocked conditions, and next transition.
+- A fresh Pick/Roast/Taste invocation can reconstruct its work from durable artifacts.
+- Result/status/transition values validate against the common schema.
+- Taste has no internal indefinite wait/observation loop.
+- Brew does not require same-context Taste execution.
+- Lifecycle skills contain no Terreno package names/commands that belong to project skills.
+- Repository skills remain local and discoverable/composable.
+- Backend/API, UI, and multi-invocation CI/review scenarios are documented.
+- Canonical sources and rulesync-generated copies validate cleanly.
 
-## Acceptance Criteria
+## Remaining assumptions / weaknesses
 
-- [ ] `plugins/README.md` explains the five stages, installation, and when to use each, in under 150 lines.
-- [ ] No plugin skill contains Flourish-specific vocabulary; sensitive-data handling is generalized per AP2.
-- [ ] No plugin skill contains a hardcoded branch suffix or a repo-root-relative path to a sibling skill.
-- [ ] The pipeline runs end to end in a **consumer app scaffolded by `terreno_bootstrap_app`**, not just in this monorepo — verified by taking one small feature from request to open PR.
-- [ ] Every skill dependency (`verify-ui-changes` at minimum) is either bundled with the plugin or declared with installation instructions.
-- [ ] Frontend path gates are derived from the project's actual layout rather than hardcoded monorepo package names.
-- [ ] Pour and Taste are self-contained per AP5; deprecated `submit`/`autobot` repo skills point to the plugin; no rule is stated in two places with different wording.
-- [ ] `docs/explanation/agentic-sdlc.md` explains the process layer versus the MCP tool layer and why fresh-context independent review matters.
-- [ ] `docs/how-to/use-the-terreno-plugin.md` takes a reader from installation to a merged PR.
-- [ ] `docs/reference/sdlc-plugin.md` documents each stage's scope, inputs, outputs, and boundaries.
-- [ ] `README.md` and `docs/README.md` name the pipeline under the AI-native pillar; the Django/Rails comparison table's generator row cites it.
-- [ ] Every public reference to a coffee-named stage gives its plain-language meaning at least once per page.
-- [ ] The marketplace is installable by the audience chosen in AP1, verified by a fresh install.
-- [ ] `plugins/` is covered by the license-coverage check.
-- [ ] `bun run rules:check` and `bun run check` pass.
+- The plugin defines state/results but does not ship a scheduler or durable remote state
+  service; the outer loop must preserve the fallback artifact between machines.
+- Some generated skill formats do not encode Cursor's `disable-model-invocation`
+  frontmatter. Enforcement of explicit invocation depends on that agent runtime.
+- Repository skill quality controls how much exact domain knowledge a stage can compose.
+  When no skill exists, agents still infer from instructions/code/tests.

package/src/docs/versioned/next/implementationPlans/apierror-standard-error-redesign.md

@@ -1,6 +1,7 @@
 # APIError redesign — standards-first extension of Error
 
 **Status:** Complete
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1080
 **Branch:** cursor/apierror-standard-error-redesign-e24a
 **Owner:** TBD
 **Created:** 2026-07-28

package/src/docs/versioned/next/implementationPlans/b2b-platform-program.md

@@ -1,6 +1,7 @@
 # Program: B2B platform
 
 **Status:** Draft — roadmap items drafted; decisions D1–D7 resolved 2026-08-09; first ten IPs open
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1095
 **Owner:** unassigned
 **Created:** 2026-08-09
 
@@ -31,7 +32,7 @@ org switcher, dark mode).
 
 | Track | Theme | IPs / roadmap items |
 |---|---|---|
-| A | Tenancy & access | `orgs-and-teams`, `rbac-permissions` (existing draft), `invitations-and-seats`, `org-management-ui` |
+| A | Tenancy & access | `orgs-and-teams`, `rbac-permissions` (Complete), `invitations-and-seats`, `org-management-ui` |
 | C | Communications (pluggable) | `comms-abstraction`, one item **per adapter**: `comms-adapter-expo-push` (first push adapter, per D4), `comms-adapter-twilio-sms`, `comms-adapter-twilio-verify`, `comms-adapter-sendgrid` (first mail adapter, per D2); operations: `comms-admin-dashboard`; consumers: `password-reset-and-email-verification`, `notification-center` |
 | B | Billing | `inbound-webhooks`, `billing-stripe` (web-first, per D1), `mobile-iap-revenuecat` (Future) |
 | D | Zero-to-deployed DX | `create-terreno-app`, `mongo-migrations` (deploy items already exist in the OSS launch program) |
@@ -92,17 +93,17 @@ All decisions resolved by the maintainer on 2026-08-09:
 
 | IP | Status | Tasks |
 |---|---|---|
-| [comms-abstraction](comms-abstraction.md) | Draft | [tasks](../tasks/comms-abstraction.md) |
+| [comms-abstraction](comms-abstraction.md) | Approved — Phase 1 gap-fill implemented | [tasks](../tasks/comms-abstraction.md) |
 | [comms-adapter-expo-push](comms-adapter-expo-push.md) | Draft | [tasks](../tasks/comms-adapter-expo-push.md) |
 | [comms-adapter-twilio-sms](comms-adapter-twilio-sms.md) | Draft | [tasks](../tasks/comms-adapter-twilio-sms.md) |
 | [comms-adapter-twilio-verify](comms-adapter-twilio-verify.md) | Draft | [tasks](../tasks/comms-adapter-twilio-verify.md) |
-| [comms-adapter-sendgrid](comms-adapter-sendgrid.md) | Draft | [tasks](../tasks/comms-adapter-sendgrid.md) |
+| [comms-adapter-sendgrid](comms-adapter-sendgrid.md) | In progress (Phase 1) | [tasks](../tasks/comms-adapter-sendgrid.md) |
 | [comms-admin-dashboard](comms-admin-dashboard.md) | Draft | [tasks](../tasks/comms-admin-dashboard.md) |
 | [password-reset-and-email-verification](password-reset-and-email-verification.md) | Draft | [tasks](../tasks/password-reset-and-email-verification.md) |
 | [orgs-and-teams](orgs-and-teams.md) | Draft | [tasks](../tasks/orgs-and-teams.md) |
 | [billing-stripe](billing-stripe.md) | Draft | [tasks](../tasks/billing-stripe.md) |
 | [native-module-baseline](native-module-baseline.md) | Draft | [tasks](../tasks/native-module-baseline.md) |
-| [rbac-permissions](rbac-permissions.md) | Draft (pre-existing API design) | TBD |
+| [rbac-permissions](rbac-permissions.md) | Complete (PR #932) | — |
 
 Remaining items (`inbound-webhooks`, `invitations-and-seats`, `org-management-ui`,
 `notification-center`, `framework-audit-log`, `rate-limiting`, `job-queues`, …) get IPs as

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

@@ -0,0 +1,48 @@
+# Research: comms-abstraction (finish pass)
+
+**Date:** 2026-08-20
+**Scope:** Reconcile the Draft IP with shipped `@terreno/comms` and name remaining roast work.
+
+## Shipped (do not re-plan)
+
+- Package scaffold, console adapters, `CommsApp`, `getCommsService()`, `PushToken` + routes,
+  `GET /comms/messages`, example-backend registration, CI/publish, reference docs, rules.
+- PRs: #1037 (foundation), #1050 (SendGrid adapter — owned by `comms-adapter-sendgrid`).
+- `SendResult.errorCode` / `errorClass` exist; `CommsMessage` stores them.
+- Mail-only inline retry on `errorClass: "transient"`.
+- Partial hooks: `onSend`, `onError`, `onRetry`, `onDeliveryEvent` (the last is never invoked).
+- Recipients redacted at rest (`redactRecipients`, default true).
+- Push pruning uses `isPermanentFailure`, not `errorClass`.
+
+## Gaps vs original IP (remaining)
+
+| Contract | IP | Code today |
+|---|---|---|
+| `beforeSend` mutate/cancel | specified | missing |
+| `onOptOut` / `OptOutEvent` | specified | missing |
+| `recordDeliveryEvent` / `recordOptOut` | implied (adapters feed events) | missing; `onDeliveryEvent` dead |
+| `CommsHookContext` | message, userId, isRetry, messageId | `{channel, provider, isRetry?}` |
+| `onRetry` | `(context, attempt)` | `(context, result)` — **keep shipped signature** |
+| Inline retry | all send paths | mail only; SMS/push/verification rethrow |
+| `attempts[]`, payload, retry links | dashboard-ready fields | missing |
+| `status: cancelled` | specified | not in enum |
+| Push prune | permanent failure | `isPermanentFailure` only |
+
+## Options considered (finish pass)
+
+Remaining work keeps the original IP as the contract. Shrink-to-code was rejected: the
+admin-dashboard IP depends on attempt history, payload retention, and `beforeSend`. A
+follow-up IP was rejected: the fields were already in this plan.
+
+Non-breaking choices for a published package:
+
+- Keep `onRetry(context, result)`; put `attempt` on `CommsHookContext`.
+- Keep `isPermanentFailure` as an adapter alias; facade also prunes on `errorClass: "permanent"`.
+- Unify provider throws to `SendResult` (no rethrow) so retry can run on every channel.
+
+## References
+
+- `comms/src/types.ts`, `commsService.ts`, `models/commsMessage.ts`
+- [comms-admin-dashboard.md](comms-admin-dashboard.md)
+- [comms-adapter-sendgrid.md](comms-adapter-sendgrid.md)
+- Roadmap: https://github.com/FlourishHealth/terreno/issues/1018