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.

4.1 KiB Raw Permalink Blame History Unescape Escape