Initial Commit

openspec/changes/restructure-packages-by-category/specs/monorepo-layout/spec.md

@@ -0,0 +1,113 @@
+## ADDED Requirements
+
+### Requirement: Three-Level Package Path Convention
+
+Every workspace package SHALL live at `packages/<category>/<plugin>/<pkg>/`, where `<category>` is one of the 18 canonical category names defined in this spec, `<plugin>` is the suaveplan-skills plugin slug, and `<pkg>` is the package directory whose `package.json` declares `@suaveplan/<pkg>`. No package SHALL exist directly under `packages/<plugin>/<pkg>/` (the legacy two-level layout) or at `packages/<pkg>/`.
+
+#### Scenario: Valid package path
+
+
+- **WHEN** a developer creates `packages/foundation/core/error/` containing a `package.json` with `"name": "@suaveplan/error"`
+- **THEN** the path-shape CI gate accepts it because the depth is exactly 3 segments under `packages/` and `foundation` is a canonical category
+
+
+#### Scenario: Legacy two-level path rejected
+
+- **WHEN** a `package.json` is found at `packages/core/error/package.json` (no category level)
+- **THEN** the path-shape CI gate fails with an error naming the missing category segment and the package
+
+
+#### Scenario: Unknown category rejected
+
+- **WHEN** a `package.json` is found at `packages/misc/core/error/package.json`
+- **THEN** the path-shape CI gate fails because `misc` is not in the canonical 18-category list
+
+### Requirement: Canonical Category Vocabulary
+
+
+The set of allowed `<category>` segment names SHALL be exactly: `foundation`, `persistence`, `network`, `communication`, `api`, `auth`, `security`, `monitor`, `media`, `react`, `r3f`, `i18n`, `geo`, `finance`, `commerce`, `testing`, `tooling`, `games`. Adding, removing, or renaming a category SHALL require a new OpenSpec change that modifies this requirement.
+
+#### Scenario: Lint script enumerates categories
+
+
+- **WHEN** `scripts/folder-reorg/generate-manifest.ts` runs
+- **THEN** it reads the 18 category names from a single source-of-truth constant whose values match this requirement exactly
+
+#### Scenario: New top-level folder under packages/ is rejected
+
+- **WHEN** a developer adds `packages/experiments/foo/bar/` without an OpenSpec change updating this requirement
+- **THEN** the path-shape CI gate fails because `experiments` is not in the canonical list
+
+
+### Requirement: Plugin-to-Category Assignment Is Stable
+
+Each plugin folder SHALL belong to exactly one category. The assignment SHALL be recorded in `scripts/folder-reorg/assignment.yml` and reflected in `MANIFEST.md`. Moving a plugin between categories SHALL require a new OpenSpec change documenting the rationale and the migration steps.
+
+
+#### Scenario: Plugin appears in exactly one category
+
+- **WHEN** the manifest generator walks `packages/`
+- **THEN** it finds the `geo` plugin folder at exactly one path (`packages/geo/geo/`) and no other category contains a folder named `geo`
+
+#### Scenario: Manifest matches filesystem
+
+- **WHEN** `bun scripts/folder-reorg/generate-manifest.ts --check` runs in CI
+
+- **THEN** it exits zero only if every plugin folder on disk matches its `assignment.yml` category entry
+
+### Requirement: Workspace Glob Matches Three-Level Layout
+
+
+The root `package.json` `workspaces` field SHALL include a glob that matches `packages/*/*/*` (three segments) and SHALL NOT include `packages/*/*` (the legacy two-level glob) unless that glob is required for a documented transitional package.
+
+#### Scenario: Bun resolves all packages
+
+- **WHEN** `bun install` runs at the repo root after restructure
+- **THEN** every `@suaveplan/<pkg>` workspace dependency resolves without `workspace package not found` errors
+
+#### Scenario: Turbo discovers all packages
+
+
+- **WHEN** `bunx turbo ls` runs at the repo root
+- **THEN** the package count matches the count of `package.json` files found by `find packages -mindepth 3 -maxdepth 3 -name package.json`
+
+
+### Requirement: Move Preserves Git History
+
+The filesystem reorganisation SHALL use `git mv` (one invocation per plugin folder) so that Git's rename detection links the old and new paths. The reorganisation commit SHALL NOT touch package source code, versions, or exports — it is a pure rename commit.
+
+#### Scenario: git log --follow traces a moved file
+
+- **WHEN** `git log --follow packages/foundation/core/error/src/error.ts` runs after the restructure commit
+- **THEN** the log includes commits made before the restructure that touched `packages/core/error/src/error.ts`
+
+
+#### Scenario: Restructure commit changes no file contents
+
+- **WHEN** `git show --stat <restructure-commit>` is inspected
+- **THEN** every line is a rename (R100 in `git show --raw -M`) and no line shows insertions or deletions outside path changes
+
+### Requirement: No `packages_temp` Swap
+
+
+The restructure SHALL NOT use a temporary sibling directory (e.g. `packages_temp/`) that is later renamed to `packages/`. Such a swap defeats Git rename detection for files whose containing directory is created and destroyed during the operation.
+
+#### Scenario: No transient packages_temp directory in history
+
+
+- **WHEN** `git log --all --diff-filter=A --name-only` is inspected for the restructure branch
+- **THEN** no commit adds a `packages_temp/` path
+
+### Requirement: Documentation Reflects New Layout
+
+`CLAUDE.md`, `MANIFEST.md`, `STATUS.md`, and `scripts/folder-reorg/assignment.yml` SHALL describe the three-level `packages/<category>/<plugin>/<pkg>/` convention and enumerate the 18 canonical categories. Archived OpenSpec change folders SHALL retain their original content; only the live root-level docs are rewritten.
+
+#### Scenario: CLAUDE.md layout section updated
+
+- **WHEN** a reader opens `CLAUDE.md` after the restructure
+- **THEN** the "Layout" subsection of "Packages" describes the `packages/<category>/<plugin>/<pkg>/` convention and lists all 18 categories
+
+#### Scenario: MANIFEST.md regenerated
+
+- **WHEN** `bun scripts/folder-reorg/generate-manifest.ts` runs after the restructure
+- **THEN** every package entry in `MANIFEST.md` shows the three-level path and the category column is populated from `assignment.yml`