# Capability Spec Delta: monorepo-structure (align-packages-to-folders-spec) **Scope**: Monorepo package taxonomy and directory layout **Status**: PROPOSED > Every requirement below carries a `**Verified by:**` line at authoring time. No exceptions. (See `openspec/AGENTS.md` Section 13.) --- ## ADDED Requirements ### Requirement: Every package lives in exactly one category folder The repository SHALL enforce that every `@suaveplan/*` package on disk resides under `packages///`, where `` is a one-word key from `FOLDERS.md` and `` matches the npm package name without the `@suaveplan/` prefix. No package may exist outside this two-level nesting. No package may appear in more than one category. #### Scenario: On-disk package is assigned to a FOLDERS.md category - **WHEN** a directory containing a `package.json` exists under `packages/` - **THEN** its immediate parent directory name SHALL appear in `FOLDERS.md` as a category heading - **AND** the package name SHALL appear in that category's Existing or Pending list #### Scenario: No orphaned category folders - **WHEN** a directory exists immediately under `packages/` - **THEN** it SHALL contain at least one package subdirectory (a directory with a `package.json`) - **AND** its name SHALL match a category defined in `FOLDERS.md` **Verified by:** `scripts/folder-reorg/realign-to-categories.ts --check` AND `src/structure/structure.test.ts::"rejects orphaned category folders"` --- ### Requirement: assignment.yml is the machine-readable mirror of FOLDERS.md `scripts/folder-reorg/assignment.yml` SHALL list every on-disk package exactly once, keyed by its `FOLDERS.md` category. The file SHALL be parseable by the migration script and SHALL produce zero duplicate or orphan errors in `--check` mode. #### Scenario: assignment.yml passes uniqueness check - **WHEN** the migration script parses `assignment.yml` - **THEN** no package name appears under more than one category key - **AND** no package name appears under `__retired__` and also under a category #### Scenario: assignment.yml covers every on-disk package - **WHEN** the migration script discovers all `packages/*/*/package.json` files - **THEN** every discovered package name appears in `assignment.yml` - **AND** every package in `assignment.yml` that does not exist on disk is silently skipped (future package) **Verified by:** `scripts/folder-reorg/realign-to-categories.ts --check::"exits 0 with no duplicates or orphans"` --- ### Requirement: MANIFEST.md reflects the on-disk layout `MANIFEST.md` SHALL be auto-generated from on-disk truth. Its category × package table SHALL match `FOLDERS.md` and `assignment.yml` exactly. If a package moves category, regenerating `MANIFEST.md` SHALL reflect the new location without manual editing. #### Scenario: MANIFEST.md regeneration after moves - **WHEN** `bun scripts/folder-reorg/generate-manifest.ts` runs after the realignment - **THEN** every moved package appears under its new category in `MANIFEST.md` - **AND** no retired category folder appears in `MANIFEST.md` **Verified by:** `src/structure/structure.test.ts::"MANIFEST.md matches assignment.yml after regeneration"` --- ### Requirement: No hard-coded retired paths in committed documentation No committed file in the repository SHALL contain a hard-coded path to a retired category folder (e.g., `packages/codes/`, `packages/primitives/`, `packages/vault/`, etc.). Documentation, scripts, and workflow files SHALL reference the current category. #### Scenario: Doc-reference sweep is clean - **WHEN** a grep runs for each retired category folder name across the repo root - **THEN** zero matches are found in any committed file **Verified by:** `scripts/lint/check-retired-paths.ts` (to be created) AND manual grep in `proposal.md` § Verification approach --- ## MODIFIED Requirements > None — this is a pure structural relocation with no behavioral changes to existing specs. --- ## REMOVED Requirements > None — this change does not remove any package capabilities.