@terreno/mcp 57.0.0 → 57.2.0

package/src/docs/versioned/57.1.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/src/docs/versioned/57.1.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/src/docs/versioned/57.1.0/tasks/ai-dev-loop-boost.md

@@ -0,0 +1,120 @@
+# Task List: The AI Development Loop (Boost)
+
+See: [`docs/implementationPlans/ai-dev-loop-boost.md`](../implementationPlans/ai-dev-loop-boost.md)
+
+**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` rename `get_rtk_state` and relocate `installTerrenoDevConsoleLogger`; they require PR #869 merged in addition to PR #802. Unmarked tasks require only #802.
+
+## Instructions for the implementing agent
+
+- **Phase 1 gates everything.** PR #802 was in draft when this IP was written. Verify every tool name, parameter, and environment variable against the merged source in `mcp-server/src/local/` and `mcp-server/src/tools.ts` before documenting anything.
+- Every tool output shown in documentation must be real output from a real run, not a plausible-looking example.
+- Do not add new MCP tools. This IP documents and renames; it does not expand the surface.
+- Run `bun run mcp:build`, `bun run lint`, and `bun run compile` before each commit. Run `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 1: Reconcile with merged #802
+
+- [ ] **Task 1.1**: Inventory the actual MCP surface
+  - Description: Read `mcp-server/src/tools.ts`, `mcp-server/src/prompts.ts`, `mcp-server/src/resources.ts`, `mcp-server/src/local/localTools.ts`, and every file under `mcp-server/src/local/tools/`. Produce a table of every tool with its exact name, input schema, and which server hosts it. Separately list every environment variable the servers read (`TERRENO_MCP_EVAL`, `TERRENO_METRO_URL`, `TERRENO_PROJECT_ROOT`, `TERRENO_LOG_FILE`, `TERRENO_BROWSER_LOGS`, and any others found). Compare against the tool table in the IP and correct the IP where it is wrong. Put the deltas in the PR body.
+  - Files: `docs/implementationPlans/ai-dev-loop-boost.md`
+  - Depends on: PR #802 merged
+  - Acceptance: every tool in the corrected table is greppable in the source; every environment variable cites its reading file; the PR body lists what differed from the pre-merge IP.
+
+- [ ] **Task 1.2**: Verify the log pipeline end to end
+  - Description: Start the example backend and frontend, then exercise each `read_logs` source and record real output: `backend` (winston JSONL file transport), `app` (console output over Metro CDP), `metro` (bundler events), and `browser` (POST fallback). Deliberately break something to produce an error and confirm `last_error` returns it with a stack. Note which sources required extra setup and what happens when Metro is not running. Save the real outputs for use in the documentation tasks.
+  - Files: none (findings recorded for later tasks)
+  - Depends on: Task 1.1
+  - Acceptance: all four sources produced output, or any that did not is documented with the reason; `last_error` output captured verbatim including a stack trace.
+
+- [ ] **Task 1.3**: Reproduce the Hermes CDP contention symptom
+  - Description: With `read_logs` connected and streaming `app` source entries, open React Native DevTools (press `j` in Metro) and observe what happens to the log tool. Record the exact status message or failure the tool reports. Then close DevTools and confirm whether the tool recovers automatically. This becomes the documented symptom and workaround.
+  - Files: none (findings recorded for later tasks)
+  - Depends on: Task 1.2
+  - Acceptance: the symptom is recorded verbatim; recovery behavior (automatic or requiring a retry) is confirmed by observation.
+
+## Phase 2: Reference completeness
+
+- [ ] **Task 2.1**: Update `docs/reference/mcp-server.md`
+  - Description: Rewrite the tool sections to match the Task 1.1 inventory exactly. Split clearly into "Hosted server (`terreno-mcp`)" and "Local server (`terreno-mcp-local`)" sections. For each tool: name, purpose, input schema table, example call, and example output. Add an "Environment variables" section listing every variable from Task 1.1 with its effect and default. Add a "What the local server can and cannot see" section — it reads `package.json`/lockfiles, connects to Mongo via the consumer's `.env`, tails log files, and attaches over CDP; it never imports consumer code. Document the Hermes limitation from Task 1.3. Update the hosted URL per IP question AI6 if the domain decision has been made.
+  - Files: `docs/reference/mcp-server.md`
+  - Depends on: Task 1.1, Task 1.3
+  - Acceptance: tool list matches the inventory one-to-one; every environment variable documented; the can/cannot-see section is present; the Hermes symptom is quoted from Task 1.3.
+
+- [ ] **Task 2.2**: Sync `mcp-server/README.md`
+  - Description: Bring the package README's tool list in line with the reference page (it is known to omit `terreno_search_docs`, `terreno_get_component_docs`, and `terreno_get_upgrade_guide`). Keep the README short — the six-section template from [`docs-reference-coverage`](../implementationPlans/docs-reference-coverage.md) — and link the reference page for full detail.
+  - Files: `mcp-server/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: the README and reference page list identical tool sets; the README follows the standard template; all links absolute.
+
+- [ ] **Task 2.3**: Document the browser-log route
+  - Description: Add `POST /__terreno/browser-logs` to `docs/reference/api.md` (or the appropriate reference page) documenting: that it is registered only when `NODE_ENV !== "production"`, that it 404s in production, the `TERRENO_BROWSER_LOGS=false` override, the JSONL file it appends to, and the payload shape. Verify all of this against `api/src/browserLogsRoute.ts` in the merged tree.
+  - Files: `docs/reference/api.md`, `docs/reference/environment-variables.md`
+  - Depends on: Task 1.1
+  - Acceptance: every behavior claimed matches `api/src/browserLogsRoute.ts`; the production 404 behavior is stated; the env var appears in the environment reference.
+
+## Phase 3: The loop explainer
+
+- [ ] **Task 3.1**: Write `docs/explanation/ai-development-loop.md`
+  - Description: Explainer covering the five stages (Ask, Generate, Run, Observe, Fix) with the mermaid diagram from the IP. For each stage, name the tools involved and what they contribute. Then a "Tool layer versus process layer" section using the table from the IP, stating that this page covers the tool layer and that the `/terreno-*` SDLC pipeline is the process layer, with a link to `docs/explanation/agentic-sdlc.md` — do not duplicate that page's content. Then a "What makes this different" section built on one narrow, defensible claim: the agent observes what the app actually did rather than a description of it. Then a "What the agent cannot see" section — production logs, native crash reports outside the dev loop, anything requiring a physical device not attached to a dev server, and the Hermes single-connection limitation. Then a "How this composes" section covering `expo-mcp` for simulator interaction, Playwright MCP for web, and Maestro for durable E2E flows, with the division of labor. No commands — this is conceptual.
+  - Files: `docs/explanation/ai-development-loop.md` (new), `docs/explanation/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: all five stages present with real tool names from the inventory; the tool/process table is present and links the companion page; the cannot-see section has at least four honest limitations; no shell commands; listed in the explanation index.
+
+- [ ] **Task 3.2**: Write `docs/explanation/agent-guidelines.md`
+  - Description: Explainer on how conventions reach an agent: the hosted server's docs resources and search, per-package `.ai/guidelines/` shipped in npm tarballs (verify whether #802 Phase 2 shipped this before documenting it — if not, describe only what exists and note the rest as planned), `terreno_bootstrap_ai_rules` for generating editor-specific rule files, and the `.rulesync/` source-of-truth pattern with its generated targets. Add a section for consumers on extending the generated rules with their own project conventions without losing them on regeneration.
+  - Files: `docs/explanation/agent-guidelines.md` (new), `docs/explanation/README.md`
+  - Depends on: Task 1.1
+  - Acceptance: every mechanism described is verified present in the merged tree, with anything unshipped clearly labeled as planned; the consumer-extension section gives a concrete pattern.
+
+## Phase 4: Setup and debug how-tos
+
+- [ ] **Task 4.1**: Write `docs/how-to/set-up-terreno-mcp.md`
+  - Description: Per-editor setup for both Terreno servers. Cover at minimum Cursor (`.cursor/mcp.json`) and Claude Code, with the exact JSON for each including the hosted HTTP entry and the `bunx terreno-mcp-local` stdio entry. Then: what `terreno-mcp-local` needs to work (project root discovery and the `TERRENO_PROJECT_ROOT` override, a reachable `MONGO_URI`, the backend log file, Metro running for app logs); an optional section on adding `expo-mcp` and Playwright MCP with the division of labor from Task 3.1; and a verification section — ask the agent to call `application_info` and confirm it reports the project's `@terreno/*` versions. Compare the JSON against what `terreno_bootstrap_app` actually generates and make them identical.
+  - Files: `docs/how-to/set-up-terreno-mcp.md` (new), `docs/how-to/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: configuration for at least two editors, each verified by actually loading it; the JSON matches bootstrap output byte-for-byte in structure; the `application_info` verification step works.
+
+- [ ] **Task 4.2**: Write `docs/how-to/debug-with-mcp.md`
+  - Description: Task-focused guide using the real failure and real outputs captured in Task 1.2. Structure: the symptom; `last_error` to locate it; `read_logs` with source filtering to see the surrounding context; `database_query` to check the data; `get_client_state` to check the client; `navigate` plus a screenshot from the composed server to confirm the fix. Include a "which tool for which symptom" table (app crashes on a screen; API returns 403; data looks wrong; screen renders empty; bundler fails). Use verbatim tool output.
+  - Files: `docs/how-to/debug-with-mcp.md` (new), `docs/how-to/README.md`
+  - Depends on: Task 1.2, Task 4.1
+  - Acceptance: all tool outputs are verbatim from Task 1.2; the symptom-to-tool table has at least five rows; the walkthrough ends with a verified fix.
+
+- [ ] **Task 4.3**: Add discovery paths for the local server
+  - Description: Nothing currently tells a developer that `terreno-mcp-local` exists. Add links to `docs/how-to/set-up-terreno-mcp.md` from: the README's MCP section, `docs/README.md` quick links, `docs/tutorials/README.md`, and the `terreno://docs/overview` MCP resource. Also confirm `terreno_bootstrap_app` output includes a comment or README line pointing at the setup guide.
+  - Files: `README.md`, `docs/README.md`, `docs/tutorials/README.md`, `mcp-server/src/docs/resources/overview.md`, `mcp-server/src/docs/templates/bootstrap/**`
+  - Depends on: Task 4.1
+  - Acceptance: at least four discovery paths link the setup guide; bootstrap output references it; `bun run mcp:build` succeeds.
+
+## Phase 5: Gap fixes
+
+- [ ] **Task 5.1**: `[RTK]` Rename `get_rtk_state` to `get_client_state`
+  - Description: Per IP question AI1, rename the tool to `get_client_state` and extend it to detect either store type, returning a field identifying which layer it found (RTK Query cache versus syncdb store). Keep `get_rtk_state` registered as an alias whose description marks it deprecated and names the replacement. Update the tool description to explain what it returns for each layer. Add tests covering: syncdb store present, RTK store present, neither present, and the alias resolving to the same handler.
+  - Files: `mcp-server/src/local/tools/runtime.ts`, `mcp-server/src/local/localTools.ts`, tests under `mcp-server/src/local/`
+  - Depends on: Task 1.1, PR #869 merged
+  - Acceptance: both names work; the response identifies the detected layer; the alias description marks it deprecated; all four test cases pass; `bun run mcp:build` succeeds.
+
+- [ ] **Task 5.2**: `[RTK]` Relocate the dev console logger
+  - Description: Per IP question AI2, move `installTerrenoDevConsoleLogger` from `rtk/src/devConsoleLogger.ts` to the syncdb package, keeping a re-export from `@terreno/rtk` for the deprecation window so existing consumers are unaffected. Move its tests with it. Update the bootstrap `_layout` template and `example-frontend/app/_layout.tsx` to import from the new location. Add the re-export to the RTK deprecation notes.
+  - Files: `syncdb/src/devConsoleLogger.ts` (moved), `rtk/src/devConsoleLogger.ts` (re-export), `rtk/src/index.ts`, `syncdb/src/index.ts`, `mcp-server/src/docs/templates/bootstrap/frontend/app/_layout.template.tsx`, `example-frontend/app/_layout.tsx`, tests
+  - Depends on: Task 5.1
+  - Acceptance: both import paths work; tests pass from the new location; `bun run compile` succeeds across the workspace; the example app still ships browser logs to the backend route (verify by producing a `console.error` and reading it back with `read_logs`).
+
+- [ ] **Task 5.3**: Add rate limiting to the hosted MCP server
+  - Description: Per IP question AI5 — a launch prerequisite. Add per-IP rate limiting to the hosted server's JSON-RPC endpoint. Choose limits appropriate to the workload (search and codegen are cheap per call; the index is built once at startup) and make them configurable by environment variable with a sensible default. Return a clear JSON-RPC error when exceeded, naming the limit and the retry window. Add tests for under-limit, at-limit, and over-limit behavior. Document the limit in `docs/reference/mcp-server.md`.
+  - Files: `mcp-server/src/index.ts`, tests under `mcp-server/src/`, `docs/reference/mcp-server.md`, `docs/reference/environment-variables.md`
+  - Depends on: Task 2.1
+  - Acceptance: exceeding the limit returns a structured error naming the limit and retry window; the limit is configurable by environment variable; three test cases pass; the limit is documented.
+
+- [ ] **Task 5.4**: Handle the MCP domain change
+  - Description: If program question P4 / IP question AI6 was answered in favor of moving off `mcp.terreno.flourish.health`, update every occurrence of the URL: `README.md`, `docs/reference/mcp-server.md`, `mcp-server/README.md`, `mcp-server/src/**` defaults, bootstrap templates, and `infra/flourish/` deployment config. Keep the old hostname serving with a redirect or CNAME for at least one release and document the cutover. If the decision was to keep the current domain, make no change and record that.
+  - Files: various (grep `rg -n "mcp\.terreno"`)
+  - Depends on: Task 2.1
+  - Acceptance: `rg -n "mcp\.terreno\.flourish\.health"` returns only intentional legacy references; a bootstrapped app's `mcp.json` uses the new URL; the cutover plan is documented; or the no-change decision is recorded in the PR body.
+
+## Phase 6: Verification
+
+- [ ] **Task 6.1**: Run the loop end to end and capture evidence
+  - Description: In a fresh agent session with both MCP servers configured per `docs/how-to/set-up-terreno-mcp.md`, complete a full loop: ask for a small feature, let the agent generate it, run the app, introduce a bug, use `last_error` and `read_logs` to find it, fix it, and verify with `navigate` plus a screenshot. Capture the transcript highlights and screenshots to `/opt/cursor/artifacts/`. Fix any documentation gap the run exposed.
+  - Files: any documentation needing correction
+  - Depends on: Task 4.2, Task 5.1, Task 5.3
+  - Acceptance: the full loop completed in one session using only the public docs; artifacts captured showing the `last_error` output and the verified fix; every gap fixed.

package/src/docs/versioned/57.1.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, orgs-and-teams Phase 3
+  - Acceptance: mocked-Stripe supertest incl. permission denials
+- [ ] **Task 2.2**: `getEntitlements` + `planSegment` + `RequiresPlan`
+  - Description: cache-backed entitlement service; feature-flag segment factory; permission
+  - Files: `billing/src/billingService.ts`
+  - Depends on: 1.2
+  - Acceptance: zero inline Stripe calls asserted; flag targeting test with FeatureFlagsApp
+- [ ] **Task 2.3**: `GET /billing/subscription`
+  - Description: org subscription + entitlements for members
+  - Files: `billing/src/billingApp.ts`
+  - Depends on: 2.2
+  - Acceptance: supertest member/non-member
+
+## Phase 3 — Webhook sync (gated on inbound-webhooks)
+
+- [ ] **Task 3.1**: Stripe webhook route with signature verification
+  - Description: raw-body route via inbound-webhooks; reject unsigned
+  - Files: `billing/src/stripeSync.ts`
+  - Depends on: inbound-webhooks IP
+  - Acceptance: signed/unsigned fixture tests
+- [ ] **Task 3.2**: Idempotent event handlers
+  - Description: checkout.session.completed, subscription created/updated/deleted, invoice paid/payment_failed → model sync via `BillingEvent`
+  - Files: `billing/src/stripeSync.ts`
+  - Depends on: 3.1
+  - Acceptance: replay of same event id is a no-op; cancellation downgrades after webhook
+- [ ] **Task 3.3**: Dunning email
+  - Description: `paymentFailed` template through comms when configured
+  - Files: `billing/src/stripeSync.ts`, `comms/src/templates.ts`
+  - Depends on: 3.2, comms-abstraction
+  - Acceptance: template send asserted on payment_failed fixture
+
+## Phase 4 — UI + example + docs
+
+- [ ] **Task 4.1**: Plan picker + billing settings screens
+  - Description: example-frontend screens per IP; SDK regen
+  - Files: `example-frontend/app/**`, `store/openApiSdk.ts`
+  - Depends on: Phase 2
+  - Acceptance: UI verification evidence per verify-ui-changes (Stripe test mode)
+- [ ] **Task 4.2**: example-backend registration + seeds + docs
+  - Description: env-gated BillingApp; test-mode setup guide; how-to + reference docs
+  - Files: `example-backend/src/server.ts`, `docs/how-to/add-billing.md`, `docs/reference/billing.md`
+  - Depends on: Phase 2
+  - Acceptance: docs build + `bun run rules:check` pass
+- [ ] **Task 4.3**: CI + publish wiring
+  - Description: billing-ci workflow; publish-on-tag entry
+  - Files: `.github/workflows/*`
+  - Depends on: 1.1
+  - Acceptance: CI green

package/src/docs/versioned/57.1.0/tasks/build-terreno-app-validation.md

@@ -0,0 +1,121 @@
+# Task List: Dogfooding Run and Launch Blog Post
+
+See: [`docs/implementationPlans/build-terreno-app-validation.md`](../implementationPlans/build-terreno-app-validation.md)
+
+**RTK deprecation flag:** **Blocked.** The run must target syncdb + Better Auth. Do not start until PR #869 has merged and [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md), [`docs-reference-coverage`](docs-reference-coverage.md), and [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md) are complete — the run tests those documents, so running earlier tests nothing.
+
+## Instructions for the implementing agent
+
+- **The public-sources-only rule is the experiment.** Read the [`build-terreno-app`](../../.rulesync/skills/build-terreno-app/SKILL.md) skill and follow its restrictions exactly. Reading `.rulesync/`, `docs/implementationPlans/`, or Terreno source to unblock yourself invalidates the run. If you do it accidentally, say so in the friction log — a disclosed contamination is recoverable, a hidden one is not.
+- Work outside the Terreno monorepo. Fresh directory, fresh environment.
+- Log friction as it happens, with timestamps. Do not reconstruct the log at the end.
+- Do not fix Terreno during a run. Record the gap, work around it, keep going. Fixes happen between runs, in the owning IPs.
+- Never claim a step succeeded without evidence.
+
+## Phase 1: Run 1
+
+- [ ] **Task 1.1**: Confirm the concept and prerequisites
+  - Description: Confirm which app concept to build (IP question B1 — **Pantry**). Record the environment: OS, Bun version, editor and agent model with version (required per IP question B6), installed Terreno version, and the resolved stack mode. Confirm the stack mode is syncdb + Better Auth; if it is not, stop — the run is premature.
+  - Files: `FRICTION_LOG.md` in the working directory (outside this repo)
+  - Depends on: PR #869 merged; the three prerequisite IPs complete
+  - Acceptance: the log header is complete including the agent model and version; the stack mode is confirmed as syncdb + Better Auth; the working directory is outside the Terreno monorepo.
+
+- [ ] **Task 1.2**: Execute run 1
+  - Description: Run the `build-terreno-app` skill through all seven of its phases: learn the framework as a newcomer, scaffold, build the slices in the concept's order, exercise the six differentiators, use the AI debug loop on a deliberate bug, deploy, and report. Log every gap with severity, phase, what was missing, the workaround, and a suggested fix. Capture the required artifacts as you go rather than at the end.
+  - Files: `FRICTION_LOG.md`, the demo app source, artifacts in `/opt/cursor/artifacts/`
+  - Depends on: Task 1.1
+  - Acceptance: all seven skill phases attempted; every gap logged with all five fields; the artifact checklist from the blog outline is complete or each missing item has a logged reason.
+
+- [ ] **Task 1.3**: Record the debug-loop measurement
+  - Description: The deliberate bug in skill phase 5 is the most important single measurement in this IP. Record: the bug introduced, the symptom observed, which tools were called in what order, the elapsed time from symptom to fix, and — critically — whether framework source had to be read or print statements added. Quote the `last_error` output verbatim.
+  - Files: `FRICTION_LOG.md`
+  - Depends on: Task 1.2
+  - Acceptance: elapsed time recorded; the tool call sequence recorded; the source-reading question answered explicitly yes or no; `last_error` output quoted verbatim.
+
+## Phase 2: Triage
+
+- [ ] **Task 2.1**: Classify and route every gap
+  - Description: For each gap in the run 1 log, assign a severity (blocking / major / minor) and route it to the owning IP using the routing table in the IP. Produce a triage table: gap, severity, owning IP, proposed issue title, proposed labels. Flag any gap that does not fit an existing IP — it may indicate a missing IP.
+  - Files: `FRICTION_LOG.md`, a triage section in the run report
+  - Depends on: Task 1.3
+  - Acceptance: every gap has a severity and an owning IP or is flagged as unrouted; the routing matches the IP's table; unrouted gaps are called out with a recommendation.
+
+- [ ] **Task 2.2**: Prepare the issue set
+  - Description: Write ready-to-file issue bodies for every blocking and major gap, following the repo's issue-form fields from [`oss-governance-baseline`](../implementationPlans/oss-governance-baseline.md). Each must be understandable by someone who did not do the run: the expected behavior, what actually happened, the exact step in the exact document, and the suggested fix. Do not file them unless explicitly asked — list them for a maintainer.
+  - Files: a section in the run report
+  - Depends on: Task 2.1
+  - Acceptance: one issue body per blocking and major gap; each names the specific document and step; each is comprehensible without the friction log.
+
+- [ ] **Task 2.3**: Update the owning IPs' task lists
+  - Description: For each routed gap, add a task to the owning IP's task file in `docs/tasks/` describing the fix, referencing the run's finding. This is the only writing this IP does inside the Terreno repo during the fix cycle — the fixes themselves belong to the owning IPs.
+  - Files: `docs/tasks/*.md` for the owning IPs
+  - Depends on: Task 2.2
+  - Acceptance: every blocking and major gap has a corresponding task in an owning IP's task file; each new task cites the run finding.
+
+## Phase 3: Fix cycle
+
+- [ ] **Task 3.1**: Track fix completion
+  - Description: Wait for the owning IPs to land the fixes. Maintain a tracking table in the run report: gap, owning IP, fix status, PR link. Do not perform the fixes here — doing so scatters ownership and means the fix is not covered by the owning IP's acceptance criteria.
+  - Files: the run report
+  - Depends on: Task 2.3
+  - Acceptance: every blocking and major gap shows a landed fix with a PR link, or an explicit decision to accept it with reasoning.
+
+## Phase 4: Run 2
+
+- [ ] **Task 4.1**: Execute run 2 in a fresh environment
+  - Description: Repeat Task 1.2 in a genuinely fresh session and environment — no cached dependencies, no carried-over context, ideally a different agent session with no memory of run 1. Build the same concept so the runs are comparable. Produce a second independent friction log.
+  - Files: `FRICTION_LOG_2.md`, the demo app source, artifacts
+  - Depends on: Task 3.1
+  - Acceptance: run 2 was performed in a fresh environment with no carried context; the same concept was built; a second complete friction log exists.
+
+- [ ] **Task 4.2**: Repeat-gap analysis
+  - Description: Compare both logs. Produce three lists: gaps fixed (present in run 1, absent in run 2), gaps that survived (present in both — for each, explain why the fix did not work), and new gaps (only in run 2, which often means a fix introduced a problem). Report the total counts by severity for each run.
+  - Files: a comparison section in the run report
+  - Depends on: Task 4.1
+  - Acceptance: all three lists produced; every surviving gap has an explanation; severity counts for both runs are stated.
+
+- [ ] **Task 4.3**: Evaluate the launch gate
+  - Description: Check run 2 against the pass thresholds in the IP: zero blocking gaps, zero major gaps, every concept slice working on web and one native target, all six differentiators with artifacts, deployment with all four checks passing, and the debug loop completed without reading framework source. State pass or fail per gate. If any gate fails, return to Phase 3 — do not proceed to the blog post.
+  - Files: the run report
+  - Depends on: Task 4.2
+  - Acceptance: every gate has an explicit pass or fail with evidence; a failure sends the work back to Phase 3 rather than proceeding.
+
+## Phase 5: Blog post
+
+- [ ] **Task 5.1**: Draft the post
+  - Description: Write `BLOG_DRAFT.md` following the nine-section outline in the skill's blog reference. Use real elapsed times, real code from the built app, and real artifacts. The "what did not work" section takes the three most instructive gaps from the logs — pick genuinely instructive ones, not three trivial gaps chosen to look candid. Name the agent model and version. Include the debug-loop measurement from Task 1.3 (and its run 2 equivalent) as a concrete number.
+  - Files: `BLOG_DRAFT.md`
+  - Depends on: Task 4.3
+  - Acceptance: all nine sections present; 1,800–2,500 words; every superlative quantified; three real gaps in the "what did not work" section with their fixes and PR links; the model and version named.
+
+- [ ] **Task 5.2**: Artifact and fact review
+  - Description: Have someone who did not perform the run verify every claim in the draft against an artifact. Produce a checklist: claim, backing artifact, verified yes/no. Remove or correct any claim without backing. Also verify no claim describes an unshipped feature by checking each against the public docs.
+  - Files: `BLOG_DRAFT.md`, a review checklist
+  - Depends on: Task 5.1
+  - Acceptance: every claim has a verified backing artifact; the reviewer is not the person who did the build; no claim references an unshipped feature.
+
+- [ ] **Task 5.3**: Publish the demo app repository
+  - Description: Per IP question B2, publish the demo app to its own repository with a README stating what it is, which Terreno version it was built against, that it is a blog-post artifact rather than a maintained example, and a link to the post. Include the app's own setup instructions so a reader can run it. Do not add it to the Terreno monorepo.
+  - Files: a new repository (outside this repo)
+  - Depends on: Task 5.2
+  - Acceptance: the repository is public with a complete README; the app runs from a fresh clone following its README; the unmaintained status is stated; it is not added to the monorepo.
+
+- [ ] **Task 5.4**: Publish the dogfooding results
+  - Description: Create `docs/explanation/dogfooding-results.md` in the Terreno repo summarizing both runs publicly: what was tested, gap counts by severity per run, what changed between them, and what remains known-imperfect. This is the durable, honest artifact — the blog post is marketing that happens to be true, this is the engineering record. Link it from `CONTRIBUTING.md` as evidence of how the project evaluates its own developer experience.
+  - Files: `docs/explanation/dogfooding-results.md` (new), `docs/explanation/README.md`, `CONTRIBUTING.md`
+  - Depends on: Task 4.2
+  - Acceptance: both runs' counts published; remaining known gaps listed rather than omitted; linked from the explanation index and `CONTRIBUTING.md`.
+
+## Phase 6: Retrospective
+
+- [ ] **Task 6.1**: Improve the harness
+  - Description: Record what the `build-terreno-app` skill itself got wrong: steps that were ambiguous, phases that were mis-scoped, artifacts that turned out not to be worth capturing, and measurements that should have been taken but were not. Update the skill and its references, then regenerate mirrors with `bun run rules`.
+  - Files: `.rulesync/skills/build-terreno-app/SKILL.md`, `.rulesync/skills/build-terreno-app/references/*`, generated mirrors
+  - Depends on: Task 4.2
+  - Acceptance: at least three concrete skill improvements landed from real experience; `bun run rules:check` exits 0.
+
+- [ ] **Task 6.2**: Recommend a cadence
+  - Description: Based on the actual effort of both runs, recommend how often this should be repeated and what triggers an unscheduled run (a major version, a data-layer change, a docs restructure). Add the recommendation to `docs/explanation/dogfooding-results.md`. Do not create a recurring commitment the team cannot keep — an abandoned cadence is worse than no cadence.
+  - Files: `docs/explanation/dogfooding-results.md`
+  - Depends on: Task 6.1
+  - Acceptance: the recommendation states an interval and the unscheduled triggers, and is justified by the measured effort of the two runs.