92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
<!-- 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 -->
|