## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Pre-flight

- [ ] 1.1 Create branch `chore/restructure-packages-by-category` off `genesis`.
- [ ] 1.2 Run `git worktree list` and confirm every worktree is clean (`git status` in each). Abort and reconcile if anything is dirty.
- [ ] 1.3 Snapshot current `MANIFEST.md` as `MANIFEST.before.md` (not committed; used for post-move diff).
- [ ] 1.4 Snapshot current `bunx turbo ls --json` output for the same purpose.
- [ ] 1.5 Audit `packages/platform/` and decide a target category for every sub-package (record decisions inline in this tasks file under §3).

## 2. Authoritative assignment file

- [ ] 2.1 Update `scripts/folder-reorg/assignment.yml` so each plugin entry includes a `category:` field with one of the 18 canonical names: `foundation`, `persistence`, `network`, `communication`, `api`, `auth`, `security`, `monitor`, `media`, `react`, `r3f`, `i18n`, `geo`, `finance`, `commerce`, `testing`, `tooling`, `games`.
- [ ] 2.2 Commit the YAML update on the restructure branch *before* doing any `git mv`, so the rename commit and the assignment metadata stay in lockstep on review.

## 3. Decompose `packages/platform/`

- [ ] 3.1 List every sub-package under `packages/platform/` (`ls packages/platform`).
- [ ] 3.2 For each, record `<pkg> → <category>` in this checklist (e.g. `webhook-client → communication`). Use only the 18 canonical categories.
- [ ] 3.3 Confirm no platform sub-package needs to be split across multiple categories. If one does, raise it as an open question on the OpenSpec proposal before proceeding.

## 4. Move plugin folders with `git mv` (one commit, one folder at a time)

Run commands from the repo root. Create the category directory just before the first `git mv` into it.

- [ ] 4.1 `foundation/`: `mkdir -p packages/foundation && git mv packages/core packages/foundation/core && git mv packages/data packages/foundation/data && git mv packages/random packages/foundation/random && git mv packages/timing packages/foundation/timing && git mv packages/bitpacker packages/foundation/bitpacker && git mv packages/barcode packages/foundation/barcode && git mv packages/flow packages/foundation/flow`.
- [ ] 4.2 `persistence/`: `mkdir -p packages/persistence && git mv packages/database packages/persistence/database && git mv packages/storage packages/persistence/storage && git mv packages/cache packages/persistence/cache`.
- [ ] 4.3 `network/`: `mkdir -p packages/network-cat && git mv packages/network packages/network-cat/network && git mv packages/drive packages/network-cat/drive && git mv packages/events packages/network-cat/events && mv packages/network-cat packages/network` (use the temp-name swap *only* at the category level to avoid colliding with the existing `packages/network/` plugin folder; the `git mv` of the inner `network` plugin is what Git tracks, the final `mv` of the empty category folder is content-free).
- [ ] 4.4 `communication/`: `mkdir -p packages/communication && git mv packages/messaging packages/communication/messaging && git mv packages/emails packages/communication/emails`.
- [ ] 4.5 `api/`: `mkdir -p packages/api-cat && git mv packages/api packages/api-cat/api && mv packages/api-cat packages/api` (same category/plugin name collision dance as `network`).
- [ ] 4.6 `auth/`: `mkdir -p packages/auth-cat && git mv packages/auth packages/auth-cat/auth && mv packages/auth-cat packages/auth`.
- [ ] 4.7 `security/`: `mkdir -p packages/security-cat && git mv packages/security packages/security-cat/security && git mv packages/crypto packages/security-cat/crypto && mv packages/security-cat packages/security`.
- [ ] 4.8 `monitor/`: `mkdir -p packages/monitor-cat && git mv packages/monitor packages/monitor-cat/monitor && mv packages/monitor-cat packages/monitor`.
- [ ] 4.9 `media/`: `mkdir -p packages/media && git mv packages/audio packages/media/audio && git mv packages/audio-fx packages/media/audio-fx && git mv packages/audio-ir packages/media/audio-ir && git mv packages/image packages/media/image && git mv packages/fonts packages/media/fonts`.
- [ ] 4.10 `react/`: `mkdir -p packages/react-cat && git mv packages/react packages/react-cat/react && git mv packages/forms packages/react-cat/forms && mv packages/react-cat packages/react`.
- [ ] 4.11 `r3f/`: `mkdir -p packages/r3f-cat && git mv packages/r3f packages/r3f-cat/r3f && mv packages/r3f-cat packages/r3f`.
- [ ] 4.12 `i18n/`: `mkdir -p packages/i18n-cat && git mv packages/i18n packages/i18n-cat/i18n && mv packages/i18n-cat packages/i18n`.
- [ ] 4.13 `geo/`: `mkdir -p packages/geo-cat && git mv packages/geo packages/geo-cat/geo && mv packages/geo-cat packages/geo`.
- [ ] 4.14 `finance/`: `mkdir -p packages/finance-cat && git mv packages/finance packages/finance-cat/finance && git mv packages/payment packages/finance-cat/payment && mv packages/finance-cat packages/finance`.
- [ ] 4.15 `commerce/`: `mkdir -p packages/commerce && git mv packages/booking packages/commerce/booking && git mv packages/contacts packages/commerce/contacts`.
- [ ] 4.16 `testing/`: `mkdir -p packages/testing-cat && git mv packages/testing packages/testing-cat/testing && mv packages/testing-cat packages/testing`.
- [ ] 4.17 `tooling/`: `mkdir -p packages/tooling-cat && git mv packages/tooling packages/tooling-cat/tooling && git mv packages/docs packages/tooling-cat/docs && git mv packages/docker packages/tooling-cat/docker && mv packages/tooling-cat packages/tooling`.
- [ ] 4.18 `games/`: `mkdir -p packages/games-cat && git mv packages/games packages/games-cat/games && mv packages/games-cat packages/games`.
- [ ] 4.19 Decompose `packages/platform/` per §3 decisions: one `git mv packages/platform/<pkg> packages/<category>/<plugin>/<pkg>` per sub-package (or to its parent plugin folder if it belongs there). Remove the now-empty `packages/platform/` directory with `rmdir packages/platform`.
- [ ] 4.20 Verify: `find packages -mindepth 1 -maxdepth 1 -type d | sort` returns exactly the 18 canonical category names and nothing else.
- [ ] 4.21 Verify: `find packages -mindepth 3 -maxdepth 3 -name package.json | wc -l` equals the count of `@suaveplan/*` packages from the pre-flight snapshot.

## 5. Update workspace and tooling configuration

- [ ] 5.1 Root `package.json`: change `workspaces` from `["packages/*/*"]` (or whatever the current glob is) to `["packages/*/*/*"]`. Verify no other glob is needed.
- [ ] 5.2 Root `turbo.json`: scan for any hard-coded `packages/<plugin>/...` paths and update to three-level.
- [ ] 5.3 Root `tsconfig*.json`: update any `paths` mappings that reference `packages/<plugin>/<pkg>` to `packages/<category>/<plugin>/<pkg>`.
- [ ] 5.4 `scripts/folder-reorg/generate-manifest.ts`: update path-walking logic to assume three levels under `packages/`; load category list from the YAML constant.
- [ ] 5.5 `scripts/publish.ts`: update any path-resolution code that walks `packages/`.
- [ ] 5.6 `scripts/lint/check-test-runner-imports.ts`: update its `packages/<plugin>/<pkg>` glob to three levels.
- [ ] 5.7 Per-package configs: `rg -n "packages/[a-z][a-z0-9-]+/[a-z][a-z0-9-]+(/|['\")\\\\])" --type-add 'cfg:*.{json,ts,js,mjs,cjs,yml,yaml,toml}' -tcfg` and audit every hit. Update each to the three-level form (or to a category-agnostic resolution if better).
- [ ] 5.8 `biome.json` (and any per-package `biome.json`): update path globs.
- [ ] 5.9 `playwright.config.*` (root and per-package): update path globs.

## 6. Add path-shape CI gate

- [ ] 6.1 Create `scripts/lint/check-package-paths.ts` that walks `packages/`, asserts every `package.json` is at depth 3 segments under `packages/`, and asserts the category segment is in the canonical 18-name list (loaded from `scripts/folder-reorg/assignment.yml`).
- [ ] 6.2 Add it to the root `lint` script and to `turbo.json` `lint` task pipeline.
- [ ] 6.3 Run it locally; confirm it exits zero.

## 7. Regenerate manifest

- [ ] 7.1 Run `bun scripts/folder-reorg/generate-manifest.ts`.
- [ ] 7.2 Diff the new `MANIFEST.md` against `MANIFEST.before.md`: only path strings and the new category column should differ. No package additions, removals, or version changes.
- [ ] 7.3 Stage `MANIFEST.md`.

## 8. Documentation updates

- [ ] 8.1 `CLAUDE.md` "Layout (`packages/<plugin>/<pkg>/`)" section: rewrite the heading to `Layout (packages/<category>/<plugin>/<pkg>/)`, document the 18-category vocabulary, and reference `scripts/folder-reorg/assignment.yml` as the source of truth.
- [ ] 8.2 `STATUS.md`: replace the implicit `unknown/` bucket with category headers; reflect the new paths.
- [ ] 8.3 `PROPOSED_STRUCTURE.md`: add a one-line note at the top — `Status: adopted via openspec/changes/restructure-packages-by-category` — and leave the rationale intact for historical context.
- [ ] 8.4 Spot-check root-level `README.md` for `packages/<plugin>` references; update.
- [ ] 8.5 Do NOT modify any file under `openspec/archive/` even if it quotes old paths.

## 9. Verification gate

- [ ] 9.1 `bun install` at repo root succeeds with no `workspace package not found` errors.
- [ ] 9.2 `bunx turbo ls` lists the same package count as the pre-flight snapshot.
- [ ] 9.3 `bunx turbo lint typecheck` green across the whole monorepo.
- [ ] 9.4 `bunx turbo test` green across the whole monorepo (allow expected DB-integration skips per CLAUDE.md).
- [ ] 9.5 `bun scripts/lint/check-package-paths.ts` exits zero.
- [ ] 9.6 `git log --follow packages/foundation/core/error/src/error.ts` (or another sample file) shows pre-restructure history.
- [ ] 9.7 `git show --stat HEAD` of the restructure commit shows only renames, zero content edits.

## 10. Commit and ship

- [ ] 10.1 Squash all step-4/5/6/7/8 work into one commit:
      `chore(repo): restructure packages under 18 categories`
- [ ] 10.2 Push branch; confirm CI green.
- [ ] 10.3 Open PR to `genesis` with the proposal, design, and tasks linked from the description.
- [ ] 10.4 After merge, fold the spec delta into `openspec/specs/monorepo-layout/spec.md` and archive `openspec/changes/restructure-packages-by-category/` to `openspec/archive/<yyyy-mm-dd>-restructure-packages-by-category/`.