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.

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.

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.

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.

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.

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.

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."

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.

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.

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).

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.

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/.