@terreno/mcp 57.2.0 → 57.3.0

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

@@ -1,107 +0,0 @@
-# Admin Script Runner — Maintenance Scripts via `AdminApp`
-
-**Status:** Implemented (ships with Admin UI v2 work; documented here as its own IP)  
-**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`
-
-## Goal
-
-Let backends register **named, server-side maintenance scripts** on `AdminApp`. Admins discover them from **`GET /admin/config`** (`scripts[]`: `name` + `description` only — no code). Execution is **`POST {adminBase}/scripts/:name/run?wetRun=true|false`**, which creates a **`BackgroundTask`**, runs the `runner` async, and supports **poll** (`GET …/scripts/tasks/:id`) and **cancel** (`DELETE …/scripts/tasks/:id`). The admin UI exposes **`AdminScriptList`** + **`AdminScriptRunModal`** (dry/wet, logs, polling) and a **`scriptRunner`** home widget that deep-links to the scripts screen.
-
-## Non-Goals
-
-- Uploading or editing script source from the browser.
-- Running scripts without authentication or without **admin** (`user.admin`).
-- Replacing **`POST /admin/background-tasks`** for arbitrary job kinds — scripts are the **curated** list; background-tasks remain the generic enqueue API for config-driven actions.
-
-## Decisions
-
-| Topic | Decision |
-|-------|-----------|
-| Task storage | Reuse **`BackgroundTask`** from `@terreno/api` (`api/src/scriptRunner.ts`); `taskType` = script `name`. |
-| Dry run | Query **`wetRun=false`** → `isDryRun: true` on the task; runners interpret per app conventions (see example-backend scripts). |
-| Config surface | Only **`name`** and **`description`** in `/admin/config` — runners stay server-only. |
-| UI entry | **`AdminShell`**: nav item when `scripts.length > 0`**; **`AdminHome`**: widget id **`scriptRunner`** (often placed in **`home.slots.navGlobal`** per Django-parity layout). |
-| SPA routing | **`admin-spa`**: dedicated `app/scripts.tsx` and dynamic **`/__scripts`** under `app/[model]/index.tsx`. |
-
-## Architecture
-
-```
-Browser
-  │
-  ├─ GET /admin/config          ← includes scripts: [{ name, description }]
-  │
-  ├─ POST /admin/scripts/:name/run?wetRun=…
-  │     → 201 { taskId }        ← creates BackgroundTask, kicks async runner
-  │
-  ├─ GET  /admin/scripts/tasks/:id   ← poll status / logs / result
-  │
-  └─ DELETE /admin/scripts/tasks/:id ← cancel (running → cancelled)
-```
-
-Types: `ScriptRunner`, `ScriptContext`, `ScriptResult` in `api/src/scriptRunner.ts`.
-
-### Phase completion (all shipped)
-
-| Phase | Scope | Evidence |
-|-------|--------|----------|
-| A | Types + `BackgroundTask` | `api/src/scriptRunner.ts` |
-| B | HTTP routes + config metadata | `admin-backend/src/adminApp.ts`; `admin-backend/src/adminApp.test.ts` (run, poll, cancel, wetRun, 403/404); `adminApp.models.test.ts` (`/admin/config` includes `scripts`) |
-| C | Hooks + UI | `admin-frontend/src/useAdminScripts.ts`, `AdminScriptList.tsx`, `AdminScriptRunModal.tsx`, `AdminShell.tsx`, `AdminHome.tsx`; tests + isolated specs |
-| D | SPA + example | `admin-spa/app/scripts.tsx`, `app/[model]/index.tsx` (`__scripts`); `example-backend/src/server.ts` `scripts` |
-
-Script **run** paths are exercised in **`admin-backend` tests**; the aggregated **`openapi.json`** snapshot in **`example-backend`** documents `/admin/config` (including the `scripts` array shape) and may not list every dynamic `POST /admin/scripts/:name/run` path depending on OpenAPI aggregation — runtime behavior is still covered by admin-backend tests.
-
-## APIs (implemented)
-
-| Method | Path | Purpose |
-|--------|------|--------|
-| POST | `{basePath}/scripts/:name/run` | Start script; body empty; **`wetRun`** query boolean. |
-| GET | `{basePath}/scripts/tasks/:taskId` | Poll task document (status, progress, logs, result). |
-| DELETE | `{basePath}/scripts/tasks/:taskId` | Request cancellation. |
-
-All script routes sit behind **`authenticateMiddleware()`**; run/poll/delete require **`user.admin`** (403 otherwise). See `admin-backend/src/adminApp.ts` (`mountScriptRoutes`).
-
-## UI (implemented)
-
-| Piece | Role |
-|-------|------|
-| `useAdminScripts` | RTK-injected endpoints for run / get task / cancel. |
-| `AdminScriptRunModal` | Dry vs wet run, start, poll, show logs/results, cancel. |
-| `AdminScriptList` | Lists scripts from config; opens modal. |
-| `AdminHome` widget `scriptRunner` | Card + “Open scripts” → `__scripts` route. |
-| `AdminShell` | Sidebar “Scripts” when `config.scripts.length > 0`. |
-
-## Consumer wiring (example)
-
-`example-backend/src/server.ts` — `new AdminApp({ … scripts: [{ name, description, runner }, …] })`. Runners may use only `wetRun` or also **`ScriptContext`** (`addLog`, `updateProgress`, `checkCancellation`) for long jobs.
-
-## Files (reference)
-
-| Area | Files |
-|------|--------|
-| Types + model | `api/src/scriptRunner.ts` (`ScriptRunner`, `BackgroundTask`, …) |
-| HTTP + OpenAPI | `admin-backend/src/adminApp.ts` |
-| Tests | `admin-backend/src/adminApp.test.ts`, `admin-backend/src/adminApp.models.test.ts` (ctx script) |
-| Hooks + UI | `admin-frontend/src/useAdminScripts.ts`, `AdminScriptList.tsx`, `AdminScriptRunModal.tsx`, `AdminHome.tsx`, `AdminShell.tsx` |
-| SPA | `admin-spa/app/scripts.tsx`, `admin-spa/app/[model]/index.tsx` (`__scripts`) |
-| Example | `example-backend/src/server.ts` (`scripts` array) |
-
-## Task list
-
-Executable checklist: **`docs/tasks/admin-script-runner.md`**.
-
-## Acceptance Criteria (summary)
-
-- [x] `GET /admin/config` includes `scripts` metadata when scripts are registered; empty array when none.  
-- [x] `POST …/scripts/:name/run` returns **201** + **`taskId`** for admins; **403** non-admin; **404** unknown name.  
-- [x] `GET …/scripts/tasks/:id` exposes task state for polling; `DELETE` cancels where allowed.  
-- [x] Runners receive **`wetRun`** and optional **`ScriptContext`**; failures mark task **failed**; **`TaskCancelledError`** respected.  
-- [x] Frontend: list + modal + polling; dry vs wet surfaced to query string.  
-- [x] `scriptRunner` home widget + shell nav reach the scripts screen without embedding the list inside the wrong slot (covered with Admin Home tests + layout rules in Admin UI v2 IP).
-
-## Future / not in scope
-
-- Per-script RBAC beyond “is admin”.  
-- Streaming log output over WebSockets (polling only today).  
-- Shared quota / concurrency limits across script and background-task queues.

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

@@ -1,204 +0,0 @@
-# Admin UI v2 — Django-Parity Admin (Config-Driven Shell)
-
-**Status:** Implemented (phased tasks complete; acceptance criteria verified in-repo)  
-**Branch:** Landed via `cursor/admin-ui-v2-backend-a736` (PR #782)  
-**Owner:** Josh Gachnang  
-**Created:** 2026-06-15  
-**Source:** Claude Design handoff (`Admin UI v2.html`, `admin/v2/schema.jsx`, design transcripts). Design blend plan approved in-session.
-
-**Companion IP — Admin script runner:** Maintenance scripts (`AdminApp` `scripts[]`, `/admin/scripts/*`, `AdminScriptList` / `scriptRunner` widget) are specified in **`docs/implementationPlans/admin-script-runner.md`** with tasks in **`docs/tasks/admin-script-runner.md`**.
-
-## Goal
-
-Evolve Terreno’s admin stack (`@terreno/admin-backend`, `@terreno/admin-frontend`, `@terreno/admin-spa`) so a **single `/admin/config` payload** can drive a **Django-style admin**: grouped sidebar, declarative **home `slots`** (header strip, above-the-fold band, main column, sidebar — analogous to Django admin template blocks), changelist with typed filters / search / sort allowlists / pagination / bulk actions (sync + background), schema-driven forms with fieldsets and readonly enforcement, permission-gated UI (e.g. delete off), and deep links to plugin screens (document storage, AI explorer). **REST-first:** every persisted entity uses `modelRouter` CRUD; only gated custom routes for bulk jobs and config aggregation.
-
-## Non-Goals
-
-- **Pixel-perfect clone** of the HTML prototype’s inline styles — match **behavior and information architecture**, using `@terreno/ui` theming.
-- **Replacing Font Awesome in the prototype** — Terreno UI uses FA6 names via `iconName`; map icons at integration boundary.
-- **Product-specific Flourish models in core packages** — example models may live in `example-backend`; framework ships **capabilities** and **reference wiring**.
-- **SSR / SEO** for admin.
-- **Cross-tenant URL structure** — tenant scoping remains consumer-owned via permissions and query filters.
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-| Config contract | Extend `GET /admin/config` with a **versioned** `schemaVersion` (e.g. `2`) and additive fields; preserve v1 consumers until admin-frontend major. |
-| List filters | Encode as **queryFields-compatible** filters (booleans, enums, text contains, date ranges, ref id); rail vs chips is **UI mode** only. |
-| Bulk sync actions | **`POST {basePath}{routePath}/bulk-patch`** with allowlisted patch keys, **≤ 1000** ids, OpenAPI documented. |
-| Background actions | Reuse **`BackgroundTask`** (`@terreno/api`) via **`POST /admin/background-tasks`** (or equivalent under `adminApp`) returning `taskId`; UI uses existing modal patterns (`AdminScriptRunModal` / `Modal` + progress). |
-| Autocomplete refs | **No custom search RPC** — `GET` list on referenced model with search query + small limit. |
-| Recent actions + audit | **Last phase**: optional **`AdminAuditLog`** model + list endpoint + home widget; **`recentActivity` last within the `sidebar` slot** (see home slots below). |
-| Realtime badge | **UI-only** flag from config (`realtime: true`); transport is app-level (polling/socket) out of scope for v1 framework. |
-| Home layout | **Slot-based `home.slots` (Solution A)** — mirrors Django admin template regions so tools/scripts can sit **above** the model grid without being “just another card”. See **Django layout mapping** below. |
-
-### Django layout mapping (reference)
-
-Stock Django `admin/index.html` splits the page into template **blocks**, not a flat widget list: main **`content`** is the app/model list (`app_list`); **`sidebar`** is “Recent actions” only; **`nav-global`** in `base.html` is an empty hook used for global shortcuts (e.g. scripts, reports) in the header row. Custom index pages inject markup **before** `app_list` by overriding `index_template` / `{% block content %}`. Terreno encodes the same idea in **`GET /admin/config`** as named **slots**, each an ordered list of **widget ids** resolved by a built-in + plugin registry.
-
-### `home.slots` contract (canonical)
-
-```typescript
-// Conceptual shape — exact TypeScript lives in admin-backend / shared types.
-home: {
-  title: string;
-  slots: {
-    navGlobal?: string[];   // Django nav-global analogue: compact header strip (e.g. scriptRunner shortcuts)
-    contentTop?: string[];  // Django “inject before app_list”: full-width row above model cards
-    main?: string[];        // Primary column: modelStats, modelsGrid, plugin widgets, etc.
-    sidebar?: string[];     // Django index sidebar: versionConfig, scriptRunner panel, recentActivity, …
-  };
-};
-```
-
-- **`scriptRunner`** (or any custom widget id) in **`navGlobal`** → horizontal tools, never mixed into the model card grid.
-- Same id in **`contentTop`** → prominent band **above** `main`.
-- **`recentActivity`** belongs in **`sidebar`** when used; it must be **last in `sidebar`** if present (Django keeps recent actions in the sidebar column, below other sidebar content you add).
-- Omitted slots render nothing. **`main`** default for backward compat: treat as `["modelsGrid"]` when `schemaVersion >= 2` and `slots` missing but legacy `widgets[]` exists — implementation detail for migration.
-
-## Architecture
-
-```
-Browser (admin-spa / embedded admin-frontend)
-    │
-    ├─ GET /admin/config          ← aggregated model meta + home + screens + scripts
-    │
-    ├─ CRUD  /admin/{resource}/*  ← modelRouter per registered model (IsAdmin)
-    │
-    ├─ POST /admin/{resource}/bulk-patch
-    │
-    └─ POST /admin/background-tasks  → BackgroundTask queue → progress poll/subscribe (app-defined)
-```
-
-Plugin screens (**Documents**, **AI requests**) remain **routes owned by** `@terreno/document-storage` / `@terreno/ai`; config only exposes **navigation entries** (`customScreens[]`).
-
-## Models
-
-Domain models in the prototype are **illustrative** (FeatureFlag, CompanyOrganization, DotPhrase, ExternalClinician, HealthEvent, InsurancePlan, ReferralMethod, ReferralSource, UserStatus). Implementations in consumer apps register Mongoose models with `AdminApp`. Framework work ensures **metadata** and **routers** support their shapes:
-
-| Model | Key relations | Indexes / notes |
-|-------|----------------|-----------------|
-| FeatureFlag | — | Unique `key`; query fields for list/search; hidden `evaluationCache` optional |
-| CompanyOrganization | — | Name search |
-| ExternalClinician | `organization` → CompanyOrganization | Index `organization` |
-| DotPhrase | — | `delete` permission optional **off** |
-| Others | — | Standard list/query/sort fields per config |
-
-**AdminAuditLog** (Phase last): `verb`, `modelName`, `recordLabel`, `recordId?`, `actorId`, `created`; list for home widget; optional TTL index for retention.
-
-**BackgroundTask**: use existing `@terreno/api` type used by `AdminApp` / scripts — no new model if already sufficient; document enqueue contract in OpenAPI.
-
-## APIs
-
-### CRUD (per registered model)
-
-- `POST /admin/{resource}` — create  
-- `GET /admin/{resource}` — list (pagination, sort, queryFields filters)  
-- `GET /admin/{resource}/:id` — read  
-- `PATCH /admin/{resource}/:id` — update (strip readonly server-side)  
-- `DELETE /admin/{resource}/:id` — delete or **disabled** when permissions say so  
-
-All **`Permissions.IsAdmin`** (or stricter consumer override).
-
-### Custom (Action Decision Gate — approved)
-
-| Endpoint | Purpose |
-|----------|---------|
-| `GET /admin/config` | **Aggregation** of models, fields, UI hints, scripts, screens, **`home.slots`** (widget ids per region) |
-| `POST /admin/{resource}/bulk-patch` | **Command + performance**: multi-row patch, cap ids, single audit hook |
-| `POST /admin/background-tasks` | **Command**: enqueue long-running admin job tied to selection |
-
-### Rejected custom routes
-
-| Idea | Fallback |
-|------|----------|
-| Dedicated ref `/search` RPC | `GET` list + query |
-| WebSocket as “admin action” | App transport; REST remains SoT |
-
-## Notifications
-
-- **In-app only:** `@terreno/ui` **Toast** after save, bulk action, enqueue background task, script completion.  
-- **No email/push** for admin events in this IP.
-
-## UI
-
-- **Shell:** `Box` / `Page`, grouped sidebar (`Text` section headers, `Button` / `IconButton`, `Avatar`), sticky top bar with breadcrumbs (`Heading`, `Link`).  
-- **Home:** Render in order: **`navGlobal` + `contentTop` merged into one horizontal top band** (same flex row, wrapping) → two-column **`main`** + **`sidebar`** (Terreno `Box` / `SplitPage`-style layout). Each slot iterates widget ids from `home.slots`; **`recentActivity` last inside `sidebar`** when present.  
-- **List:** `DataTable`, `Pagination`, `TextField` (debounced search), filter rail (`Card` + fields) or chip mode (`SelectField` / date inputs), row selection, bulk `SelectField` + `Modal` confirms, inline boolean via PATCH.  
-- **Form:** `Accordion` or stacked `Card` for fieldsets; `TextField`, `NumberField`, `BooleanField`, `SelectField`, `DateTimeField`; readonly fields disabled + helper copy; ref picker = debounced list fetch.  
-- **Danger zone:** `Button` destructive + `Modal`; **hidden** when delete permission false.  
-- **Background run:** `Modal` + `Spinner` + log `Text` (reuse `AdminScriptRunModal` patterns).  
-- **testIDs:** `admin-home`, `admin-home-slot-top` (combined `navGlobal` + `contentTop` widgets), `admin-home-slot-main`, `admin-home-slot-sidebar`, `admin-list-{model}`, `admin-form-{model}`, `filter-{field}`, `bulk-action`, `widget-recent-activity` (last in **sidebar** slot).
-
-## Phases
-
-1. **Backend contracts** — extend config response; bulk-patch; background enqueue; OpenAPI + tests.  
-2. **CRUD parity** — ensure each registered model’s `queryFields`, sort, response stripping align with config lists.  
-3. **Frontend shell + list + form** — consume v2 config; `DataTable` list; form fieldsets/readonly/autocomplete.  
-4. **Home widgets** — registry + **`home.slots`** layout + plugin widget IDs + placement (`navGlobal` and `contentTop` render in one top row; `main` vs `sidebar`).  
-5. **admin-spa + example** — runnable demo; link plugin screens.  
-6. **Audit log & recent actions (last)** — `AdminAuditLog` model (if approved for deployment), logging hooks, `GET` list, wire **`recentActivity` as the final id in `home.slots.sidebar`**.
-
-### Phase completion (all shipped)
-
-| # | Scope | Evidence |
-|---|--------|----------|
-| 1 | Config + OpenAPI for `/admin/config` | `admin-backend/src/adminApp.models.test.ts` (`schemaVersion`, `home.slots`, scripts metadata) |
-| 2 | Bulk-patch + background-tasks | Same file + `adminApp.test.ts` |
-| 3 | Example modelRouter alignment | `example-backend/src/server.ts` registrations |
-| 4–6 | Shell, list, form | `admin-frontend` compile + `AdminModelTable.test.tsx`, `AdminModelForm.test.tsx`, `AdminBreadcrumbs.test.tsx` |
-| 7 | Home widgets + slots | `admin-frontend/src/AdminHome.test.tsx` |
-| 8 | admin-spa + example | `admin-spa/app/**`, Playwright `admin-spa/e2e/**` |
-| 9 | Audit + recent activity | `example-backend` `AdminAuditLog` + `onAdminAudit`; `admin-backend` **`AdminApp onAdminAudit`** tests (POST/PATCH/DELETE); `AdminHome.test.tsx` sidebar order |
-
-
-## Feature Flags & Migrations
-
-- **Config `schemaVersion`:** clients switch parsers/layout when `>= 2`.  
-- **No DB migration in framework packages** — consumer apps migrate their own collections.  
-- Optional **feature flag** in consumer: `ADMIN_UI_V2` to toggle layout component root (defer if unnecessary).
-
-## Activity Log & User Updates
-
-- **Deferred to final phase** so list/form/config stabilize first.  
-- On completion: admin mutations optionally write **AdminAuditLog** rows; home **Recent actions** reads latest N.  
-- User-visible copy: past tense verbs (“changed”, “added”, “deleted”) matching prototype semantics.
-
-## Not Included / Future Work
-
-- Full **realtime push** of flag changes to all clients (server fan-out).  
-- **Per-field row inline edit** beyond booleans (e.g. numeric inline).  
-- **Cross-model global search**.  
-- **Export CSV** from changelist.  
-- **Granular admin roles** beyond `IsAdmin`.
-
-## Files to Create / Modify (high level)
-
-| Area | Files (expected) |
-|------|------------------|
-| admin-backend | `src/adminApp.ts` (config shape, bulk route, background enqueue), tests |
-| admin-frontend | `AdminModelTable.tsx`, `AdminModelForm.tsx`, new layout/sidebar modules, `useAdminConfig.tsx`, types |
-| admin-spa | Router screens for home v2, list v2, form v2; SDK regen |
-| api | Only if `BackgroundTask` / OpenAPI helpers need small extensions |
-| docs | This IP + `docs/tasks/admin-ui-v2-django-parity.md` |
-
-## Task List
-
-See **`docs/tasks/admin-ui-v2-django-parity.md`** for the executable, phased checklist (audit log / recent actions **last**).
-
-**Script runner tasks** (same release train): **`docs/tasks/admin-script-runner.md`**.
-
-## Acceptance Criteria (summary)
-
-- [x] `GET /admin/config` returns v2 fields without breaking v1 layout (additive + `schemaVersion`).  
-- [x] `POST .../bulk-patch` rejects >1000 ids and unknown patch keys.  
-- [x] Background enqueue returns task id; admin UI shows progress path consistent with scripts.  
-- [x] List: search debounced; filters typed; sort allowlist enforced server-side.  
-- [x] Form: readonly fields cannot be persisted via PATCH.  
-- [x] Delete UI absent when model `delete` permission disabled.  
-- [x] Home: `home.slots` drives layout; `scriptRunner` (or custom tools) in `navGlobal` or `contentTop` never appears inside the **`main`** model grid unless also listed under `main`.  
-- [x] Home: when `recentActivity` is configured, it is **last in `slots.sidebar`**.  
-- [x] Phase last: audit entries created for configured mutations; recent widget shows data from API.
-
-Verification pointers: `admin-backend/src/adminApp.models.test.ts` (config `schemaVersion`, bulk-patch caps/allowlist, background-tasks, **`AdminApp onAdminAudit`** hooks after POST/PATCH/DELETE), `admin-frontend/src/AdminModelForm.test.tsx` (readonly PATCH body), `admin-frontend/src/AdminHome.test.tsx` (slot/widget placement + sidebar order), `example-backend` admin registration + audit model + OpenAPI snapshot.

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

@@ -1,177 +0,0 @@
-# Implementation Plan: Publish and Document the Agentic SDLC Plugin
-
-**Status:** Draft — key decisions recorded (2026-07-29)
-**Priority:** High
-**Effort:** Big batch
-**Owner:** unassigned
-**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.
-
-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.
-
-## Non-Goals
-
-- 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.
-
-## Blocking questions
-
-**Recorded 2026-07-29** (see program [P11](oss-launch-program.md#blocking-questions-program-level)).
-
-| # | 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 |
-
-### Stage mapping (rename + aliases)
-
-| # | 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` |
-
-## Architecture
-
-### 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
-```
-
-| 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 reactive loop: CI + bot/human comments until mergeable or timeout | Inlines the former **`autobot`** flow (no delegation to repo skills). Classifies each CI failure as actionable versus flaky and refuses to push speculative fixes for flakes. Treats all CI logs and review comments as untrusted input |
-
-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.
-
-### It only works here
-
-The most serious finding. The pipeline currently assumes it is running inside the Terreno monorepo:
-
-| 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 |
-
-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.
-
-### Overlap with existing repo skills
-
-| 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/` |
-
-Per AP5, **`submit` and `autobot` are deprecated** once Taste ships self-contained. Do not document two parallel pipelines.
-
-### Positioning
-
-The pipeline belongs in the **AI-native** pillar, alongside the MCP server. They are complementary and the distinction should be stated plainly:
-
-- **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.
-
-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.
-
-## Models / APIs / Notifications / UI
-
-None.
-
-## Phases
-
-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).
-
-## Feature Flags & Migrations
-
-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`.
-
-## Not Included / Future Work
-
-- 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.
-
-## Files to Create / Modify
-
-**Create**
-
-- `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`
-
-**Modify**
-
-- `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)
-
-## Task List
-
-See [`docs/tasks/agentic-sdlc-plugin.md`](../tasks/agentic-sdlc-plugin.md).
-
-## Acceptance Criteria
-
-- [ ] `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.