@terreno/mcp 57.2.0 → 57.4.0

package/dist/docs/versioned/next/explanation/modular-api-design.md

@@ -158,6 +158,14 @@ This would be nearly impossible with `setupServer()` because installing an app r
 
 With TerrenoApp, an "app" is just a function that receives the `TerrenoApp` instance and calls its methods.
 
+#### 6. One collection catalog for surfaces
+
+`modelRouter` registers each collection once in an in-memory **collection catalog** keyed by route path (for example `/todos`). The record holds the Mongoose model, `ModelRouterOptions`, and which surfaces are active (`mcp`, `realtime`, `sync`). TerrenoApp option enrichment calls `replaceCollectionOptions` once per path after RBAC injects `accessControl`.
+
+MCP, realtime, and sync read **views** of that catalog — they do not keep separate option arrays. `registerMCPModel`, `registerRealtime`, `registerSync`, and the `update*RegistryOptions` helpers remain as wrappers for tests and legacy callers. `clearMCPRegistry`, `clearRealtimeRegistry`, and `clearSyncRegistry` clear the **whole** catalog so tests cannot leave a stale MCP entry after a sync-only clear.
+
+Custom MCP tools stay on a separate list; they are not collections. Sync schema validation and index enqueue still run when a collection first opts into `sync`.
+
 ## Design Principles
 
 ### 1. Explicit over Implicit

package/dist/docs/versioned/next/explanation/organizations.md

@@ -0,0 +1,88 @@
+# How organization tenancy works
+
+Terreno treats organizations as an optional framework primitive. Existing
+single-tenant apps do not pay a migration or authorization cost; multi-tenant
+apps opt in at the access, application, model, and admin layers. New apps
+generated by `create-terreno-app` opt in by default.
+
+## Identity and authorization layers
+
+Platform and tenant authority are separate:
+
+| Authority | Storage | Scope |
+| --- | --- | --- |
+| `superadmin` | `User.roles` | Every framework permission |
+| `operator` | `User.roles` | Organization directory and every organization |
+| `org-admin` | `Membership.roleName` | One organization |
+| `member` | `Membership.roleName` | One organization; app permissions decide actions |
+
+`user.admin` does not imply operator access. `org-admin` is deliberately not a
+global RBAC role: putting it on `User.roles` grants nothing. During an
+organization request, `createAccess({organizations: true})` adds the current
+active Membership grants to the normal role permissions.
+
+## Request context
+
+Tenant routes resolve `X-Organization-Id` after authentication. An operator or
+superadmin may enter any organization but must choose one. An org-admin with
+exactly one administered organization may omit the header; Terreno infers it.
+Ambiguous or unauthorized context fails before model queries run.
+
+The resolved organization and membership are stored in AsyncLocalStorage as
+well as `req.organization` / `req.membership`. This lets `OrgQueryFilter` add
+the server-owned organization id without trusting a client query parameter.
+
+## Isolation boundaries
+
+Tenant isolation uses multiple checks rather than one convention:
+
+1. `orgContextMiddleware({required: true})` rejects missing or unauthorized context.
+2. `OrgQueryFilter` ANDs the selected organization into list and search queries.
+3. `Permissions.IsOrganizationMember` rejects cross-org object reads and writes.
+4. Create hooks overwrite client-supplied organization ids.
+5. `orgScopedPlugin` rejects any post-create change to `organizationId` (REST, admin, sync, direct save).
+6. Sync scopes resolve active Membership rows and partition streams by organization.
+
+`AdminApp({organizations: true})` applies these boundaries automatically to
+admin models whose schema contains `organizationId`. Models without that path
+remain platform-scoped.
+
+## Disabled organizations
+
+When `Organization.disabled` is `true`, tenant context and membership mutations
+stop, but operators can still manage the organization record itself:
+
+| Surface | Disabled org behavior |
+| --- | --- |
+| `orgContextMiddleware` / inferred org context | 403 `Organization is disabled` |
+| `GET /orgs/mine` | Disabled orgs omitted from the switcher list |
+| `GET /orgs` (operator directory) | Disabled orgs still listed |
+| `GET` / `PATCH /orgs/:id` | Allowed (operators use `PATCH` with `disabled: false` to re-enable) |
+| `POST` / `PATCH` / `DELETE /orgs/:id/members` | 403 while disabled |
+| Soft-deleted orgs | Still 404 everywhere |
+
+Disabling or deleting an organization suspends its memberships. Re-enabling does
+not automatically reactivate them.
+
+## Why organizations are optional
+
+Automatically registering routes, roles, or Mongoose models would change
+existing apps merely because they upgraded `@terreno/api`. Instead:
+
+- `createAccess` omits Membership grants and the `operator` seed unless
+  `organizations: true`;
+- `TerrenoApp` does not mount `/orgs` unless organizations are enabled;
+- `AdminApp` does not scope models unless organizations are enabled;
+- Organization and Membership Mongoose models register lazily on first use.
+  Apps add fields to `Organization.settings` with `createOrganizationSettingsSchema`
+  and `registerOrganizationSettings`, not by replacing the Organization model.
+
+This keeps upgrades backward compatible while letting bootstrap generate
+multi-tenant-ready apps.
+
+## Related
+
+- [Add organizations](../how-to/add-organizations.md)
+- [API reference](../reference/api.md#organizations)
+- [Admin backend reference](../reference/admin-backend.md#organization-scoping)
+- [Admin frontend reference](../reference/admin-frontend.md#orgdirectoryscreen)

package/dist/docs/versioned/next/explanation/planning-plugins.md

@@ -0,0 +1,114 @@
+# Planning plugins
+
+Terreno ships its agentic workflows as **two host plugins**. They divide along one line:
+the lifecycle plugin knows *how to build one approved thing correctly*, and the scan
+plugin knows *what is worth building next and whether it worked*.
+
+```text
+terreno-scan                            terreno (lifecycle)
+------------                            -------------------
+Aim     charter a measurable goal
+Sweep   shard + map the repository
+Sift    reduce to verified findings
+Plot    slice findings into briefs ───►  Grow    shape IP + tasks
+                                         Pick ⇄ Roast  build and prove
+                                         Brew    submit the PR
+                                         Taste   react to CI and review
+Track   re-measure, close findings  ◄───  (merged)
+```
+
+A scan never edits product code. The lifecycle never decides what the repository should
+become. Every slice crosses that boundary exactly once, as an approved IP and task list.
+
+## terreno (lifecycle plugin)
+
+Five bounded transitions plus three outer loops. Canonical source:
+`plugins/terreno-planning/`; Claude Code consumes the generated `plugins/terreno-claude/`.
+
+| Stage | Owns | PASS next |
+| --- | --- | --- |
+| Grow | Research, grilling, approved IP and dependency-aware task list, criterion → verification map | Pick |
+| Pick | Implement one task, then Roast it, then take the next until the list is done | Roast, or Brew when done |
+| Roast | Independently prove the current task against its criteria | Pick if tasks remain, else Brew |
+| Brew | Final checks, commit, push, PR, evidence, CI trigger, wait for review bots | Taste |
+| Taste | One reaction to the current head: bots, CI on every host, conflicts, comments | null or fresh Taste |
+
+| Outer loop | Walks |
+| --- | --- |
+| `pick-roast-loop` | An approved plan through every Pick/Roast retry, one ledger, stop only at completion or a genuine human gate |
+| `planning-loop` | Grow/Pick/Brew/Taste, restrictable with `phases=` |
+| `taste-sweep` | Every open PR of yours that is conflicting or failing, until each is mergeable |
+
+Full contract: [lifecycle plugin reference](../reference/lifecycle-plugin.md) and
+[loop engineering](loop-engineering.md).
+
+## terreno-scan (scan plugin)
+
+Five bounded transitions plus two outer loops. Canonical source: `plugins/terreno-scan/`;
+Claude Code consumes the generated `plugins/terreno-scan-claude/`. It depends on the
+lifecycle plugin — Plot hands every slice to Grow.
+
+| Stage | Owns | PASS next |
+| --- | --- | --- |
+| Aim | Charter: metric with a command, measured baseline, dry-run detection rules, exclusions, validity rule, severity rubric, slice policy, review routing, budget | Sweep |
+| Sweep | Run the rules, shard hits deterministically, map fresh workers into candidate findings | Sift |
+| Sift | Dedupe, adversarially verify, drop what does not reproduce, rank, write the findings report | Plot, or Track when dry |
+| Plot | Slice findings into PR-sized units with standalone Grow briefs | Track, handing off to Grow |
+| Track | Re-measure the metric, close or reopen findings with evidence, record the round, choose the next move | Plot, Sweep, or null |
+
+| Outer loop | Walks |
+| --- | --- |
+| `campaign` | Bounded rounds: Aim → Sweep → Sift → Plot → lifecycle → Track. Stops at every gate. |
+| `loop` | Resident session: the same rounds, plus a heartbeat over open campaign PRs — route, answer review through Taste, fix red CI, Track merges — refilling work up to `wipLimit`. |
+
+Full contract: [scan plugin reference](../reference/scan-plugin.md).
+
+## Which one to invoke
+
+| Situation | Start with |
+| --- | --- |
+| You know what to build | `1-grow` |
+| You have an approved plan and want it built | `pick-roast-loop` |
+| A PR of yours is red or conflicting | `5-taste`, or `taste-sweep` for all of them |
+| You know the outcome you want, not the work | `scan 1-aim` |
+| You want that outcome pursued unattended | `scan loop` |
+
+## What each plugin persists
+
+| Artifact | Owner | Committed |
+| --- | --- | --- |
+| IP and task list | Grow | yes |
+| Execution state (`.terreno/pipeline/<slug>.json`) | Lifecycle outer loops | no |
+| Charter (`docs/scans/<goal>/charter.md`) | Aim | yes |
+| Findings report (`docs/scans/<goal>/round-<n>-findings.md`) | Sift | yes |
+| Campaign state (`.terreno/scan/<goal>.json`) | Scan outer loops | no |
+
+Both plugins emit the same shaped result — `v: 2`, `status` of `PASS` / `FAIL` /
+`BLOCKED` / `PENDING`, a `next`, and a concrete `action` — in a collapsed details block,
+with `status` / `next` / `action` as the visible lines. Neither persists
+chain-of-thought.
+
+## Why the split
+
+Three properties fall out of keeping discovery and delivery in separate plugins:
+
+- **A finding must earn its slice.** Sift drops anything that cannot be tied to the
+  goal metric, so the lifecycle only ever receives work with a stated payoff.
+- **Delivery rules stay in one place.** Review response, CI waiting, the pre-push gate,
+  and documentation obligations live in the lifecycle, so a scan cannot invent a
+  shortcut around them.
+- **Progress is measured, not asserted.** Track re-runs the metric command after the
+  work merges, so "we improved it" is always a number with its command output.
+
+## Hosts
+
+| Host | Lifecycle | Scan |
+| --- | --- | --- |
+| Cursor | `terreno-planning`, `/terreno-1-grow` | `terreno-scan`, `/terreno-scan-1-aim` |
+| Codex | `terreno-planning`, `$terreno-1-grow` | `terreno-scan`, `$terreno-scan-1-aim` |
+| Claude Code | `terreno`, `/terreno:1-grow` | `terreno-scan`, `/terreno-scan:1-aim` |
+
+Install both from the marketplaces described in
+[install agent skills](../how-to/install-agent-skills.md). Claude Code resolves a plugin
+skill's command from its frontmatter `name`, which is why the two `*-claude/` trees are
+generated with shortened names by `bun run skills:sync`.

package/dist/docs/versioned/next/explanation/positioning.md

@@ -103,8 +103,8 @@ your codebase is the 20% that is unique to your product.
 
 The analogy earns two honest caveats. First, Terreno targets a document store
 (MongoDB via Mongoose), not a relational ORM, and it has no migrations framework.
-Second, it is younger — several Django/Rails staples (background jobs,
-server-side rendering, role-based access control) are not shipped yet. The
+Second, it is younger — several Django/Rails staples (server-side rendering,
+role-based access control) are not shipped yet. The
 comparison table below is deliberately straight about where the analogy holds and
 where it does not; being honest about the gaps is what makes the analogy credible
 rather than marketing.
@@ -125,8 +125,8 @@ shipped" row links the implementation plan or roadmap item that tracks it.
 | Auth + permissions | Better Auth (`api/src/betterAuthApp.ts`) + `Permissions` (`api/src/permissions.ts`) | Fine-grained RBAC is in progress ([`rbac-permissions`](../implementationPlans/rbac-permissions.md)) |
 | Templates / views | `@terreno/ui` components — one universal codebase for iOS, Android, and web | Server-side rendering for web is not shipped yet ([`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md)) |
 | `manage.py` / generators | MCP server tools — the *tool* layer (`mcp-server/src/tools.ts`) + the `/terreno-*` SDLC pipeline — the *process* layer (`plugins/terreno-planning/skills/`) | Agent-driven rather than CLI-driven; the pipeline is not yet packaged for consumer apps ([`agentic-sdlc-plugin`](../implementationPlans/agentic-sdlc-plugin.md) Task 2.5) |
-| Celery / ActiveJob (background jobs) | Not shipped | On the [roadmap](../../ROADMAP.md) |
-| Migrations | No migrations framework | Schema evolution is convention plus the `mongoose-schema-safety` skill (`.claude/skills/mongoose-schema-safety/`) |
+| Celery / ActiveJob (background jobs) | `@terreno/jobs` `JobsApp` (`jobs/`) | [How-to](../how-to/background-jobs.md), [reference](../reference/jobs.md); optional GCP Cloud Tasks and Vercel Queues runners |
+| Migrations | No migrations framework | Schema evolution is convention plus the published `mongoose-schema-safety` skill |
 
 ## Language rules
 

package/dist/docs/versioned/next/explanation/repository-settings.md

@@ -31,18 +31,31 @@ descriptions):
 **Path:** Settings → Branches → Branch protection rules → `master`
 
 - Require a pull request before merging
-- Require status checks to pass (include Repository policies, package CI, and
-  Rulesync Check jobs relevant to the change)
+- Require status checks to pass (include CircleCI `repo-policies`, package CI,
+  and Rulesync Check jobs relevant to the change — see the check name map in
+  [how-to/circleci.md](../how-to/circleci.md))
 - Require branches to be up to date before merging
 - Do not allow bypassing the above settings
 
-### CircleCI dual-run (in progress)
+### CircleCI checks
 
-Package CI / policy / Playwright twins live under `.circleci/` (see
-[how-to/circleci.md](../how-to/circleci.md)). **Keep requiring the existing GitHub
-Actions check names** until a twin is trusted; then add the CircleCI job name and
-remove the GHA workflow. Do not require CircleCI deploy jobs yet (deploys not
-ported).
+Package CI, policy, Playwright, Maestro web, architectural review, deploy, and
+release workflows run under `.circleci/` (see
+[how-to/circleci.md](../how-to/circleci.md)). Require the path-filtered CircleCI
+check names. Remove required GitHub Action checks for workflow files whose
+trigger is `on: []`; those checks cannot report anymore. Do not require the
+config-only `circleci-config` workflow. Keep Cursor Approval / Security / Bugbot
+as GitHub App checks; they are not CircleCI jobs.
+
+## GitHub Environments (GCP preview)
+
+**Path:** Settings → Environments
+
+Same-repo PR jobs in `cd.yml` (`Terraform preview`, `Tasks deploy (preview)`,
+`Backend deploy (preview)`) skip when `head.repo.full_name != github.repository`.
+Also restrict the `gcp-cd-preview` environment (create it on first deploy if missing) with a
+**deployment branch policy** or **required reviewers** so a fork that edits
+`cd.yml` cannot mint a prod WIF token.
 
 ## Merge settings
 

package/dist/docs/versioned/next/explanation/roadmap-process.md

@@ -10,6 +10,10 @@ both.
 - **IPs** — approved design docs before substantial cross-package work
 
 See also [CONTRIBUTING.md](https://github.com/FlourishHealth/terreno/blob/master/CONTRIBUTING.md) for the contributor intake flow.
+Issue-sized work that is not a public roadmap item uses
+[GitHub issue lifecycle](../how-to/github-issue-lifecycle.md)
+(`create-github-issue` → `work-github-issues`, or `status:ready-for-dev` →
+`implement-ready-for-dev`) instead of an IP.
 
 ## How work flows (IP ↔ roadmap)
 
@@ -130,7 +134,7 @@ When an answer repeats, maintainers turn it into a how-to doc via PR.
 MCP server setup, Cursor/Claude skills, and agent-driven workflows.
 
 - MCP package: [`mcp-server/`](https://github.com/FlourishHealth/terreno/tree/master/mcp-server) and hosted `terreno-mcp`.
-- Agent skills: [`.rulesync/skills/`](https://github.com/FlourishHealth/terreno/tree/master/.rulesync/skills) (mirrored to `.cursor/`, `.claude/`, etc.).
+- Agent skills: [`.rulesync/skills/`](https://github.com/FlourishHealth/terreno/tree/master/.rulesync/skills) (mirrored into editor-specific copies).
 - Terreno planning plugin: [`plugins/terreno-planning/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-planning).
 
 General feature ideas → **Ideas**. Doc typos → **Docs feedback** or a docs PR.
@@ -166,44 +170,78 @@ Every docs page also has a **Discuss this page** link in the footer.
 
 ### Project board
 
-Create one GitHub Project named **Terreno Roadmap** (repo-level is fine; org-level also
-works). Link it to `FlourishHealth/terreno`.
+The board must be an **organization** project under `FlourishHealth`. The generator queries
+`organization(login:).projectV2`, so a repo-level project returns no data.
+
+`bun run roadmap:sync` creates the project, its fields, and its items from repo data — no
+hand-clicking. It needs a token with `project` scope:
+
+```bash
+gh auth refresh -s project                              # one time
+GITHUB_TOKEN=$(gh auth token) bun run roadmap:sync --dry-run   # print the plan
+GITHUB_TOKEN=$(gh auth token) bun run roadmap:sync             # apply
+GITHUB_TOKEN=$(gh auth token) bun run roadmap:sync --check     # exit 1 on drift (CI)
+```
+
+What it reads, and therefore what you edit to change the board:
+
+| Source | Drives |
+| ------ | ------ |
+| [`.github/roadmap-fields.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/roadmap-fields.yml) | `Status`, `Target`, `Impact` options |
+| `area:*` labels in [`.github/labels.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/labels.yml) | `Area` options |
+| [`roadmap-seed-issues.md`](roadmap-seed-issues.md) | one item per roadmap entry, plus its field values and issue labels |
 
 **Fields** (single-select unless noted):
 
 | Field | Type | Options |
 | ----- | ---- | ------- |
-| Status | Single select | `Inbox`, `Shaping`, `Planned`, `In progress`, `In review`, `Shipped`, `Declined` |
-| Area | Single select | `api`, `ui`, `syncdb`, `auth`, `admin`, `ai`, `mcp`, `docs`, `deploy`, `examples`, `dx` |
-| Target | Single select | `0.28`, `0.29`, `Next`, `Future` (add version labels as releases approach) |
+| Status | Single select | from `roadmap-fields.yml` `status` |
+| Area | Single select | from the `area:*` labels |
+| Target | Single select | from `roadmap-fields.yml` `target` |
 | IP | Text | Slug e.g. `web-ssr-and-admin-spa` (empty when no IP yet) |
-| Impact | Single select | `Breaking`, `Feature`, `Improvement`, `Fix` |
+| Impact | Single select | from `roadmap-fields.yml` `impact` |
 | Community interest | Number | 👍 count — refresh manually on triage |
 
-**Views**
+`Target` answers *which release*, never *what state* — `Status` carries state. Already-shipped
+work uses `Target = Released` so it groups at the bottom of `ROADMAP.md` instead of inflating
+an upcoming version. `TARGET_ORDER` in
+[`scripts/generate-roadmap/lib.ts`](https://github.com/FlourishHealth/terreno/blob/master/scripts/generate-roadmap/lib.ts)
+must stay deep-equal to the yaml list; a test enforces it.
+
+**Views** — still UI-only; there is no GitHub API for creating project views.
 
 1. **Roadmap** — Board layout, group by `Status`, filter `Status != Declined` (default public view).
 2. **By area** — Table, group by `Area`.
 3. **Next release** — Table, filter `Target = Next` (update filter when cutting a release).
 4. **Needs shaping** — Table, filter `Status = Shaping`.
 
-**CLI (partial support)**
-
-```bash
-gh project list --owner FlourishHealth --limit 20
-gh project link <project-number> --owner FlourishHealth --repo FlourishHealth/terreno
-```
-
-Field and view creation is **UI-only** today — recreate the tables above in the Project
-settings.
+**What sync will not do:** it never opens a tracking issue for an entry whose `IP` field is
+empty. The repo's process opens the issue when the IP reaches **Approved**, so speculative
+items stay off the public board. Pass `--create-missing-issues` once an IP lands to open the
+issue and place it in one step.
 
-**Backfill:** paste tracking issues from [`roadmap-seed-issues.md`](roadmap-seed-issues.md)
-when each IP reaches **Approved**.
+Adding new options to an existing single-select field rewrites that field's whole option list
+(GitHub has no add-one-option mutation). The planner always carries the existing option names
+through the rewrite, so no card loses its current value — but review the `--dry-run` output
+before applying a rewrite.
 
 ### Labels
 
 [`.github/labels.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/labels.yml) is the source of truth.
 
+Every issue on the board carries the **`roadmap`** label. That label — not a title prefix — is
+how roadmap work is filtered:
+
+```bash
+gh issue list --repo FlourishHealth/terreno --label roadmap --state all
+```
+
+`roadmap:sync` adds it to every issue it declares, so seed entries do not repeat it on their
+`**Labels:**` line. Tracking issues used to be titled `[Roadmap] <outcome>`; titles are now
+just the outcome, and `displayTitle` in
+[`scripts/generate-roadmap/lib.ts`](https://github.com/FlourishHealth/terreno/blob/master/scripts/generate-roadmap/lib.ts)
+strips the legacy prefix wherever it survives.
+
 Apply or update labels with `gh` authenticated as a maintainer:
 
 ```bash
@@ -240,7 +278,9 @@ Five agent skills cover the recurring roadmap work. Each one researches, propose
 **stops for a maintainer to approve** before touching GitHub — roadmap decisions are the most
 human part of the process, so none of them mutate state on their own. All five are
 `disable-model-invocation`, meaning an agent will not start them on its own initiative;
-you invoke them explicitly.
+you invoke them explicitly. Unattended implementation of a roastable issue is
+[`implement-ready-for-dev`](../how-to/github-issue-lifecycle.md#unattended-pickup),
+not a sixth roadmap skill.
 
 | Skill | Use it when |
 | ----- | ----------- |
@@ -248,6 +288,15 @@ you invoke them explicitly.
 | `roadmap-promote` | Maintainers accepted an Ideas or RFC discussion and it needs a tracked issue that links back to the thread |
 | `roadmap-item` | An approved IP needs its public tracking issue, or an existing entry's scope changed |
 | `roadmap-review` | Recurring hygiene: status drift, stale items, untriaged backlog, promotion candidates, then regenerate `ROADMAP.md` |
+
+`roadmap-item` and `roadmap-promote` no longer touch the board with `gh project`. They add or
+edit an entry in [`roadmap-seed-issues.md`](roadmap-seed-issues.md) and run `roadmap:sync`,
+which opens the issue, applies the labels, adds the item, and sets every field in one
+idempotent pass. Board items added by hand show up as `--check` drift; apply does not delete
+them. A dragged `Status` that is ahead of the seed is reported the same way and is not reset.
+
+`roadmap-review` starts from `bun run roadmap:reconcile`, which mechanically answers most
+hygiene questions and leaves a `Needs a human` list that is exactly the review's agenda.
 | `roadmap-frontier` | A destination is too large or uncertain for one IP/context and needs a map, a small unblocked frontier, and repeated Grow → Taste delivery loops |
 
 ### Huge features: frontier maps
@@ -270,11 +319,12 @@ per-agent mirrors.
 The skills do not carry a copy of the taxonomy. They call:
 
 ```bash
-bun run roadmap:check --labels "area:api,type:feature" --status Planned --target Next --impact Feature --area api
+bun run roadmap:check --on-board --labels "roadmap,area:api,type:feature" --status Planned --target Next --impact Feature --area api
 ```
 
 Run it with no arguments to print every valid label and field option. It enforces exactly one
-`area:*` and one `type:*` label, rejects labels absent from
+`area:*` and one `type:*` label, requires the `roadmap` label under `--on-board` (omit the
+flag when triaging an issue that is not headed for the board), rejects labels absent from
 [`.github/labels.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/labels.yml),
 rejects Project values absent from
 [`.github/roadmap-fields.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/roadmap-fields.yml),
@@ -326,8 +376,71 @@ do not claim completion until done.
 
 | Workflow | Trigger | Purpose |
 | -------- | ------- | ------- |
-| [`.github/workflows/triage.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown |
-| [`.github/workflows/roadmap-generate.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | Regenerate `ROADMAP.md` from the Project board |
+| [`.github/workflows/triage.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown + `type:*` from Kind when present |
+| [`.github/workflows/roadmap-generate.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board |
+| [`.github/workflows/roadmap-sync.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/workflows/roadmap-sync.yml) | Taxonomy files change on `master` + manual | Apply labels and reconcile the board's fields and items |
+| [`.github/workflows/roadmap-reconcile.yml`](https://github.com/FlourishHealth/terreno/blob/master/.github/workflows/roadmap-reconcile.yml) | IP or task files change on `master` + manual | Advance status from IP headers, push to the board, regenerate `ROADMAP.md` |
+
+All three share the `roadmap` concurrency group. They write the same board, and interleaving
+them produces confusing partial states. After the group lock is acquired, each job refreshes
+to the latest branch HEAD so a queued `roadmap-sync` cannot overwrite statuses that
+`roadmap-reconcile` already advanced. `roadmap-reconcile` also fails fast when
+`TERRENO_PROJECT_NUMBER` is unset, so it never mutates the seed or board before generate
+can run. `roadmap:sync` pages organization projects until it finds **Terreno Roadmap**, so
+it will not create a second project if the org has more than 50 boards.
+
+The full loop, each arrow with exactly one writer:
+
+```
+docs/implementationPlans/*.md ──roadmap:reconcile──▶ roadmap-seed-issues.md
+docs/tasks/*.md                    (Status only)              │
+                                                         roadmap:sync
+                                                              ▼
+                                                        Project board
+                                                              │
+                                                      roadmap:generate
+                                                              ▼
+                                                          ROADMAP.md
+```
+
+Who owns what:
+
+| Artifact | Owns |
+| -------- | ---- |
+| IP header `**Status:**` | Where the work is in its lifecycle |
+| `roadmap-seed-issues.md` | Which items exist, plus Area / Target / Impact / labels / summary |
+| Project board | Live state a maintainer drags, and `Community interest` |
+| `ROADMAP.md` | Nothing — fully generated |
+
+`roadmap:sync` owns the board's *shape*: which fields exist, which options they allow, which
+issues are on it, and Area / Target / Impact / IP. It writes `Status` only onto a new card or
+when the seed is strictly ahead (or Declined). A dragged Status that is ahead of the seed is
+reported by `--check` and is never overwritten. Cards that are not in
+[`roadmap-seed-issues.md`](roadmap-seed-issues.md) are also `--check` failures; apply does
+not delete them. Maintainers own the board's *state* and `Community interest`.
+
+**Status automation is monotonic.** `roadmap:reconcile --fix` advances status and applies
+supersessions, but never walks a status backwards and never revives declined work. IP headers
+go stale far more often than boards do — several plans still read `Draft` for work that
+shipped — so a backwards move is reported as a stale header for a human to resolve.
+
+| IP `**Status:**` | Board `Status` |
+| ---------------- | -------------- |
+| `Draft` (also `Shaped`) | `Shaping` |
+| `Approved` | `Planned` |
+| `In progress` | `In progress` |
+| `Complete` (also `Implemented`) | `Shipped` |
+| `Deferred`, or any `**Superseded by:**` | `Declined` |
+
+Only the leading phrase matters, so `Approved — decisions recorded (2026-07-29)` maps cleanly.
+A status the table cannot map is reported rather than guessed at.
+
+Two headers keep a plan out of that accounting:
+
+| Header | Effect |
+| ------ | ------ |
+| IP `**Parent IP:**` | The plan rides on another plan's roadmap entry, like a `-research` or `-design` sub-document, and needs no entry of its own. Empty or italic `*(optional)*` placeholders do not count — omit the header unless it names a real parent |
+| Task file `**Status:** Closed` | The checklist is history — the IP finished by another route, so its unchecked boxes are not outstanding work and never contradict a `Shipped` status |
 
 Triage resolves the `area:*` label with
 [`scripts/issueAreaLabels.ts`](https://github.com/FlourishHealth/terreno/blob/master/scripts/issueAreaLabels.ts),