@terreno/mcp 57.2.0 → 57.3.0

package/dist/docs/versioned/57.2.0/tasks/admin-only.md

@@ -0,0 +1,223 @@
+# Task List: Admin-Only — Serve Admin SPA From a Terreno Backend
+
+**Status:** Closed (2026-08-20) — IP complete. Shipped as `@terreno/admin-spa`. Open tasks below were not executed; see shipped code in `admin-spa/`.
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+See: `docs/implementationPlans/admin-only.md` for full plan.
+
+## Phase 0: admin-frontend prop split (prerequisite — verified blocker)
+
+- [ ] **Task 0.1**: Split `baseUrl` → `apiBase` + `routeBase` across admin-frontend
+  - Description: Add optional `apiBase` and `routeBase` props alongside the existing `baseUrl` to every exported admin-frontend component. Internally resolve `const apiBase = props.apiBase ?? props.baseUrl; const routeBase = props.routeBase ?? props.baseUrl;`. Replace each occurrence: `useAdminConfig(api, baseUrl)` → `useAdminConfig(api, apiBase)`; `useAdminApi(api, baseUrl, modelName)` → `useAdminApi(api, apiBase, modelName)`; every `router.push(\`${baseUrl}/...\`)` and `href: \`${baseUrl}/...\`` → use `routeBase` instead.
+  - Files: `admin-frontend/src/AdminModelList.tsx`, `AdminModelTable.tsx`, `AdminModelForm.tsx`, `AdminRefField.tsx`, `AdminScriptList.tsx`, `AdminVersionConfig.tsx`, `ConfigurationScreen.tsx`, `useAdminConfig.tsx`, `useAdminApi.ts`, `AdminScriptRunModal.tsx` (if it references baseUrl)
+  - Depends on: none
+  - Acceptance: `bun run admin-frontend:lint` + `bun run admin-frontend:compile` pass. Type-check passes.
+
+- [ ] **Task 0.2**: Tests for prop split
+  - Description: Add a focused test asserting that when `apiBase="/admin"` + `routeBase="/console"` are passed, `useAdminConfig` is called with `/admin` and `router.push` is invoked with `/console/${modelName}`. Also assert backward-compat: `baseUrl="/admin"` alone still works (both internally default to `/admin`).
+  - Files: `admin-frontend/src/AdminModelList.test.tsx`, `AdminModelTable.test.tsx`
+  - Depends on: 0.1
+  - Acceptance: `bun run admin-frontend:test` passes with new assertions.
+
+- [ ] **Task 0.3**: Verify embedded admin still works
+  - Description: Run `example-frontend` against `example-backend`. Log in as admin, navigate to `/admin`, click through a model. Verify no regression. No code change expected — this is a verification step.
+  - Files: (manual)
+  - Depends on: 0.1
+  - Acceptance: All embedded admin flows in example-frontend render and function identically to pre-Phase 0.
+
+## Phase 1: Package scaffolding
+
+- [ ] **Task 1.1**: Create `admin-spa/` workspace package files
+  - Description: Create `package.json` (`@terreno/admin-spa`, version 0.13.0, deps mirror needed runtime: `@terreno/admin-frontend`, `@terreno/rtk`, `@terreno/ui`, `expo`, `expo-router`, `react`, `react-native-web`, `redux-persist`, `better-auth`; peer dep `@terreno/api`; dev deps mirror `example-frontend`). Add `tsconfig.json` (extends Expo preset, covers `app/`, `store/`, `components/`), `tsconfig.server.json` (covers `src/`, outputs `src/dist/`), `biome.jsonc` and `bunfig.toml` copied from `admin-frontend`, `babel.config.js` and `metro.config.js` copied from `example-frontend` (with workspace path adjustments), `app.json` with `web.output: "static"` and `extra.BASE_URL: "__SAME_ORIGIN__"`.
+  - Files: `admin-spa/package.json`, `admin-spa/tsconfig.json`, `admin-spa/tsconfig.server.json`, `admin-spa/biome.jsonc`, `admin-spa/bunfig.toml`, `admin-spa/babel.config.js`, `admin-spa/metro.config.js`, `admin-spa/app.json`, `admin-spa/.gitignore` (must include `dist/`, `store/openApiSdk.ts`, `src/dist/`)
+  - Depends on: none
+  - Acceptance: `bun install` from root succeeds; `bun run --filter '@terreno/admin-spa' compile` is a no-op (succeeds with no source yet).
+
+- [ ] **Task 1.2**: Register workspace in root and add scripts
+  - Description: Add `"admin-spa"` to `workspaces` array in root `package.json`. Add `admin-spa:compile`, `admin-spa:lint`, `admin-spa:test`, `admin-spa:build`, `admin-spa:sdk` scripts mirroring the admin-backend/admin-frontend convention.
+  - Files: `package.json` (root)
+  - Depends on: 1.1
+  - Acceptance: `bun install` resolves admin-spa; `bun run admin-spa:lint` runs (even with no source).
+
+- [ ] **Task 1.3**: Stub server-side plugin entry
+  - Description: Create `src/index.ts` exporting `AdminSpaServeApp` (stub class implementing `TerrenoPlugin` with empty `register()`). Create `src/appConfig.ts` with `AdminSpaAppConfig` interface and `DEFAULT_APP_CONFIG`. Run `tsc -p tsconfig.server.json` and verify `src/dist/` is produced.
+  - Files: `admin-spa/src/index.ts`, `admin-spa/src/appConfig.ts`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' compile` outputs `src/dist/index.js` and `src/dist/appConfig.js`.
+
+- [ ] **Task 1.4**: Stub Expo Router app entry
+  - Description: Create minimal `app/_layout.tsx` (just `<Stack/>`) and `app/index.tsx` rendering a `<Box>Hello admin</Box>` from `@terreno/ui`. Goal: verify the static export pipeline works end-to-end before adding real logic.
+  - Files: `admin-spa/app/_layout.tsx`, `admin-spa/app/index.tsx`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' build:web` produces `dist/index.html`, `dist/_expo/...`, no errors. Open `dist/index.html` in a browser → "Hello admin" renders.
+
+## Phase 2: Same-origin BASE_URL support
+
+- [ ] **Task 2.1**: Add `__SAME_ORIGIN__` sentinel to `@terreno/rtk`
+  - Description: Add `export const SAME_ORIGIN_SENTINEL = "__SAME_ORIGIN__";` to `rtk/src/constants.ts`. Modify `resolveBaseUrls` signature to accept optional `windowOrigin?: string`. When `baseFromExtra === SAME_ORIGIN_SENTINEL` and `windowOrigin` (or `globalThis.location?.origin`) is set, return `{baseUrl: origin, baseTasksUrl: `${origin}/tasks`, baseWebsocketsUrl: `${origin.replace(/^http/, "ws")}/`}`. Module-level call passes `globalThis.location?.origin` (with safe `typeof` check).
+  - Files: `rtk/src/constants.ts`
+  - Depends on: none
+  - Acceptance: Existing tests pass; new sentinel-aware path returns expected URLs.
+
+- [ ] **Task 2.2**: Tests for same-origin sentinel
+  - Description: Add tests to `rtk/src/constants.test.ts` covering: (a) sentinel + `windowOrigin: "https://api.example.com"` → `https://...` + `wss://...`; (b) sentinel + `windowOrigin: "http://localhost:4000"` → `http://...` + `ws://...`; (c) sentinel + no window origin → falls back to existing resolution; (d) non-sentinel BASE_URL is unchanged; (e) sentinel + isDev=true behaves the same as production for the sentinel path.
+  - Files: `rtk/src/constants.test.ts`
+  - Depends on: 2.1
+  - Acceptance: `bun run rtk:test` passes including new cases.
+
+## Phase 3: Express plugin
+
+- [ ] **Task 3.1**: Implement `AdminSpaServeApp.register()`
+  - Description: Implement `src/serve.ts`: resolve `basePath` (default `/console`), `distDir` (default `path.resolve(__dirname, "../../dist")` so it works from `src/dist/serve.js`), merged `appConfig`. Register three Express handlers: `express.static` for `_expo/` and `assets/` with `{immutable: true, maxAge: "365d"}`, `GET ${basePath}/app-config.json` returning JSON with `Cache-Control: no-store`, `GET ${basePath}{/*splat}` returning `index.html` with `Cache-Control: no-store`. Log at info level on mount.
+  - Files: `admin-spa/src/serve.ts`, `admin-spa/src/index.ts` (export)
+  - Depends on: 1.3
+  - Acceptance: `bun run admin-spa:compile` produces `src/dist/serve.js`; manual import from Node ESM works.
+
+- [ ] **Task 3.2**: Plugin unit tests
+  - Description: Add `src/serve.test.ts` using `supertest`. Create a tmpdir with stub `index.html` ("STUB-SPA"), `_expo/static/js/web/foo.abc123.js` ("CONTENT"), and `assets/foo.png` (any bytes). Construct an Express app and register the plugin with `distDir` pointing at the tmpdir. Cases: `GET /console/` → 200 + STUB-SPA + `Cache-Control: no-store`; `GET /console/users` → 200 + STUB-SPA (fallback); `GET /console/users/abc123` → 200 + STUB-SPA; `GET /console/_expo/static/js/web/foo.abc123.js` → 200 + CONTENT + cache headers; `GET /console/app-config.json` → 200 + JSON with `brandName: "Terreno Admin"` (default) + `Cache-Control: no-store`; `GET /console/app-config.json` with custom appConfig → returns merged config; `GET /unrelated` → 404 (plugin doesn't catch outside `basePath`); custom `basePath: "/admin-ui"` works.
+  - Files: `admin-spa/src/serve.test.ts`
+  - Depends on: 3.1
+  - Acceptance: `bun run admin-spa:test` passes all cases.
+
+## Phase 4: SPA — gates and auth
+
+- [ ] **Task 4.1**: AppConfigGate component
+  - Description: Create `components/AppConfigGate.tsx`. Uses React context to expose `AdminSpaAppConfig`. On mount, fetches `./app-config.json` (relative to current URL — so `/console/app-config.json` when mounted at `/console`). Defines defaults to merge with response. Renders a centered `<Spinner>` with `testID="admin-spa-app-config-loading"` while loading. Errors → renders a `<Text>` with retry button. Exposes `useAppConfig()` hook.
+  - Files: `admin-spa/components/AppConfigGate.tsx`
+  - Depends on: 1.4, 3.1
+  - Acceptance: Build succeeds; importing `useAppConfig` outside the gate throws a clear error.
+
+- [ ] **Task 4.2**: StoreProvider component (replaces "factory function" pattern)
+  - Description: Create `components/StoreProvider.tsx`. Reads `useAppConfig()`. Inside the component body, memo-builds `authClient = createAuthClient({baseURL: window.location.origin, basePath: appConfig.authBasePath ?? "/api/auth"})` using `better-auth/react` **directly** (NOT `@terreno/rtk`'s factory — that one is RN-targeted with the expo plugin). Builds `{betterAuthReducer, middleware, selectors} = generateBetterAuthSlice(authClient)`, then `store = configureStore({reducer: {betterAuth: betterAuthReducer, [openapi.reducerPath]: openapi.reducer}, middleware: (gdm) => gdm().concat(openapi.middleware, ...middleware)})`, then `persistor = persistStore(store)`. Wraps children: `<Provider store={store}><PersistGate loading={<Spinner testID="admin-spa-persist-loading"/>} persistor={persistor}>{children}</PersistGate></Provider>`. The `loading` prop is **required** — without it, AdminGate flashes the login screen during rehydration.
+  - Files: `admin-spa/components/StoreProvider.tsx`, `admin-spa/store/sdk.ts` (re-exports `emptySplitApi as openapi` from `@terreno/rtk` with tag types)
+  - Depends on: 4.1, 6.1
+  - Acceptance: Build succeeds; type-check passes; no `expo-secure-store` import surfaces in the bundle (since this is web-only).
+
+- [ ] **Task 4.3**: AdminGate component
+  - Description: Create `components/AdminGate.tsx`. Wraps children. On mount, calls `authClient.getSession()`. Uses `useSelectIsAuthenticated`. Renders spinner with `testID="admin-spa-admin-gate-loading"` while loading. If unauth and not on `/login`, `router.replace("/login")`. If auth + `user.admin !== true` and not on `/forbidden`, `router.replace("/forbidden")`. If auth + admin and on `/login` or `/forbidden`, `router.replace("/")`. Otherwise pass through.
+  - Files: `admin-spa/components/AdminGate.tsx`
+  - Depends on: 4.2
+  - Acceptance: Build succeeds; gate logic verifiable via unit test of selector behavior (`bun test`).
+
+- [ ] **Task 4.4**: Login screen
+  - Description: Create `app/login.tsx`. Reads `useAppConfig().providers`. Renders form with `TextField` (email) + `TextField` (password, type="password") + `Button` ("Sign in") calling `authClient.signIn.email({email, password})`. For each provider in `providers` that isn't `"email"`, renders a `SocialLoginButton`. Handles loading, error display. On success, `router.replace("/")`. testIDs as listed in IP.
+  - Files: `admin-spa/app/login.tsx`
+  - Depends on: 4.3
+  - Acceptance: Rendering the SPA logged-out shows the login form; clicking submit attempts the better-auth signIn (verifiable by mock in unit test).
+
+- [ ] **Task 4.5**: Forbidden screen + signout
+  - Description: Create `app/forbidden.tsx`. Renders `<Page>` with heading "Admins only" and explanation text. Includes a "Sign out" button calling `authClient.signOut()` then `router.replace("/login")`.
+  - Files: `admin-spa/app/forbidden.tsx`
+  - Depends on: 4.3
+  - Acceptance: Build succeeds; testID on screen root.
+
+- [ ] **Task 4.6**: Root layout assembly (correct provider order)
+  - Description: Update `app/_layout.tsx`. Order: `<AppConfigGate><StoreProvider><TerrenoProvider><AdminGate><Stack screenOptions={{headerShown: false}}>...</Stack></AdminGate></TerrenoProvider></StoreProvider></AppConfigGate>`. AppConfigGate is outermost because it has no Redux dependency and its result is needed to build the store. StoreProvider includes Provider + PersistGate. TerrenoProvider is inside Provider so theme hooks can read store state. AdminGate is innermost so it sees fully-hydrated state.
+  - Files: `admin-spa/app/_layout.tsx`
+  - Depends on: 4.1, 4.2, 4.3, 4.4, 4.5
+  - Acceptance: `bun run admin-spa:build` succeeds with no Metro errors. Sequential render: loading splash → (rehydrating) spinner → (unauth) login OR (admin) model list. No login flash for authenticated admins.
+
+## Phase 5: Wire admin screens
+
+All screens pass `apiBase={appConfig.adminApiBasePath ?? "/admin"}` AND `routeBase=""` so navigation stays inside the SPA's `/console` root. Depends on Phase 0.
+
+- [ ] **Task 5.1**: Model list screen
+  - Description: `app/index.tsx` renders `<AdminModelList api={terrenoApi} apiBase={apiBase} routeBase={routeBase} />`. Get values from `useAppConfig()`: `const apiBase = appConfig.adminApiBasePath ?? "/admin"; const routeBase = "";`.
+  - Files: `admin-spa/app/index.tsx`
+  - Depends on: 4.6, 0.1
+  - Acceptance: After login, model list renders models from `${apiBase}/config`. Clicking a model card calls `router.push("/${modelName}")` (relative to SPA root), NOT `/admin/${modelName}`.
+
+- [ ] **Task 5.2**: Model table + form routes
+  - Description: Create `app/[model]/_layout.tsx` (`<Stack/>`), `app/[model]/index.tsx` (renders `<AdminModelTable>`), `app/[model]/[id].tsx` (renders `<AdminModelForm id={id}>`), `app/[model]/create.tsx` (renders `<AdminModelForm>`). Use `useLocalSearchParams()` for params. Handle the `__scripts` and `version-config` sentinels like example-frontend does.
+  - Files: `admin-spa/app/[model]/_layout.tsx`, `admin-spa/app/[model]/index.tsx`, `admin-spa/app/[model]/[id].tsx`, `admin-spa/app/[model]/create.tsx`
+  - Depends on: 5.1
+  - Acceptance: Navigating to `/console/Users` shows the table; clicking a row opens the form.
+
+- [ ] **Task 5.3**: Configuration + scripts + version-config screens
+  - Description: Create `app/configuration.tsx`, `app/scripts.tsx`, `app/version-config.tsx` wrapping the corresponding `@terreno/admin-frontend` screens (`ConfigurationScreen`, `AdminScriptList`, `AdminVersionConfig`).
+  - Files: `admin-spa/app/configuration.tsx`, `admin-spa/app/scripts.tsx`, `admin-spa/app/version-config.tsx`
+  - Depends on: 5.1
+  - Acceptance: Each screen renders without errors.
+
+- [ ] **Task 5.4**: Not-found + Expo Router conventions
+  - Description: Create `app/+not-found.tsx` rendering a friendly 404 with link back to `/`. Add `app/+html.tsx` if needed for static export head config (favicon, viewport).
+  - Files: `admin-spa/app/+not-found.tsx`, `admin-spa/app/+html.tsx`
+  - Depends on: 4.6
+  - Acceptance: Visiting `/console/nonexistent` shows the 404 screen.
+
+## Phase 6: SDK glue (no codegen by default)
+
+Admin endpoints are runtime-injected by `admin-frontend/src/useAdminApi.ts` — codegen is unnecessary for the admin flow itself.
+
+- [ ] **Task 6.1**: Hand-written `store/sdk.ts`
+  - Description: Create `store/sdk.ts` that re-exports `emptySplitApi as openapi` from `@terreno/rtk` and uses `.enhanceEndpoints({addTagTypes: ["admin-models", "admin-version-config", "admin-scripts", "profile"]})`. Export `const terrenoApi = openapi` for consumers.
+  - Files: `admin-spa/store/sdk.ts`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' compile` passes; importing `terrenoApi` from `store/sdk` works in app code.
+
+- [ ] **Task 6.2 (optional)**: Codegen config for consumers wanting extended SDKs
+  - Description: Create `openapi-config.ts` pointing at `http://localhost:4000/openapi.json`. Document in README as optional — not part of the standard build.
+  - Files: `admin-spa/openapi-config.ts`, `admin-spa/README.md` section
+  - Depends on: 6.1
+  - Acceptance: Running `bun run --filter '@terreno/admin-spa' sdk` against a live backend regenerates `store/openApiSdk.ts` with all endpoints.
+
+## Phase 7: Example backend integration
+
+- [ ] **Task 7.1**: Add admin-spa dep to example-backend
+  - Description: Add `"@terreno/admin-spa": "workspace:*"` to `example-backend/package.json` dependencies.
+  - Files: `example-backend/package.json`
+  - Depends on: 1.2
+  - Acceptance: `bun install` resolves.
+
+- [ ] **Task 7.2**: Register plugin in example-backend
+  - Description: In `example-backend/src/server.ts`, import `AdminSpaServeApp`. Register it (gated on `process.env.ADMIN_SPA_ENABLED === "true"`) with `basePath: "/console"`, `appConfig: {brandName: "Terreno Example", primaryColor: "#7C3AED", providers: ["email", "google"]}`.
+  - Files: `example-backend/src/server.ts`
+  - Depends on: 7.1, 3.1
+  - Acceptance: With `ADMIN_SPA_ENABLED=true AUTH_PROVIDER=better-auth bun run backend:dev`, server starts and logs "Admin SPA mounted at /console/".
+
+- [ ] **Task 7.3**: Manual smoke test
+  - Description: Start the backend with the env flags above. Open `http://localhost:4000/console/`. Confirm: (a) login screen renders with brand name "Terreno Example"; (b) sign in with an admin user → redirects to admin list; (c) clicking a model opens the table; (d) editing a row works; (e) `app-config.json` GET returns the configured shape; (f) non-admin user → forbidden screen. Document any gaps found.
+  - Files: (manual)
+  - Depends on: 7.2, 5.x complete
+  - Acceptance: All six checks pass.
+
+## Phase 8: Docs and rules
+
+- [ ] **Task 8.1**: README for admin-spa
+  - Description: Write `admin-spa/README.md`. Sections: overview, install, register with backend, customizing app-config, regenerating SDK, comparison with embedded admin-frontend usage.
+  - Files: `admin-spa/README.md`
+  - Depends on: 7.3
+  - Acceptance: Reading the README is sufficient for a new consumer to add admin to their backend.
+
+- [ ] **Task 8.2**: rulesync rule file
+  - Description: Author `.claude/rules/admin-spa/00-admin-spa.md` matching the shape of `.claude/rules/admin-frontend/00-admin-frontend.md`. Run `bun run rules` to regenerate `rulesync.jsonc` artifacts. Verify the rule appears in any AI consumer config files generated.
+  - Files: `.claude/rules/admin-spa/00-admin-spa.md`, plus regenerated rulesync artifacts
+  - Depends on: 8.1
+  - Acceptance: `bun run rules:check` passes (no diff after a clean regen).
+
+- [ ] **Task 8.3**: Update CLAUDE.local.md and admin-backend README
+  - Description: Add admin-spa to the packages list in `CLAUDE.local.md`. Add a "Standalone admin SPA" pointer to `admin-backend/README.md`.
+  - Files: `CLAUDE.local.md`, `admin-backend/README.md`
+  - Depends on: 8.1
+  - Acceptance: Both files mention admin-spa and reference the IP.
+
+- [ ] **Task 8.5**: Publish CI job
+  - Description: Add an `admin-spa` publish job to `.github/workflows/publish-on-tag.yml` mirroring the existing 8 publish jobs. Job must: `bun install` → `bun run admin-spa:build` → `bun run admin-spa:compile` → `bun publish --filter '@terreno/admin-spa'`. Without this, tagged releases publish an empty `dist/`.
+  - Files: `.github/workflows/publish-on-tag.yml`
+  - Depends on: 8.1
+  - Acceptance: Dry-run the workflow on a feature branch; verify the tarball contains `src/dist/`, `dist/index.html`, and at least one file in `dist/_expo/`.
+
+- [ ] **Task 8.6**: CI smoke test
+  - Description: New job (or extension of existing E2E workflow). Boots example-backend with `ADMIN_SPA_ENABLED=true AUTH_PROVIDER=better-auth` after running `bun run --filter '@terreno/admin-spa' build:web`. curl `/console/`, `/console/app-config.json`, and one `/console/_expo/static/js/web/*.js` asset. Assert 200s + correct cache headers. Catches path-rewrite regressions in CI.
+  - Files: `.github/workflows/admin-spa-smoke.yml` (new) or update an existing test workflow
+  - Depends on: 7.2, 3.1
+  - Acceptance: Workflow passes on a clean run; mutating the rewrite list in `serve.ts` to omit `_expo` causes a CI failure.
+
+## Optional Phases
+
+- [ ] **Task 9.1 (optional)**: Playwright E2E
+  - Description: Add `e2e/admin-spa.spec.ts` to example-frontend with three tests: anonymous user sees login screen, admin can log in and view model list, non-admin gets forbidden screen.
+  - Files: `example-frontend/e2e/admin-spa.spec.ts`, plus testIDs already added in Phase 4
+  - Depends on: 7.3
+  - Acceptance: `bun run --filter '@terreno/example-frontend' e2e -- admin-spa.spec.ts` passes locally with backend running.

package/dist/docs/versioned/57.2.0/tasks/agentic-sdlc-plugin.md

@@ -0,0 +1,57 @@
+# Task List: Loop-Engineering Lifecycle Plugin
+
+See: [`docs/implementationPlans/agentic-sdlc-plugin.md`](../implementationPlans/agentic-sdlc-plugin.md)
+
+## Phase 1: Audit and contracts
+
+- [x] **Task 1.1**: Audit five lifecycle skills, metadata, references, repo skills, state conventions, sync tooling, and long-lived-context assumptions
+  - Blocked by: none
+  - Acceptance: Findings identify duplicated repository knowledge, missing handoffs, generated sources, and orchestration owned by stages.
+- [x] **Task 1.2**: Define shared stage result and execution-state schemas
+  - Blocked by: Task 1.1
+  - Acceptance: Stable schemas use only `PASS`/`FAIL`/`BLOCKED`/`PENDING`, preserve evidence/attempts, and contain no reasoning transcript.
+- [x] **Task 1.3**: Document loop ownership, retries, human gates, state transport, and supporting-skill discovery
+  - Blocked by: Task 1.2
+  - Acceptance: A fresh invocation packet and fallback execution-state location are explicit.
+
+## Phase 2: Bounded lifecycle stages
+
+- [x] **Task 2.1**: Refactor Grow as an approved-artifact transition
+  - Blocked by: Task 1.3
+  - Acceptance: Grow classifies uncertainty, researches facts, grills decisions, maps acceptance to verification, and emits Pick-ready state.
+- [x] **Task 2.2**: Refactor Pick as one-slice TDD implementation
+  - Blocked by: Task 1.3
+  - Acceptance: Pick consumes retry evidence, preserves verified behavior, runs independent implementation/test-quality review, and delegates repository detail.
+- [x] **Task 2.3**: Refactor Roast as independent authoritative verification
+  - Blocked by: Task 2.2
+  - Acceptance: Roast executes a requirement/evidence matrix, does not trust Pick claims, and returns exact failures to Pick.
+- [x] **Task 2.4**: Refactor Brew to terminate after PR setup
+  - Blocked by: Task 2.3
+  - Acceptance: Brew records PR/current head and recommends Taste without executing or waiting for it.
+- [x] **Task 2.5**: Refactor Taste as one reactive iteration
+  - Blocked by: Task 2.4
+  - Acceptance: Taste observes current head once, handles current actionable work, emits state, exits, and contains no internal waiting loop.
+
+## Phase 3: Plugin boundary and composition
+
+- [x] **Task 3.1**: Remove Terreno package commands/patterns from lifecycle control surfaces
+  - Blocked by: Task 2.5
+  - Acceptance: Exact repo knowledge remains under `.rulesync/skills/`; lifecycle stages discover applicable skills.
+- [x] **Task 3.2**: Convert plugin utility/orchestration skills to shared references
+  - Blocked by: Task 2.5
+  - Acceptance: Plugin exposes exactly five lifecycle skill directories; independent review and feature-loop behavior remain documented once.
+- [x] **Task 3.3**: Document backend, UI, and multi-invocation CI/review compositions
+  - Blocked by: Task 3.2
+  - Acceptance: Each scenario shows lifecycle + project skills + durable evidence.
+
+## Phase 4: Validation and documentation
+
+- [x] **Task 4.1**: Add lifecycle architecture validator and unit tests
+  - Blocked by: Task 3.2
+  - Acceptance: Validator enforces names/directories, required contracts, status/transition values, portability, Brew/Taste boundaries, and migration docs.
+- [x] **Task 4.2**: Update plugin/docs/metadata/changelog and regenerate integrations
+  - Blocked by: Task 4.1
+  - Acceptance: Plugin is `2.0.0`; docs describe the bounded loop; generated rules are current; retired names appear only in intentional migration/history.
+- [x] **Task 4.3**: Run static tests, rulesync validation, lint/type checks, and independent review
+  - Blocked by: Task 4.2
+  - Acceptance: All checks pass and no material standards/spec findings remain.

package/dist/docs/versioned/57.2.0/tasks/billing-stripe.md

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

package/dist/docs/versioned/57.2.0/tasks/comms-abstraction.md

@@ -0,0 +1,96 @@
+# Tasks: Pluggable communications layer (@terreno/comms)
+
+IP: [comms-abstraction](../implementationPlans/comms-abstraction.md)
+
+## Phase 1 — Package + contracts
+
+- [x] **Task 1.1**: Scaffold `@terreno/comms` workspace package
+  - Description: `comms/` package with tsconfig/biome/bun test setup mirroring `feature-flags/`; root workspace entry + `comms:*` scripts
+  - Files: `comms/package.json`, `comms/tsconfig.json`, `comms/biome.jsonc`, root `package.json`
+  - Depends on: none
+  - Acceptance: `bun run comms:compile` and `bun run comms:lint` pass
+- [x] **Task 1.2**: Finish provider types for remaining contracts
+  - Description: Add `cancelled` to `CommsMessageStatus`; expand `CommsHookContext` (`message`, `userId`, `isRetry`, `attempt`, `messageId`); add `OptOutEvent`; add `errorCode`/`errorClass` on `DeliveryEvent`; keep shipped `onRetry(context, result)` and `isPermanentFailure` alias
+  - Status: base provider/message/`errorCode`/`errorClass` shipped; listed fields remain
+  - Files: `comms/src/types.ts`, `comms/src/index.ts`
+  - Depends on: 1.1
+  - Acceptance: types compile and are exported; existing SendGrid tests still typecheck against `onRetry(context, result)`
+- [x] **Task 1.3**: Console adapters
+  - Description: dev adapters for all four channels logging via `logger.info`
+  - Files: `comms/src/adapters/console.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: each adapter returns `accepted: true` and logs
+- [x] **Task 1.4**: `CommsMessage` attempt history + dashboard fields
+  - Description: add `status: cancelled`, `attempts[]`, `attemptCount`, `lastAttemptAt`, `retriedFromId`/`retriedById`, `templateId`, `payload`, `payloadExpiresAt`; `logSend` creates the first row; `appendAttempt` never throws; `clearExpiredPayloads` unsets expired `payload` only (limit 50)
+  - Files: `comms/src/models/commsMessage.ts`, `comms/src/modelTypes.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: send logging survives a forced model error (logged, not thrown); a second attempt appends without a second row; Mongo TTL index is not used
+  - Status: model, `errorCode`/`errorClass`, and non-throwing `logSend` shipped; listed fields remain
+- [x] **Task 1.5**: Channel-wide transient retry + no rethrow
+  - Description: wrap provider throws as `{accepted: false, errorClass: "transient", errorCode: "provider-throw"}`; retry once on transient for `sendMail`, `sendSms`, `startVerification`; for `sendPushToUser`, retry only tokens whose first result is transient; do not retry `checkVerification`; prune tokens when `errorClass === "permanent"` or `isPermanentFailure === true`
+  - Status: mail retry shipped; SMS/push/verification still rethrow; prune is `isPermanentFailure` only
+  - Files: `comms/src/commsService.ts` + tests
+  - Depends on: 1.2, 1.3, 1.4
+  - Acceptance: unit tests cover happy path + unconfigured channel in both env modes; permanent/config failures do not retry; SMS throw returns a `SendResult` instead of rejecting
+- [x] **Task 1.6**: Lifecycle hooks + event intake
+  - Description: `beforeSend` (mutate/cancel, once before first attempt; throwing beforeSend = no cancel); `onSend`/`onError`/`onRetry` (keep `(context, result)`, set `context.attempt`); `recordDeliveryEvent` / `recordOptOut` invoke `onDeliveryEvent` / `onOptOut` and update the log row by `providerMessageId` when present; wrap every hook
+  - Files: `comms/src/commsService.ts`, `comms/src/types.ts` + tests
+  - Depends on: 1.5
+  - Acceptance: one test per hook (fires with correct context) plus one throwing-hook test per hook; cancelled send has `status: "cancelled"` and zero provider calls
+- [x] **Task 1.7**: Payload retention + redaction
+  - Description: `retainPayloadDays` (default 30) stores the channel payload after `redactPayload`; `retainPayloadDays: 0` stores nothing; push payload omits tokens; verification start stores `{channel}` only; `clearExpiredPayloads` runs best-effort from `logSend`/`appendAttempt`
+  - Files: `comms/src/commsService.ts`, `comms/src/models/commsMessage.ts` + tests
+  - Depends on: 1.4, 1.5, 1.6
+  - Acceptance: payload stored redacted; expired payload cleared without deleting the row; `retainPayloadDays: 0` stores nothing
+
+## Phase 2 — CommsApp + routes
+
+- [x] **Task 2.1**: `PushToken` model
+  - Description: model per IP with unique token upsert semantics
+  - Files: `comms/src/models/pushToken.ts` + tests
+  - Depends on: 1.1
+  - Acceptance: duplicate token registration updates the existing row
+- [x] **Task 2.2**: `CommsApp` TerrenoPlugin
+  - Description: options wiring, `getCommsService()` accessor, route mounting on `register()`
+  - Files: `comms/src/commsApp.ts` + tests
+  - Depends on: 1.5, 2.1
+  - Acceptance: plugin registers on `TerrenoApp` and service accessor returns configured providers
+- [x] **Task 2.3**: Push token routes
+  - Description: custom idempotent registration/list/deactivation endpoints plus modelRouter owner read; persisted `userId` scoping
+  - Files: `comms/src/routes/pushTokens.ts` + supertest
+  - Depends on: 2.2
+  - Acceptance: acceptance criteria bullets 2 pass under supertest
+- [x] **Task 2.4**: Admin delivery explorer
+  - Description: `GET /comms/messages` admin-only, paginated, filtered; OpenAPI builder
+  - Files: `comms/src/routes/commsExplorer.ts` + supertest
+  - Depends on: 2.2
+  - Acceptance: non-admin gets 403; filters work
+- [x] **Task 2.5**: `sendPushToUser` token resolution + pruning
+  - Description: resolve active tokens per user; deactivate tokens whose `SendResult` reports permanent failure
+  - Files: `comms/src/commsService.ts` + tests
+  - Depends on: 2.1, 1.5
+  - Acceptance: dead token is `active: false` after a failed send
+  - Note: remaining prune-by-`errorClass` work is in Task 1.5
+
+## Phase 3 — Integration + docs
+
+- [x] **Task 3.1**: example-backend registration
+  - Description: register `CommsApp` with console adapters; env-gated
+  - Files: `example-backend/src/server.ts`
+  - Depends on: 2.2
+  - Acceptance: backend boots; `/comms/pushTokens` in `/openapi.json`
+- [x] **Task 3.2**: Reference docs + rules
+  - Description: `docs/reference/comms.md`, rulesync source rule, `bun run rules`
+  - Files: `docs/reference/comms.md`, `.rulesync/**`
+  - Depends on: 2.x
+  - Acceptance: `bun run rules:check` passes
+- [x] **Task 3.3**: CI + publish wiring
+  - Description: `comms-ci` workflow; add `@terreno/comms` to `publish-on-tag.yml`
+  - Files: `.github/workflows/comms-ci.yml`, `.github/workflows/publish-on-tag.yml`
+  - Depends on: 1.x
+  - Acceptance: CI green on the PR
+- [x] **Task 3.4**: Docs refresh for gap-fill APIs
+  - Description: document `beforeSend`, `recordDeliveryEvent`/`recordOptOut`, attempt history, payload retention, channel-wide retry, and the `onRetry`/`isPermanentFailure` aliases in reference docs + comms rule
+  - Files: `docs/reference/comms.md`, `.rulesync/rules/comms/00-comms.md`
+  - Depends on: 1.6, 1.7
+  - Acceptance: `bun run rules:check` passes; docs match the Approved IP

package/dist/docs/versioned/57.2.0/tasks/comms-adapter-expo-push.md

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

package/dist/docs/versioned/57.2.0/tasks/comms-adapter-sendgrid.md

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

package/dist/docs/versioned/57.2.0/tasks/comms-adapter-twilio-sms.md

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

package/dist/docs/versioned/57.2.0/tasks/comms-adapter-twilio-verify.md

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