@terreno/mcp 57.0.0 → 57.1.0

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

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

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

@@ -1,163 +1,57 @@
-# Task List: Publish and Document the Agentic SDLC Plugin
+# Task List: Loop-Engineering Lifecycle Plugin
 
 See: [`docs/implementationPlans/agentic-sdlc-plugin.md`](../implementationPlans/agentic-sdlc-plugin.md)
 
-**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` update the frontend-verification path lists, which name `rtk/` today and must name `syncdb/` after PR #869. Everything else is safe to implement now.
-
-## Instructions for the implementing agent
-
-- Read all five skill files under `plugins/terreno-planning/skills/` before changing any of them. The stages reference each other's scope boundaries, so an edit to one often requires a matching edit elsewhere.
-- Do not change what a stage *does*. This IP is packaging, portability, and documentation. If you believe a stage's procedure is wrong, note it and propose it separately.
-- When you remove Flourish-specific content, do not remove the underlying judgment. "Apply PHI minimum-necessary handling" becomes a rule about sensitive data, not nothing.
-- Test portability claims by actually running the pipeline outside this repository. A portability fix you did not exercise in a consumer app is unverified.
-- Run `bun run rules:check` after touching `.rulesync/`, and `bun run check` before each commit.
-
-## Phase 1: Decide and sanitize
-
-- [x] **Task 1.1**: Audit the plugin for repo- and org-specific content
-  - Description: Grep all five skills for Flourish-specific and monorepo-specific content: `rg -n -i "phi|hipaa|flourish|dcb3|example-frontend|admin-spa|bun run|docs/implementationPlans"` across `plugins/`. Produce a table: file, line, category (org-specific / repo-path / hardcoded value / tool assumption), and the proposed replacement. Include the `.cursor-plugin/*.json` files (owner email, marketplace description). Do not change anything yet.
-  - Files: none (findings in the PR body)
-  - Depends on: none
-  - Acceptance: every hit is categorized with a proposed replacement; the table covers all five skills plus both JSON files.
-
-- [x] **Task 1.2**: Generalize sensitive-data handling
-  - Description: Per IP question AP2, replace PHI/HIPAA-specific language with generalized sensitive-data language across `terreno-1-blend`, `terreno-4-pour`, and `terreno-5-dialin`. The rule must survive the rewrite: PR text, review replies, and attached evidence media must not contain sensitive data (PHI, PII, credentials, customer data). Keep it concrete — a vague "be careful with data" is not a usable instruction for an agent.
-  - Files: `plugins/terreno-planning/skills/terreno-1-blend/SKILL.md`, `terreno-4-pour/SKILL.md`, `terreno-5-dialin/SKILL.md`
-  - Depends on: Task 1.1
-  - Acceptance: `rg -n -i "phi|hipaa" plugins/` returns nothing; each rewritten rule names the specific artifacts it applies to (PR body, comments, screenshots, recordings) and the data categories.
-
-- [x] **Task 1.3**: Fix the hardcoded branch suffix
-  - Description: `terreno-4-pour` documents the branch convention as `cursor/<descriptive-name>-dcb3`. The suffix is per-agent-run, not a fixed literal, so this will produce wrong branch names. Replace it with a description of the convention (a `cursor/` prefix plus the run-specific suffix the agent was given) and instruct the agent to use the suffix from its own run instructions rather than any literal in the skill.
-  - Files: `plugins/terreno-planning/skills/terreno-4-pour/SKILL.md`
-  - Depends on: Task 1.1
-  - Acceptance: no literal run suffix appears anywhere in `plugins/`; the convention is described such that an agent in any run produces a correctly-suffixed branch.
-
-- [x] **Task 1.4**: Clean up plugin metadata
-  - Description: Update `.cursor-plugin/marketplace.json` and `plugins/terreno-planning/.cursor-plugin/plugin.json`: adjust the marketplace description per the AP1 decision (it currently says "Team marketplace"), review whether a personal email is the right contact for a public plugin versus a role address, and add a field or README note declaring which Terreno versions the plugin targets (IP question AP7). Add `plugins/terreno-planning/LICENSE` matching the root license.
-  - Files: `.cursor-plugin/marketplace.json`, `plugins/terreno-planning/.cursor-plugin/plugin.json`, `plugins/terreno-planning/LICENSE` (new)
-  - Depends on: Task 1.1
-  - Acceptance: both JSON files are valid and consistent with the AP1 decision; the contact address is a deliberate choice; the targeted Terreno version range is declared; the LICENSE matches the root license.
-
-## Phase 2: Portability
-
-- [ ] **Task 2.1**: Remove repo-root-relative sibling-skill paths
-  - Description: `terreno-4-pour` step 6 instructs reading `plugins/terreno-planning/skills/terreno-5-dialin/SKILL.md` "from the repository root", and `terreno-5-dialin` does the same for Pour. That path only resolves when the workspace happens to be this repository — an installed plugin lives in the agent's plugin cache. Replace with guidance that resolves in both cases: reference the sibling skill relative to the current skill's own location, and keep the existing note that Cursor may not resolve plugin skill names alone. Verify the replacement actually works by running Pour's handoff from a workspace that is not this repo.
-  - Files: `plugins/terreno-planning/skills/terreno-4-pour/SKILL.md`, `terreno-5-dialin/SKILL.md`
-  - Depends on: Task 1.3
-  - Acceptance: the handoff resolves both inside this repo and in a consumer app; no absolute or repo-root-relative path to a sibling skill remains; the fix was exercised in a non-Terreno workspace.
-
-- [ ] **Task 2.2**: Resolve the `verify-ui-changes` dependency
-  - Description: Four stages invoke `verify-ui-changes` by name, but that skill lives in this repo's `.rulesync/skills/` and a consumer installing the plugin does not get it. Choose and implement one resolution: bundle a consumer-appropriate copy inside the plugin, or declare it as a prerequisite with installation instructions, or have `terreno_bootstrap_app` generate it into consumer apps. Whichever is chosen, a consumer running the pipeline must end up with a working frontend-verification step rather than a reference to a skill they do not have.
-  - Files: `plugins/terreno-planning/skills/*/SKILL.md`, plus the bundled skill or the bootstrap template
-  - Depends on: Task 2.1
-  - Acceptance: a consumer app that installed only the plugin can execute the frontend-verification step; the resolution is documented in `plugins/README.md`; no stage references a skill the user cannot obtain.
-
-- [ ] **Task 2.3**: `[RTK]` Derive frontend paths from project layout
-  - Description: The frontend gates in Roast, Pour, and Dial In hardcode Terreno monorepo package names (`ui/`, `demo/`, `example-frontend/`, `admin-frontend/`, `admin-spa/`, `rtk/`). Replace with layout detection: describe how to identify frontend paths in the two shapes that matter — this monorepo, and a bootstrapped consumer app (which uses `frontend/`/`backend/`) — and instruct the agent to determine the set rather than assume it. Update the path list to name `syncdb/` instead of `rtk/` per PR #869, keeping `rtk/` for the deprecation window.
-  - Files: `plugins/terreno-planning/skills/terreno-2-roast/SKILL.md`, `terreno-4-pour/SKILL.md`, `terreno-5-dialin/SKILL.md`
-  - Depends on: Task 2.2, PR #869 merged
-  - Acceptance: the gates fire correctly in both a bootstrapped consumer app and this monorepo, verified by running Roast on a frontend change in each; `syncdb/` is included and `rtk/` retained.
-
-- [ ] **Task 2.4**: Make Blend's conventions portable
-  - Description: `terreno-1-blend` assumes `docs/implementationPlans/` and `docs/tasks/`, a project registry containing only `flourishhealth/terreno`, and this repo's `bun run` command set. Generalize: describe where planning artifacts go with a documented default and a way to detect an existing convention, replace the hardcoded registry with a resolution procedure, and describe the command set as "the project's lint/compile/test commands" discovered from `package.json`. Keep the question-first behavior exactly as it is — that is the stage's most valuable property.
-  - Files: `plugins/terreno-planning/skills/terreno-1-blend/SKILL.md`
-  - Depends on: Task 2.1
-  - Acceptance: Blend produces an IP in a consumer app with no Terreno-specific directory assumptions; the question-first clarification gate is unchanged; the registry is a procedure rather than a fixed list.
-
-- [ ] **Task 2.5**: Verify the pipeline in a consumer app
-  - Description: Scaffold an app with `terreno_bootstrap_app`, install the plugin, and take one small feature from request to open PR through all five stages. Record every place the pipeline assumed something untrue about the project. Fix each. This task is the actual acceptance test for Phase 2 — the previous tasks are hypotheses until this passes.
-  - Files: any plugin skill needing correction
-  - Depends on: Task 2.3, Task 2.4
-  - Acceptance: all five stages complete in a consumer app; a PR is opened with evidence attached; every assumption failure found is fixed; the run is summarized in the PR body.
-
-## Phase 3: Resolve overlap with repo skills
-
-- [ ] **Task 3.1**: Map the overlap precisely
-  - Description: For each plugin stage, read its repo-skill counterparts (`submit`, `commit`, `create-pr`, `check-watcher`, `respond-to-review`, `autobot`, `ip`, `design-blend`, `implement`) and produce a table: plugin stage, overlapping skill, rules that agree, rules that **disagree**. The disagreements matter most — two documented processes with different rules is worse than either alone. Report in the PR body.
-  - Files: none (findings in the PR body)
-  - Depends on: none
-  - Acceptance: every stage is mapped to its counterparts; all rule disagreements are listed explicitly with both wordings.
-
-- [ ] **Task 3.2**: Make Brew self-contained; inline Taste review loop per AP5
-  - Description: Per IP question AP5, rewrite **Taste** (`terreno-5-taste`) to inline the full submit → CI → review loop (former `autobot` behavior) rather than delegating to repo skills — delegation has been unreliable inside the plugin. **Brew** (`terreno-4-brew`) may orchestrate `commit`/`create-pr` where those resolve from the plugin cache, but must not depend on monorepo-only paths. Resolve every disagreement from Task 3.1 in favor of one wording, in one place. Deprecate `submit` and `autobot` repo skills once Taste ships.
-  - Files: `plugins/terreno-planning/skills/terreno-4-brew/SKILL.md`, `terreno-5-taste/SKILL.md`, and deprecated `.rulesync/skills/submit/`, `autobot/`
-  - Depends on: Task 3.1, Task 2.5
-  - Acceptance: Taste completes a full review loop without delegating to repo skills; no rule appears in both a plugin stage and a repo skill with different wording; `submit`/`autobot` are marked deprecated; `bun run rules:check` exits 0.
-
-- [ ] **Task 3.3**: Cross-reference deprecated repo skills
-  - Description: Add a short deprecation note to `.rulesync/skills/submit/SKILL.md` and `autobot/SKILL.md` pointing to the plugin pipeline (Brew/Taste) as the supported path. Regenerate mirrors. Document in `plugins/README.md` that the individual repo skills are legacy once the plugin is public.
-  - Files: `.rulesync/skills/submit/SKILL.md`, `.rulesync/skills/autobot/SKILL.md`, generated mirrors, `plugins/README.md`
-  - Depends on: Task 3.2, Task 4.1
-  - Acceptance: both skills state they are deprecated in favor of Brew/Taste; the plugin README references them as legacy; `bun run rules:check` exits 0.
-
-## Phase 4: Documentation
-
-- [ ] **Task 4.1**: Write `plugins/README.md`
-  - Description: Under 150 lines. Cover: what the pipeline is in two sentences; the five stages in a table with the plain-language meaning of each coffee name per IP question AP3; installation (marketplace, per the AP1 decision); a quickstart showing one feature going through all five stages; prerequisites (the skill dependency from Task 2.2, the Terreno version range from Task 1.4); how it relates to the individual repo skills; and how to use a single stage without the full pipeline. Every command must be one you ran.
-  - Files: `plugins/README.md` (new)
-  - Depends on: Task 2.5
-  - Acceptance: under 150 lines; every coffee name is glossed; the installation steps were performed from a fresh state; the quickstart matches a run you completed.
-
-- [ ] **Task 4.2**: Write `docs/explanation/agentic-sdlc.md`
-  - Description: The conceptual case, no commands. Cover: the process layer versus the MCP tool layer, and why both are needed; why planning is a separate stage with a question-first gate (agents confidently plan the wrong thing); why review happens in a **fresh context** rather than by asking the implementing agent to check its own work; why verification is a separate stage from implementation; why the frontend gate demands evidence rather than a claim; and why flaky CI must be classified rather than guessed at. Then an honest limits section: what the pipeline does not do, where a human must decide, and why the review loop persists through slow CI but stops when no autonomous action can advance a terminal failure. Reuse the mermaid diagram from the IP.
-  - Files: `docs/explanation/agentic-sdlc.md` (new), `docs/explanation/README.md`
-  - Depends on: Task 4.1
-  - Acceptance: no commands; all six design rationales explained; a limits section naming at least three things the pipeline will not do; linked from the explanation index.
-
-- [ ] **Task 4.3**: Write `docs/how-to/use-the-terreno-plugin.md`
-  - Description: Task-focused: install the plugin, take a small feature from request to merged PR through all five stages, with the real output of each stage. Include what to do when a stage stops and asks a question (Blend's clarification gate), when Roast's review sub-agent flags something, and when Dial In reports blocked. Include a "using one stage on its own" section — most people will start with Pour or Dial In on existing work rather than adopting the whole pipeline at once.
-  - Files: `docs/how-to/use-the-terreno-plugin.md` (new), `docs/how-to/README.md`
-  - Depends on: Task 4.2
-  - Acceptance: the walkthrough was performed and the outputs shown are real; all three interruption cases documented; the single-stage section is present; listed in the how-to index.
-
-- [ ] **Task 4.4**: Write `docs/reference/sdlc-plugin.md`
-  - Description: Per-stage reference: name, slash command, plain-language purpose, preconditions, inputs, outputs, scope boundary (what it explicitly does not own), handoff target, and failure/exit conditions. Include the `disable-model-invocation` behavior — several stages are deliberately not auto-invocable and must be called explicitly — and explain why. Add the plugin to `docs/reference/README.md`.
-  - Files: `docs/reference/sdlc-plugin.md` (new), `docs/reference/README.md`
-  - Depends on: Task 4.1
-  - Acceptance: all five stages documented with all eight fields; the auto-invocation behavior matches each skill's frontmatter; listed in the reference index.
-
-## Phase 5: Positioning
-
-- [ ] **Task 5.1**: Add the pipeline to the positioning copy
-  - Description: Update `docs/explanation/positioning.md` (from [`positioning-django-rails-universal`](../implementationPlans/positioning-django-rails-universal.md)): name the pipeline in the AI-native pillar's `pillars` block, and rewrite the comparison table's generator row so it credits the pipeline — Django gives you `manage.py startapp`, Terreno gives you a reviewed path from request to mergeable PR. Add the tool-layer/process-layer distinction to the `pitch` block. Keep the copy blocks internally consistent, since every other surface copies them verbatim.
-  - Files: `docs/explanation/positioning.md`
-  - Depends on: Task 4.2
-  - Acceptance: the pipeline appears in the pillars block and the comparison table; the tool/process distinction is in the pitch; the blocks remain consistent with each other.
-
-- [ ] **Task 5.2**: Surface the pipeline in the README and docs landing
-  - Description: Add the pipeline to `README.md`'s AI section (currently only describes the MCP server) and to `docs/README.md`'s pillars, each with a link to the explainer and the how-to. Keep it to a short paragraph in each — the detail lives in the docs. Make sure the AI section names both layers so a reader understands they are complementary rather than alternatives.
-  - Files: `README.md`, `docs/README.md`
-  - Depends on: Task 5.1
-  - Acceptance: both surfaces name the pipeline and the MCP server as the two halves of the AI story; both link the explainer; neither exceeds a paragraph.
-
-- [ ] **Task 5.3**: Make agents aware of the pipeline
-  - Description: Add the pipeline to `.rulesync/rules/00-root.md` (source for `AGENTS.md`, `CLAUDE.md`, and the copilot instructions) and to `CLAUDE-consumer.md`, so an agent working in this repo or in a consumer app knows the pipeline exists and when to use it. Currently no root agent file mentions `plugins/` at all. Regenerate mirrors.
-  - Files: `.rulesync/rules/00-root.md`, `CLAUDE-consumer.md`, generated mirrors
-  - Depends on: Task 5.2
-  - Acceptance: `AGENTS.md` and `CLAUDE.md` both describe the pipeline and when to use it; `bun run rules:check` exits 0.
-
-- [ ] **Task 5.4**: Use the pipeline in the dogfooding harness
-  - Description: If AP1 made the plugin public, update `.rulesync/skills/build-terreno-app/SKILL.md` to install and use the pipeline during the dogfooding run — it is exactly the kind of public tooling that harness is meant to exercise, and the run will find portability problems that Task 2.5 missed. Add the plugin to the skill's list of permitted public sources, and add a friction-log section for pipeline-specific gaps. Regenerate mirrors.
-  - Files: `.rulesync/skills/build-terreno-app/SKILL.md`, generated mirrors
-  - Depends on: Task 5.3
-  - Acceptance: the harness installs and uses the pipeline; the plugin is listed among permitted sources; the friction log has a pipeline section; `bun run rules:check` exits 0.
-
-## Phase 6: Distribution
-
-- [ ] **Task 6.1**: Verify a fresh install
-  - Description: From a clean agent environment with no plugin cache, install the plugin per `plugins/README.md` and confirm all five stages are available and invocable. Record what the install experience actually looks like, including whether the stages appear as slash commands and whether the sibling-skill handoff from Task 2.1 resolves from the cache rather than the workspace.
-  - Files: `plugins/README.md` (corrections)
-  - Depends on: Task 4.1, Task 1.4
-  - Acceptance: a fresh install exposes all five stages; the handoff resolves from the plugin cache; every install-guide inaccuracy is fixed.
-
-- [ ] **Task 6.2**: Generate non-Cursor variants
-  - Description: Per IP question AP6, make the pipeline available outside Cursor by routing it through `.rulesync/`, which already generates skills for cursor, claude, devin, copilot, and agents targets. Decide whether the plugin skills become rulesync sources (generated into the plugin directory) or whether a parallel rulesync copy is maintained — prefer one source of truth. Document which runtimes are supported and any behavioral differences (notably that the `disable-model-invocation` and slash-command behavior is Cursor-specific).
-  - Files: `.rulesync/skills/` or the plugin skills, `plugins/README.md`, `docs/reference/sdlc-plugin.md`, generated mirrors
-  - Depends on: Task 6.1
-  - Acceptance: the pipeline is invocable in at least one non-Cursor runtime; there is a single source of truth per skill, not two divergent copies; runtime differences are documented; `bun run rules:check` exits 0.
-
-- [ ] **Task 6.3**: Extend license coverage to `plugins/`
-  - Description: Update `scripts/check-license-coverage.ts` (from [`oss-governance-baseline`](../implementationPlans/oss-governance-baseline.md)) so `plugins/terreno-planning/` is covered by the license check. Confirm the plugin ships a LICENSE and that its declared license matches the root license.
-  - Files: `scripts/check-license-coverage.ts`
-  - Depends on: Task 1.4, `oss-governance-baseline` Task 1.6
-  - Acceptance: `bun run check:licenses` covers the plugin; deleting `plugins/terreno-planning/LICENSE` makes it fail and name the plugin.
+## 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/next/tasks/comms-abstraction.md

@@ -9,39 +9,39 @@ IP: [comms-abstraction](../implementationPlans/comms-abstraction.md)
   - 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
-- [ ] **Task 1.2**: Provider interfaces and message types
-  - Description: `MailProvider`, `SmsProvider`, `PushProvider`, `VerificationProvider`, `SendResult` (incl. `errorCode`/`errorClass`), `DeliveryEvent`, `CommsHookContext`, `OptOutEvent` per IP
-  - Status: base provider/message contracts shipped; `errorCode`/`errorClass`, `CommsHookContext`, and `OptOutEvent` remain
-  - Files: `comms/src/types.ts`
+- [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
+  - 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
-- [ ] **Task 1.4**: `CommsMessage` model + `logSend`
-  - Description: delivery log model with five-type pattern, `description` on every field, plugins, static `logSend` that never throws; dashboard-ready fields (`errorCode`, `errorClass`, `attempts[]`, `attemptCount`, `lastAttemptAt`, `retriedFromId`/`retriedById`, `templateId`, retained `payload`)
-  - Files: `comms/src/models/commsMessage.ts` + tests
-  - Depends on: 1.1
-  - Acceptance: send logging survives a forced model error (logged, not thrown); attempts append per attempt
-  - Status: model and non-throwing `logSend` shipped; dashboard-ready fields remain
-- [ ] **Task 1.5**: `commsService` send facade
-  - Description: `sendMail`/`sendSms`/`sendPushToUser`/`startVerification`/`checkVerification`; template render helper; unconfigured-channel behavior (501 in prod, console fallback in dev); inline retry on `errorClass: "transient"` only
-  - Status: send facade, templates, and unconfigured-channel behavior shipped; inline transient retry remains
-  - Files: `comms/src/commsService.ts`, `comms/src/templates.ts` + tests
-  - Depends on: 1.2, 1.3, 1.4
-  - Acceptance: unit tests cover happy path + unconfigured channel in both env modes; permanent failures do not retry
-- [ ] **Task 1.6**: Lifecycle hooks
-  - Description: `beforeSend` (mutate/cancel), `onSend`, `onError`, `onRetry`, `onOptOut`, `onDeliveryEvent` wiring in the facade; every hook wrapped so a throw is logged and never changes the send outcome
+- [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
-- [ ] **Task 1.7**: Payload retention + redaction
-  - Description: `retainPayloadDays` (default 30) storage of rendered payload post-`redactPayload`; expiry cleanup clears `payload` without touching the log row
+  - 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
-  - Acceptance: payload stored redacted; expired payload cleared; `retainPayloadDays: 0` stores nothing
+  - 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
 
@@ -70,6 +70,7 @@ IP: [comms-abstraction](../implementationPlans/comms-abstraction.md)
   - 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
 
@@ -88,3 +89,8 @@ IP: [comms-abstraction](../implementationPlans/comms-abstraction.md)
   - 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/src/docs/versioned/next/tasks/comms-adapter-sendgrid.md

@@ -4,22 +4,22 @@ IP: [comms-adapter-sendgrid](../implementationPlans/comms-adapter-sendgrid.md)
 
 ## Phase 1 — Send path
 
-- [ ] **Task 1.1**: `SendGridMailProvider` with config + sandbox mode
+- [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
-- [ ] **Task 1.2**: Error classification
+- [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
-- [ ] **Task 1.3**: Dashboard metadata + hooks coverage
+- [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
-- [ ] **Task 1.4**: Peer dep + registration + docs
+- [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

package/src/docs/versioned/next/tasks/consent-forms.md

@@ -1,5 +1,7 @@
 # Task List: Consent Forms System
 
+**Status:** Closed (2026-08-20) — IP complete. Shipped in `@terreno/api` (`ConsentApp`) and `@terreno/ui`. Open tasks below were not executed.
+
 *Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
 
 ## Phase 1: Models + API

package/src/docs/versioned/next/tasks/feature-flags.md

@@ -1,5 +1,7 @@
 # Feature Flags — Task List
 
+**Status:** Closed (2026-08-20) — IP deferred; superseded by [feature-flags-openfeature.md](./feature-flags-openfeature.md). Open tasks below will not be executed.
+
 ## Phase 1: Backend + Evaluation Engine
 
 - [ ] **Task 1.1**: Create `feature-flags/` package with FeatureFlag model (including archived field)

package/src/docs/versioned/next/tasks/migrate-cicd-to-circleci.md

@@ -19,14 +19,16 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Files: `docs/how-to/circleci.md` (stub OK)
   - Depends on: none (human prerequisite)
   - Acceptance: a manual “hello” pipeline can be triggered from the project; dynamic config is enabled.
+  - Note: hello scaffold merged (#1052). Dynamic config + org slug still need maintainer confirmation.
 
 - [ ] **Task 0.2**: Create CircleCI Contexts (empty shells)
   - Description: Create contexts named in the IP (`terreno-npm`, `terreno-netlify`, `terreno-expo`, `terreno-gcp`, `terreno-e2e`, `terreno-release`, `terreno-agentic`, `terreno-github-api`). Document which GitHub secrets map into each. Do not paste secret values into the repo.
   - Files: `docs/how-to/circleci.md`
   - Depends on: Task 0.1
   - Acceptance: contexts exist; mapping table is complete; access restrictions noted for `terreno-release`.
+  - Note: mapping table documented in how-to; contexts themselves are still a human step.
 
-- [ ] **Task 0.3**: Inventory required GitHub checks
+- [x] **Task 0.3**: Inventory required GitHub checks
   - Description: List current branch-protection required checks and map each to the GHA job `name:` and the future CircleCI job name. Start from `docs/explanation/repository-settings.md` and live settings.
   - Files: `docs/how-to/circleci.md` or a short table in the IP
   - Depends on: none
@@ -34,43 +36,45 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
 
 ## Phase 1: Foundation
 
-- [ ] **Task 1.1**: Add setup + continue config skeleton
+- [x] **Task 1.1**: Add setup + continue config skeleton
   - Description: Create `.circleci/config.yml` with `setup: true` using `circleci/path-filtering` (and `circleci/continuation`). Create `.circleci/continue-config.yml` with parameters for each package/area and a no-op `config-ok` job that always runs.
   - Files: `.circleci/config.yml`, `.circleci/continue-config.yml`
   - Depends on: Task 0.1
   - Acceptance: push triggers setup → continuation; `config-ok` is green.
 
-- [ ] **Task 1.2**: Shared Bun + cache commands
+- [x] **Task 1.2**: Shared Bun + cache commands
   - Description: Add reusable commands (inline or orb) for installing Bun via `circleci/node`, `bun install --frozen-lockfile`, and cache keys equivalent to today’s GHA bun cache. Pin Bun policy (`latest` vs pin) consistently with EAS jobs that need a pin.
   - Files: `.circleci/continue-config.yml`
   - Depends on: Task 1.1
   - Acceptance: a sample job restores cache on second run; install is frozen-lockfile.
 
-- [ ] **Task 1.3**: Path-filter mapping
+- [x] **Task 1.3**: Path-filter mapping
   - Description: Encode path → parameter mapping for api, ai, ui, rtk, comms, mcp-server, admin-*, example-*, demo, docs/website, terraform, e2e-relevant sets, matching current workflow path filters.
   - Files: `.circleci/config.yml`
   - Depends on: Task 1.1
   - Acceptance: a docs-only change sets docs/deploy params without setting `run-api`.
+  - Note: deploy path params omitted until Phase 4+.
 
 ## Phase 2: Package CI + policy
 
-- [ ] **Task 2.1**: Port package CI jobs
+- [x] **Task 2.1**: Port package CI jobs
   - Description: Port api/ai/rtk/ui/ui-demo/comms/mcp-server/example-frontend/example-backend(+script)/admin-spa CI to CircleCI jobs gated by path params. Include Mongo service where GHA used it. Fix mcp branch filter to `master`.
   - Files: `.circleci/continue-config.yml`, possibly package scripts unchanged
   - Depends on: Task 1.2, Task 1.3
   - Acceptance: dual-run green for each package on a change that touches it; GHA still required.
 
-- [ ] **Task 2.2**: Port Docker build-only job
+- [x] **Task 2.2**: Port Docker build-only job
   - Description: Port `example-backend-docker.yml` to CircleCI remote Docker / machine with layer caching replacement for `type=gha`.
   - Files: `.circleci/continue-config.yml`
   - Depends on: Task 2.1
   - Acceptance: PR touching `example-backend/**` builds the image without pushing.
 
-- [ ] **Task 2.3**: Port repo-policies + rulesync + DCO
+- [x] **Task 2.3**: Port repo-policies + rulesync + DCO
   - Description: Port `repo-policies.yml`, `rulesync-check.yml`, and fork DCO checks. DCO must use GitHub API via `terreno-github-api` context.
   - Files: `.circleci/continue-config.yml`
   - Depends on: Task 0.2, Task 1.2
   - Acceptance: intentional barrel-import / dirty rulesync / missing DCO on a fork PR fails the CircleCI job.
+  - Note: DCO skips cleanly if `GITHUB_TOKEN` unset until context is created.
 
 - [ ] **Task 2.4**: Dual-run cutover for Phase 2
   - Description: Add CircleCI checks to branch protection; remove GHA package/policy workflows once trusted; delete corresponding `.github/workflows/*-ci.yml` and policy workflows.
@@ -80,7 +84,7 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
 
 ## Phase 3: Playwright E2E
 
-- [ ] **Task 3.1**: Port `e2e-ci` and `admin-spa-integration`
+- [x] **Task 3.1**: Port `e2e-ci` and `admin-spa-integration`
   - Description: Mongo replica set, E2E secrets context, Playwright browsers, artifact store for reports. Skip Dependabot-equivalent if applicable.
   - Files: `.circleci/continue-config.yml`
   - Depends on: Task 2.1, Task 0.2
@@ -209,7 +213,7 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Acceptance: `rg -n "GitHub Actions" docs/explanation/repository-settings.md` and deploy docs reflect CircleCI as source of truth.
 
 - [ ] **Task 10.2**: Final GHA workflow purge + IP close
-  - Description: Ensure `.github/workflows` has no CI/CD yml left (except intentionally empty dir or README). Update `PLAN_INDEX.md`; archive IP when Complete.
-  - Files: `.github/workflows/`, `docs/implementationPlans/PLAN_INDEX.md`
+  - Description: Ensure `.github/workflows` has no CI/CD yml left (except intentionally empty dir or README). Set the IP `**Status:**` to Complete and archive the IP.
+  - Files: `.github/workflows/`, `docs/implementationPlans/migrate-cicd-to-circleci.md`
   - Depends on: Task 9.3, Task 10.1, Task 8.2
   - Acceptance: `ls .github/workflows/*.yml` is empty (or only an agreed stub); IP status Complete.

package/src/docs/versioned/next/tasks/model-router-actions.md

@@ -1,5 +1,7 @@
 # modelRouter Actions — Task List
 
+**Status:** Closed (2026-08-20) — IP deferred. Open tasks below will not be executed.
+
 ## Phase 1: Foundation (types + runtime + per-route OpenAPI middleware)
 
 - [ ] **Task 1.1**: Add `zod ^4.3.6` as a **peerDependency** of `@terreno/api` (also pin `^4.3.6` in `devDependencies` so the package compiles/tests on its own) and `@asteasolutions/zod-to-openapi ^8.5.0` as a regular `dependency` (it bundles its own usage). Use Bun catalog for Zod if a catalog version exists.