@terreno/mcp 0.30.0 → 0.31.0

package/dist/docs/versioned/next/tasks/public-roadmap-github.md

@@ -13,19 +13,19 @@ See: [`docs/implementationPlans/public-roadmap-github.md`](../implementationPlan
 
 ## Phase 1: Discussions
 
-- [ ] **Task 1.1**: Document Discussion category setup
+- [x] **Task 1.1**: Document Discussion category setup
   - Description: Create `docs/explanation/roadmap-process.md`. Start with a "Maintainer setup" section listing the seven Discussion categories from the IP with their exact names, formats (Announcement / Question-Answer / Open-ended), descriptions, and display order. For each, include the description text to paste into the GitHub UI (one to two sentences, written for outside users). Note that Discussions must first be enabled in Settings → General → Features.
   - Files: `docs/explanation/roadmap-process.md` (new)
   - Depends on: none
   - Acceptance: all seven categories are listed with name, format, description, and order; the Announcements category is marked maintainers-only.
 
-- [ ] **Task 1.2**: Write the pinned intro posts
+- [x] **Task 1.2**: Write the pinned intro posts
   - Description: In `docs/explanation/roadmap-process.md`, add a "Pinned posts" section containing the full markdown body for one pinned post per category. Each should say what belongs there, what does not, and where to go instead. The Ideas post must explain that ideas are the intake funnel and that maintainers promote them to issues. The Agents & AI post must point at the MCP setup docs and the skills directory. The Q&A post must link `docs/how-to/` and note that recurring questions become how-to guides.
   - Files: `docs/explanation/roadmap-process.md`
   - Depends on: Task 1.1
   - Acceptance: seven post bodies exist, each under 200 words, each naming an alternative destination for off-topic content.
 
-- [ ] **Task 1.3**: Add Discussion templates
+- [x] **Task 1.3**: Add Discussion templates
   - Description: Create `.github/DISCUSSION_TEMPLATE/rfc.yml` with fields: title guidance, Summary (required), Motivation (required), Detailed design (required), Alternatives considered (required), Drawbacks, Unresolved questions, and a checkbox acknowledging that accepted RFCs become IPs in `docs/implementationPlans/`. Create `.github/DISCUSSION_TEMPLATE/ideas.yml` with: Problem you are hitting (required), What you tried, Rough idea for a solution, and Would you be willing to help implement. Both must set the correct `labels:` and target the right category via the filename convention.
   - Files: `.github/DISCUSSION_TEMPLATE/rfc.yml` (new), `.github/DISCUSSION_TEMPLATE/ideas.yml` (new)
   - Depends on: Task 1.1
@@ -33,13 +33,13 @@ See: [`docs/implementationPlans/public-roadmap-github.md`](../implementationPlan
 
 ## Phase 2: Project board
 
-- [ ] **Task 2.1**: Document Project board setup
+- [x] **Task 2.1**: Document Project board setup
   - Description: Add a "Project board" section to `docs/explanation/roadmap-process.md` specifying: the Project name (`Terreno Roadmap`), whether it is repo- or org-level, the six fields with their exact types and option values from the IP, and the four views with their layout, grouping, and filters. Include the `gh project` commands a maintainer can run for the parts the CLI supports, and mark the rest as UI-only.
   - Files: `docs/explanation/roadmap-process.md`
   - Depends on: Task 1.1
   - Acceptance: all six fields and four views are specified precisely enough to recreate without further decisions; option values match the IP tables exactly.
 
-- [ ] **Task 2.2**: Write the tracking-issue bodies for this program's IPs
+- [x] **Task 2.2**: Write the tracking-issue bodies for this program's IPs
   - Description: Create `docs/explanation/roadmap-seed-issues.md` containing one ready-to-paste issue body per IP listed in `docs/implementationPlans/oss-launch-program.md`. Each body must include: a one-paragraph summary written for an outside reader (not internal shorthand), a link to the IP file, a link to the task file, the RTK deprecation flag, the dependencies, and the labels and Project field values to set (`Area`, `Target`, `Impact`, `IP`). Read each IP file to write its summary — do not paraphrase from the program index alone.
   - Files: `docs/explanation/roadmap-seed-issues.md` (new)
   - Depends on: Task 2.1
@@ -47,19 +47,19 @@ See: [`docs/implementationPlans/public-roadmap-github.md`](../implementationPlan
 
 ## Phase 3: Labels and triage
 
-- [ ] **Task 3.1**: Define the label set as data
+- [x] **Task 3.1**: Define the label set as data
   - Description: Create `.github/labels.yml` listing every label from the IP taxonomy with `name`, `color`, and `description`. Use a consistent color family per prefix (for example one hue for `area:`, another for `type:`, another for `status:`, and distinct colors for the bare labels). Add a "Labels" section to `docs/explanation/roadmap-process.md` explaining that `.github/labels.yml` is the source of truth and how to apply it (`gh label create` loop or a label-sync action), plus which GitHub default labels to delete.
   - Files: `.github/labels.yml` (new), `docs/explanation/roadmap-process.md`
   - Depends on: Task 1.1
   - Acceptance: `.github/labels.yml` parses as valid YAML and contains every label in the IP taxonomy table with no duplicates; colors are valid six-digit hex without `#`.
 
-- [ ] **Task 3.2**: Add the triage workflow
+- [x] **Task 3.2**: Add the triage workflow
   - Description: Create `.github/workflows/triage.yml`. On `issues: [opened]`, add the `status:needs-triage` label. Then read the issue body for the package dropdown value rendered by the issue forms and map it to the matching `area:*` label (for example `@terreno/api` → `area:api`, `docs` → `area:docs`). Implement the mapping in an inline `actions/github-script` step with an explicit lookup object; if no match is found, add no area label and leave a comment asking the reporter to specify. Validate required inputs before use per the repo convention.
   - Files: `.github/workflows/triage.yml` (new)
   - Depends on: Task 3.1
   - Acceptance: workflow parses as valid YAML; the mapping object covers every option in `bug_report.yml`'s package dropdown; the no-match path does not throw.
 
-- [ ] **Task 3.3**: Document the backfill triage pass
+- [x] **Task 3.3**: Document the backfill triage pass
   - Description: Add a "One-time backfill" section to `docs/explanation/roadmap-process.md` describing how to triage existing open issues and PRs onto the new taxonomy: run `gh issue list --state open --limit 200 --json number,title,labels`, assign one `area:` and one `type:` label each, add anything still relevant to the board with `Status = Inbox`, and close or label `status:wontfix` anything stale beyond six months. Include the read-only `gh` commands for producing the working list.
   - Files: `docs/explanation/roadmap-process.md`
   - Depends on: Task 3.1
@@ -67,25 +67,25 @@ See: [`docs/implementationPlans/public-roadmap-github.md`](../implementationPlan
 
 ## Phase 4: Roadmap generation
 
-- [ ] **Task 4.1**: Write the roadmap generator
+- [x] **Task 4.1**: Write the roadmap generator
   - Description: Create `scripts/generate-roadmap.ts` (Bun, TypeScript, `const` arrow functions with explicit return types, no new dependencies). It queries the GitHub GraphQL API for the `Terreno Roadmap` ProjectV2 items and their field values, then writes `ROADMAP.md`: a header explaining that the board is the source of truth and that no dates are promised, then sections grouped by `Target` (current release first, then `Next`, then `Future`), and within each, subsections by `Area`. Each item renders as a bullet with its title, issue link, `Impact`, and an IP link when the `IP` field is set. Exclude items with `Status` of `Declined`. Read the token from `GITHUB_TOKEN` and the project number from `TERRENO_PROJECT_NUMBER`; fail with a clear message listing missing variables when either is absent. Use Luxon for the generated-at timestamp.
   - Files: `scripts/generate-roadmap.ts` (new), `package.json` (add a `roadmap:generate` script)
   - Depends on: Task 2.1
   - Acceptance: running with both env vars unset prints an error naming both and exits non-zero; with a valid token it writes a `ROADMAP.md` matching the described structure; `bun run lint` passes.
 
-- [ ] **Task 4.2**: Add the roadmap workflow
+- [x] **Task 4.2**: Add the roadmap workflow
   - Description: Create `.github/workflows/roadmap-generate.yml` running on `schedule` (daily) and `workflow_dispatch`. Validate `GITHUB_TOKEN`/PAT and `TERRENO_PROJECT_NUMBER` at job start with the repo's fail-fast pattern. Run `bun run roadmap:generate`, then commit and push `ROADMAP.md` only if `git diff --quiet` reports changes. Use a bot identity for the commit.
   - Files: `.github/workflows/roadmap-generate.yml` (new)
   - Depends on: Task 4.1
   - Acceptance: workflow parses as valid YAML; the secret-validation step lists every required variable; the commit step is conditional on a real diff.
 
-- [ ] **Task 4.3**: Seed `ROADMAP.md` and link it
+- [x] **Task 4.3**: Seed `ROADMAP.md` and link it
   - Description: Commit an initial hand-written `ROADMAP.md` (the generator will overwrite it later) built from the IPs in `docs/implementationPlans/oss-launch-program.md` plus the active plans in `PLAN_INDEX.md`. Add a note at the top that it is generated from the Project board. Link it from `README.md` and add it to the docs site sidebar in `website/docusaurus.config.ts` (or the sidebars file if navigation is defined there — check both).
   - Files: `ROADMAP.md` (new), `README.md`, `website/docusaurus.config.ts` or `website/sidebars.ts`
   - Depends on: Task 4.1
   - Acceptance: `ROADMAP.md` lists every IP in the program with a `Target`; the docs site builds (`bun run website:build`) with the new nav entry; the README links it.
 
-- [ ] **Task 4.4**: Add the docs feedback footer link
+- [x] **Task 4.4**: Add the docs feedback footer link
   - Description: In `website/docusaurus.config.ts`, add a footer link (or theme config item) pointing at the Docs feedback Discussions category. If Docusaurus's `editUrl` mechanism is the better fit for per-page feedback, add the discussion link alongside the existing `editUrl` rather than replacing it.
   - Files: `website/docusaurus.config.ts`
   - Depends on: Task 1.1
@@ -93,19 +93,19 @@ See: [`docs/implementationPlans/public-roadmap-github.md`](../implementationPlan
 
 ## Phase 5: Linear bridge
 
-- [ ] **Task 5.1**: Document the Linear bridge rules
+- [x] **Task 5.1**: Document the Linear bridge rules
   - Description: Add a "Linear bridge" section to `docs/explanation/roadmap-process.md` covering: which artifacts live where (GitHub = public discussion, issues, roadmap state; Linear = sprint execution; `docs/implementationPlans/` = design), the one-way GitHub → Linear intake triggered by the `tracked` label, the rule that Linear status is not synced back and that GitHub state changes via `Fixes #NNN` on merge, how internally-originated public work gets a manual GitHub issue, and an explicit statement that internal-only Linear work is never mirrored. Explain *why* status is not two-way synced.
   - Files: `docs/explanation/roadmap-process.md`
   - Depends on: Task 3.1
   - Acceptance: the section states the direction of every sync, names the trigger label, and gives the reason two-way status sync was rejected.
 
-- [ ] **Task 5.2**: Document the intake flow in `CONTRIBUTING.md`
+- [x] **Task 5.2**: Document the intake flow in `CONTRIBUTING.md`
   - Description: Add a "How work gets planned" section to `CONTRIBUTING.md`, under 30 lines: file an Ideas discussion → maintainer promotes to an issue → issue is triaged onto the roadmap board → substantial work gets an IP → implementation. Add the RFC path for public API changes and new packages. Link `ROADMAP.md`, the Discussions categories, and `docs/implementationPlans/README.md`.
   - Files: `CONTRIBUTING.md`
   - Depends on: Task 5.1
   - Acceptance: the section is under 30 lines, links all three destinations, and matches the flow diagram in the IP.
 
-- [ ] **Task 5.3**: Add the release announcement step
+- [x] **Task 5.3**: Add the release announcement step
   - Description: Edit `.rulesync/skills/release/SKILL.md` to add a step: after publishing a release that includes breaking changes or deprecations, post a discussion in the Announcements category summarizing the change, linking the changelog section and the relevant upgrade note in `mcp-server/src/docs/upgrades/`. Regenerate mirrors with `bun run rules`.
   - Files: `.rulesync/skills/release/SKILL.md` plus generated mirrors
   - Depends on: Task 1.1

package/dist/docs/versioned/next/tasks/rtk-to-syncdb-migration-docs.md

@@ -2,7 +2,9 @@
 
 See: [`docs/implementationPlans/rtk-to-syncdb-migration-docs.md`](../implementationPlans/rtk-to-syncdb-migration-docs.md)
 
-**RTK deprecation flag:** **Blocked.** Do not start any task in this file until PR [#869](https://github.com/flourishhealth/terreno/pull/869) is merged into `master`. Verify with `git log --oneline master | rg -i syncdb` before beginning.
+**RTK deprecation flag:** **Blocked.** Do not start any task in this file until a `@terreno/syncdb` package is merged into `master`. PR [#869](https://github.com/flourishhealth/terreno/pull/869) was the delivery vehicle but is **closed, not merged** (checked 2026-08-09) and no `syncdb/` package exists on `master`. Verify with `git log --oneline master | rg -i syncdb` before beginning.
+
+**Migration strategy (decision M6, reaffirmed 2026-08-09):** this IP ships *context for an AI agent to perform the migration*, not a migration script or codemod. The deliverables are the syncdb reference, a guide built from verified before/after pairs, and the `upgrading-terreno` skill that drives an agent through a per-screen `USE_SYNCDB` rollout. See the "Migration strategy: AI-context-first" section in the IP. Do not author a codemod as the primary path.
 
 ## Instructions for the implementing agent
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terreno/mcp",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "MCP server for Terreno - provides documentation, tools, and prompts for building full-stack apps",
   "type": "module",
   "main": "dist/index.js",
@@ -27,9 +27,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "0.30.0",
+    "@terreno/api": "0.31.0",
     "minisearch": "^7.2.0",
-    "mongoose": "8.23.0"
+    "mongoose": "9.7.4"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.6",
@@ -38,6 +38,7 @@
     "typescript": "~5.9.2"
   },
   "files": [
+    "LICENSE",
     "dist",
     "src/docs"
   ],

package/src/docs/templates/bootstrap/backend/types/models/userTypes.template.md

@@ -1,16 +1,17 @@
-/// <reference types="passport-local-mongoose" />
 import type {APIErrorConstructor} from "@terreno/api";
 import type mongoose from "mongoose";
-import type {Document, FilterQuery, Model} from "mongoose";
+import type {Document, Model} from "mongoose";
+
+type ModelQuery<T> = Partial<Record<keyof T, unknown>> & Record<string, unknown>;
 
 export interface DefaultStatics<T> {
   findOneOrNone(
-    query: FilterQuery<T>,
+    query: ModelQuery<T>,
     errorArgs?: Partial<APIErrorConstructor>
   ): Promise<(Document & T) | null>;
 
   findExactlyOne(
-    query: FilterQuery<T>,
+    query: ModelQuery<T>,
     errorArgs?: Partial<APIErrorConstructor>
   ): Promise<Document & T>;
 }

package/src/docs/templates/tools/model.template.md

@@ -5,9 +5,11 @@ interface {{Name}}Document extends mongoose.Document {
 {{interfaceFields}}
 }
 
+type ModelQuery<T> = Partial<Record<keyof T, unknown>> & Record<string, unknown>;
+
 interface {{Name}}Model extends mongoose.Model<{{Name}}Document> {
-  findOneOrNone(query: mongoose.FilterQuery<{{Name}}Document>): Promise<{{Name}}Document | null>;
-  findExactlyOne(query: mongoose.FilterQuery<{{Name}}Document>): Promise<{{Name}}Document>;
+  findOneOrNone(query: ModelQuery<{{Name}}Document>): Promise<{{Name}}Document | null>;
+  findExactlyOne(query: ModelQuery<{{Name}}Document>): Promise<{{Name}}Document>;
 }
 
 const {{lowerName}}Schema = new mongoose.Schema<{{Name}}Document, {{Name}}Model>(

package/src/docs/upgrades/0.31.0.md

@@ -0,0 +1,60 @@
+# 0.31.0
+
+Terreno packages move in lockstep. Nothing in this release removes or renames a public
+export, so most apps upgrade by bumping the `@terreno/*` versions and running:
+
+- `bun run compile` and `bun run lint` at the repo root
+- `cd <your frontend> && bun run sdk` after any `@terreno/api` route or model surface change
+
+## Mongoose 9 is now supported (Mongoose 8 still works)
+
+Every published package that talks to Mongoose (`api`, `test`, `admin-backend`, `ai`,
+`feature-flags`) widened its peer dependency to `^8.0.0 || ^9.0.0`. Terreno itself
+develops against Mongoose 9.7.4.
+
+You can stay on Mongoose 8 with no changes. If you upgrade your app to Mongoose 9, the
+changes that mattered inside Terreno will most likely matter in your code too:
+
+```typescript
+// Before (Mongoose 8)
+await Model.findOneAndUpdate(filter, update, {new: true});
+
+// After (Mongoose 9)
+await Model.findOneAndUpdate(filter, update, {returnDocument: "after"});
+```
+
+- Aggregation-pipeline updates must pass `updatePipeline: true` to `updateMany`.
+- Query middleware no longer takes the legacy `next()` callback — use the async form.
+- Array schema paths expose `getEmbeddedSchemaType()`; the private `caster` property is gone.
+- Mongoose 9 ships its own types, so `@types/mongodb` and
+  `@types/passport-local-mongoose` should be removed from your dev dependencies.
+- Pin `bson` to `7.2.0` if your lockfile resolves an older copy alongside Mongoose 9.
+
+Mongoose 9 requires Node >= 20.19.0. Terreno's root `package.json` now declares that
+engine range for local development.
+
+## `@terreno/api` type changes
+
+Both changes widen or relax types; they are source-compatible for normal usage, but
+explicit annotations may need updating:
+
+- `modelRouter` now accepts `Model<T, any, any, any, any, any>` instead of `Model<T>`,
+  so models with custom query helpers, methods, or virtuals no longer need a cast.
+- `findOneOrNoneFor(model, query)` takes `ModelQuery<T>` (a partial record keyed by the
+  document fields) instead of Mongoose's `FilterQuery<T>`. If you were building a
+  `FilterQuery<T>` value to pass in, it still works; if you were annotating the variable
+  as `FilterQuery<T>` and relying on operator typing, switch to `ModelQuery<T>`.
+
+## `@terreno/admin-backend` array field metadata
+
+`GET /admin/config` derives array item metadata (`itemType`, `itemRef`, `itemEnum`) from
+Mongoose's public `getEmbeddedSchemaType()` when available, falling back to the Mongoose 8
+`caster` shape. `itemEnum` is only emitted when the embedded enum is an array, so an enum
+declared as an object map no longer produces a malformed `itemEnum`. Admin clients that
+read `itemEnum` should treat it as optional.
+
+## License changed from Apache-2.0 to MIT
+
+All published `@terreno/*` packages are now MIT licensed and ship a `LICENSE` file in the
+package tarball. No code change is required; update any license inventory or attribution
+list that pinned Terreno as Apache-2.0.

package/src/docs/versioned/0.30.0/explanation/explicit-any-policy.md

@@ -0,0 +1,88 @@
+# Explicit `any` policy
+
+Terreno discourages `any` in TypeScript. Biome blocks **new** unsuppressed explicit `any` at lint time; this document describes how we inventory existing usages and track remediation.
+
+## Why
+
+- **Type safety**: `any` disables checking and hides bugs at compile time.
+- **Refactor confidence**: precise types make API and UI changes safer.
+- **Consistency**: one convention for when `any` is acceptable and how it is documented.
+
+Prefer `unknown` (and narrow) or a precise type. Use `as unknown as T` over `as any as T` when a cast is unavoidable.
+
+## Allowed uses
+
+Explicit `any` is acceptable only at **framework or library boundaries** where types are not expressible in TypeScript today, for example:
+
+- Mongoose `Schema<any, …>` accepting arbitrary consumer schemas (`api/src/plugins.ts`)
+- RTK Query `Api<any, any, any, any>` in generic middleware (`rtk/src/offlineMiddleware.ts`)
+- Dynamic RTK hook lookup where endpoint names are not statically known (`admin-frontend`)
+- Test mocks with type-erased doubles (`*.test.ts`, `*.isolated.tsx`)
+
+Every allowed use must be **lint-clean** and **documented** (see below).
+
+## Remediation status
+
+The audit script (`bun run check:explicit-any`) classifies each explicit `any`:
+
+| Status | Meaning |
+|--------|---------|
+| `violation` | No `biome-ignore` — fails Biome lint |
+| `suppressed-only` | Has `biome-ignore` but missing `// noExplicitAny:` rationale |
+| `fully-documented` | Has both `biome-ignore` and `// noExplicitAny:` |
+| `file-blanket` | File-level `biome-ignore-all` without file-level `noExplicitAny:` |
+| `out-of-scope` | In Biome-excluded source (e.g. `api/src/populate.ts`) |
+
+## How to document an `any`
+
+When `any` cannot be removed, add **both** comments on the line above (or a file header for tests):
+
+```typescript
+// noExplicitAny: RTK Query generates hook names dynamically; not statically expressible
+// biome-ignore lint/suspicious/noExplicitAny: dynamic hook lookup on RTK Query enhanced API
+const hook = (api as any)[`useGet${name}Query`];
+```
+
+For test files with many mocks, a file-level header is fine:
+
+```typescript
+// noExplicitAny: test mocks use type-erased RTK Query API doubles
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
+```
+
+## Commands
+
+```bash
+bun run check:explicit-any                         # summary report
+bun run check:explicit-any:json                    # JSON inventory
+bun run check:explicit-any:baseline                # fail if counts regress vs baseline
+bun run check:explicit-any -- --undocumented       # only suppressed-but-undocumented
+bun run check:explicit-any -- --list --undocumented  # file:line list for remediation
+bun run check:explicit-any -- --production-only --undocumented --list
+bun run check:explicit-any -- --package=api        # filter to one package
+bun run check:explicit-any -- --include-excluded   # include Biome-excluded files
+bun run check:explicit-any -- --write-baseline     # refresh scripts/check-explicit-any/baseline.json
+bun run check:explicit-any:remediate               # auto-add missing noExplicitAny: comments
+```
+
+## Enforcement
+
+| Layer | What it does |
+|-------|----------------|
+| **Biome `noExplicitAny: error`** | Blocks new unsuppressed `any` in every linted package |
+| **`bun run check:explicit-any:baseline`** | CI ratchet — total, undocumented, and violation counts must not increase |
+| **`bun run lint`** | Per-package lint including `noExplicitAny` |
+
+Baseline file: `scripts/check-explicit-any/baseline.json`. After intentional reductions (removing or properly documenting `any`), refresh with `--write-baseline` and commit the updated baseline.
+
+## Remediation workflow
+
+1. Run `bun run check:explicit-any -- --list --undocumented --production-only` for a work queue.
+2. For each hit, either **replace** `any` with a proper type or **document** with `noExplicitAny:` + `biome-ignore`.
+3. Prefer line-level suppressions over file-level `biome-ignore-all` in production code.
+4. Run `bun run check:explicit-any:baseline` before opening a PR.
+5. If counts decreased, run `--write-baseline` and commit the new baseline.
+
+## Exclusions
+
+The audit skips generated and template files (`openApiSdk.ts`, `*.template.ts`). Biome-excluded paths (see `!!` patterns in `biome.jsonc`) are omitted unless `--include-excluded` is passed.

package/src/docs/versioned/0.30.0/implementationPlans/PLAN_INDEX.md

@@ -0,0 +1,75 @@
+# Implementation plan index
+
+Tracks active and completed implementation plans (IP) for Terreno. File paths are relative to `docs/implementationPlans/`.
+
+## Programs
+
+Umbrella plans that coordinate several IPs.
+
+| Program | Status | Created | IPs |
+|---------|--------|---------|-----|
+| [Open source launch](oss-launch-program.md) | Draft — decisions recorded; Vercel spike open | 2026-07-27 | 15 |
+
+## Active
+
+| Plan | Status | Created | Tasks |
+|------|--------|---------|-------|
+| [Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md) | Approved | 2026-06-15 | [tasks](../tasks/admin-ui-v2-django-parity.md) |
+| [RBAC Permissions](rbac-permissions.md) | Draft (API design) | 2026-07-08 | TBD |
+| [SyncDB Local-First Data Layer](syncdb-local-first.md) | In progress ([PR #869](https://github.com/flourishhealth/terreno/pull/869)) | 2026-07-13 | [tasks](../tasks/syncdb-local-first.md) |
+| [MCP Boost parity](mcp-boost-parity.md) | In progress ([PR #802](https://github.com/flourishhealth/terreno/pull/802)) | 2026-06-21 | TBD |
+
+## Open source launch IPs
+
+All part of the [launch program](oss-launch-program.md). The **RTK flag** column marks dependence on the `@terreno/rtk` → `@terreno/syncdb` migration in PR #869: `None` is safe to implement now, `Partial` has some blocked tasks, `Blocked` cannot start until #869 merges.
+
+### Wave 0 — unblocked
+
+| Plan | Status | RTK flag | Tasks |
+|------|--------|----------|-------|
+| [OSS governance baseline](oss-governance-baseline.md) | Draft | None | [tasks](../tasks/oss-governance-baseline.md) |
+| [Public roadmap on GitHub](public-roadmap-github.md) | Draft | None | [tasks](../tasks/public-roadmap-github.md) |
+| [Deploy to GCP (generalized)](deploy-to-gcp.md) | Draft | None | [tasks](../tasks/deploy-to-gcp.md) |
+| [Agentic SDLC plugin (`/terreno-*`)](agentic-sdlc-plugin.md) | Draft | Partial | [tasks](../tasks/agentic-sdlc-plugin.md) |
+
+### Wave 1 — gated on PR #869
+
+| Plan | Status | RTK flag | Tasks |
+|------|--------|----------|-------|
+| [RTK deprecation and syncdb migration docs](rtk-to-syncdb-migration-docs.md) | Draft | **Blocked** (gating IP) | [tasks](../tasks/rtk-to-syncdb-migration-docs.md) |
+| [Positioning — Django/Rails for TypeScript](positioning-django-rails-universal.md) | Draft | Partial | [tasks](../tasks/positioning-django-rails-universal.md) |
+| [Reference documentation coverage](docs-reference-coverage.md) | Draft | Blocked | [tasks](../tasks/docs-reference-coverage.md) |
+| [AI-first tutorials](docs-tutorials-ai-first.md) | Draft | Blocked | [tasks](../tasks/docs-tutorials-ai-first.md) |
+| [Deployment foundation](deployment-foundation.md) | Draft | Partial | [tasks](../tasks/deployment-foundation.md) |
+| [Deploy to Vercel](deploy-to-vercel.md) | Draft | Partial | [tasks](../tasks/deploy-to-vercel.md) |
+| [Upgrade guides and skill](upgrade-guides-and-skill.md) | Draft | Blocked | [tasks](../tasks/upgrade-guides-and-skill.md) |
+| [The AI development loop (Boost)](ai-dev-loop-boost.md) | Draft | Partial | [tasks](../tasks/ai-dev-loop-boost.md) |
+| [Dogfooding run and launch blog post](build-terreno-app-validation.md) | Draft | Blocked | [tasks](../tasks/build-terreno-app-validation.md) |
+| [Examples, demo, and test coverage](examples-demo-coverage.md) | Draft | Partial | [tasks](../tasks/examples-demo-coverage.md) |
+
+### Wave 2 — independent
+
+| Plan | Status | RTK flag | Tasks |
+|------|--------|----------|-------|
+| [Web SSR and admin SPA](web-ssr-and-admin-spa.md) | Draft | Partial | [tasks](../tasks/web-ssr-and-admin-spa.md) |
+
+## Completed
+
+| Plan | Status | Created | Tasks |
+|------|--------|---------|-------|
+| [APIError redesign — standards-first extension of Error](apierror-standard-error-redesign.md) | Complete | 2026-07-28 | n/a |
+
+## Deferred / Closed
+
+*(Plans parked or superseded.)*
+
+## Backlog
+
+*(Links to ideas not yet promoted to a full IP.)*
+
+| Idea | Notes |
+|------|-------|
+| [Langfuse integration](terreno-langfuse-integration.md) | AI observability plugin |
+| [modelRouter MCP tools](model-router-mcp.md) | MCP surface for consumer app APIs |
+| [Offline mode](offline-mode.md) | Superseded in large part by [syncdb](syncdb-local-first.md) — confirm and close |
+| [modelRouter actions](model-router-actions.md) | — |

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

@@ -0,0 +1,177 @@
+# 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.