Initial Commit

openspec/archive/2026-05-13-align-packages-to-folders-spec/spec-delta.md

@@ -0,0 +1,91 @@
+<!-- markdownlint-disable MD024 -->
+
+# 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/<category>/<pkg>/`, where `<category>` is a one-word key from `FOLDERS.md` and `<pkg>` 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.
+
+<!-- markdownlint-enable MD024 -->