Initial Commit

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

@@ -0,0 +1,121 @@
+# 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/`.