suaveplan/openspec/archive/2026-04-25-folder-reorg-by-domain/tasks.md

# Tasks: folder-reorg-by-domain

**Change ID**: folder-reorg-by-domain
**Scope**: Monorepo-wide structural change

---

## 1. Pre-flight

- [ ] Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each).
- [ ] Confirm all currently-published packages on Verdaccio have green pre-publish gates (snapshot the list — `bun scripts/list-published.ts` if available, otherwise grep `npmjs.fq.io`).
- [ ] Tag the pre-migration state: `git tag pre-folder-reorg`.

---

## 2. Assignment manifest

- [ ] Create `scripts/folder-reorg/assignment.yml` — machine-readable copy of the plugin → package table from `proposal.md`. Format: `<plugin-name>: [<pkg1>, <pkg2>, ...]`.
- [ ] Add a sanity check: every package referenced in `assignment.yml` exists either on disk in genesis OR in `MIGRATION.md` (future) OR in the universe spec (future). Fail fast if any package is unaccounted for.
- [ ] Add a uniqueness check: every package appears in exactly one plugin.

---

## 3. Migration script

- [ ] Write `scripts/folder-reorg/migrate-folders.ts`:
  - Reads `assignment.yml`.
  - For each package currently on disk under `universal/<domain>/<pkg>/`, runs `git mv universal/<domain>/<pkg>/ packages/<plugin>/<pkg>/`.
  - Skips packages listed in `assignment.yml` but not yet on disk (future packages from MIGRATION.md / universe spec).
  - Logs every move; outputs a summary.
- [ ] Dry-run mode (`--dry-run`) prints planned moves without executing.

---

## 4. Execute migration

- [ ] Run `bun scripts/folder-reorg/migrate-folders.ts --dry-run`. Review output.
- [ ] Run `bun scripts/folder-reorg/migrate-folders.ts`. Single commit: `chore(structure): move all packages to domain-first layout`.
- [ ] Verify `packages/` contains exactly the plugin folders from `proposal.md`.
- [ ] Verify legacy folders (`universal/`, etc.) are empty or removed.

---

## 5. Workspace + tooling updates

- [ ] Root `package.json` — `workspaces` glob: ensure `packages/*/*` covers the new layout. Remove any tier-specific globs.
- [ ] Root `tsconfig.json` — regenerate `paths` mapping if it's not glob-based.
- [ ] `turbo.json` — no change expected (uses workspace inheritance); verify by running `bunx turbo run build --dry-run`.
- [ ] Run nuclear clean install: `rm -rf node_modules bun.lockb && find . -type d -name "node_modules" -exec rm -rf {} + && bun install --force`.
- [ ] Run full lint+typecheck+test sweep: `bunx turbo lint typecheck test`. All packages must stay green — folder move should be transparent to package contents.

---

## 6. Documentation updates

- [ ] `CLAUDE.md` — replace every `universal/<domain>/<pkg>` path reference with `packages/<plugin>/<pkg>`. Update the Packages section to describe the new layout. Update Quick Commands examples.
- [ ] `openspec/AGENTS.md` — replace every `universal/<domain>/<pkg>` and `packages/universal/<pkg>` path reference. Update file-size, banned-pattern, and missing-`.md` scan commands.
- [ ] `openspec/project.md` — update if it references folder layout.
- [ ] In-flight OpenSpec changes (`enterprise-*`) — update only the `Target path:` line in each `proposal.md` if the change is not yet archived. Already-archived changes stay frozen.

---

## 7. Delete FOLDERS.yml

- [ ] `git rm FOLDERS.yml`.
- [ ] Add a one-line note to `CLAUDE.md` Packages section: "Folder layout is domain-first; see `MANIFEST.md` for the per-tier overlay view."

---

## 8. Retire @suaveplan/overview

- [ ] `git rm -r packages/data/overview/` (it has been reassigned to foundation but is being retired — confirm by re-reading `proposal.md` and removing it from the foundation row in `assignment.yml` before running the migration script).
- [ ] Unpublish from Verdaccio: `bun scripts/unpublish.ts --package @suaveplan/overview` (or manual `npm unpublish @suaveplan/overview --registry https://npmjs.fq.io --force`).
- [ ] Search the rest of genesis for any `import ... from '@suaveplan/overview'` or `"@suaveplan/overview"` dependency entries; remove them. Expected: zero matches (the package was a leaf with no in-repo consumers).
- [ ] Remove the `enterprise-overview` OpenSpec archive line from any index if one exists.

---

## 9. MANIFEST.md generator

- [ ] Write `scripts/generate-manifest.ts`:
  - Walks `packages/<plugin>/<pkg>/package.json` for every package.
  - Emits `MANIFEST.md` at repo root with sections:
    1. **Plugins** — table of `plugin | package count | total deps`.
    2. **Packages** — table of `npm name | plugin | tier (inferred) | version | dep count`.
    3. **Tier overlay** — packages grouped by inferred tier (universal / browser / react / r3f / server / python). Inference rules:
       - `python` if `package.json` has `"python"` field or path contains `python-`.
       - `r3f` if `peerDependencies` contains `@react-three/fiber`.
       - `react` else if `peerDependencies` contains `react`.
       - `browser` else if `package.json` has `"browser"` field or `engines` excludes node.
       - `server` else if `bin` is set OR depends on `bun:sqlite` / `node:fs` / similar.
       - `universal` otherwise.
    4. **Dependency graph** — DOT block listing `<pkgA> -> <pkgB>` for every workspace dep edge.
  - `--check` mode regenerates in-memory and diffs against on-disk `MANIFEST.md`; exits non-zero on diff.
- [ ] Co-locate `scripts/generate-manifest.md` documentation per genesis docs rules.
- [ ] First-time generation: `bun scripts/generate-manifest.ts > MANIFEST.md`. Commit.

---

## 10. CI gate

- [ ] Add `bun scripts/generate-manifest.ts --check` as a CI step in the root pipeline.
- [ ] Add the same as a `pre-commit` hook entry (optional — if hooks are configured).

---

## 11. Verify

- [ ] `bunx turbo lint typecheck test` — all green.
- [ ] `bunx turbo test:coverage --filter=@suaveplan/*` — every package still at 100%.
- [ ] `bunx turbo build` — every package still builds.
- [ ] `bun scripts/generate-manifest.ts --check` — clean.
- [ ] `git status` — only intentional changes (folder moves, doc updates, MANIFEST.md, removed FOLDERS.yml, removed overview package).
- [ ] Spot-check three packages from different plugins (e.g. `packages/core/error/`, `packages/gaming-engine/ecs/`, `packages/drive/drive-webrtc/`) — `package.json` valid, `vitest.config.ts` resolves, tests pass.

---

## 12. OpenSpec archival

- [ ] Fold `specs/monorepo-structure/spec.md` (this change's spec delta) into `openspec/specs/monorepo-structure/spec.md`.
- [ ] Move `openspec/changes/folder-reorg-by-domain/` → `openspec/archive/2026-04-25-folder-reorg-by-domain/`.