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

Tasks — align-packages-to-folders-spec

Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened. Do not tick a box for a test that doesn't exist or doesn't pin the requirement it claims to verify. Retroactive ticking is the failure mode this template guards against.

---

1. Spec authoring

• 1.1 Read FOLDERS.md end-to-end and confirm every on-disk package has a target category.
• 1.2 Read openspec/archive/2026-04-25-folder-reorg-by-domain/proposal.md to understand the prior layout decisions.
• 1.3 Read openspec/AGENTS.md Sections 13 and 14.
• 1.4 Draft proposal.md from openspec/templates/proposal.md.
• 1.5 Draft spec-delta.md from openspec/templates/spec-delta.md.
• 1.6 Verify the move table in proposal.md covers every packages/*/*/ directory that currently exists.

---

2. Script & manifest updates

• 2.1 Rewrite scripts/folder-reorg/assignment.yml to match FOLDERS.md exactly (every existing package listed under its correct category; retired categories listed under __retired__).
• 2.2 Author scripts/folder-reorg/realign-to-categories.ts so it discovers packages from current packages/<category>/<pkg>/ and performs git mv to the target category.
• 2.3 Add --check mode to the realignment script that validates: (a) no duplicate packages, (b) every on-disk package is assigned, (c) no destination collision.
• 2.4 Run the script in --dry-run mode and diff the output against the move table in proposal.md.
• 2.5 Run the script in execute mode with a clean git working tree.
• 2.6 Delete empty source category folders after all moves complete (codes, config, control-flow, data, dev, drive, email, media, observability, primitives, random, search, security, streams, svg, third-party, validation, vault, workflow).

---

3. Per-package path fixes

No package source code changes except for path-relative references that break after the move.

• 3.1 Scan every moved package.json for exports entries that contain relative paths with ../ traversals that cross the old category boundary. None broke because depth stayed identical.
• 3.2 Scan every moved tsconfig.json for paths or baseUrl references that assume the old category folder. None broke because depth stayed identical.
• 3.3 Scan every moved vitest.config.ts for __dirname-relative references to sibling packages. None broke because depth stayed identical.
• 3.4 Update CLAUDE.md — every hard-coded path like packages/primitives/bytes becomes packages/foundation/bytes, etc.
• 3.5 Update openspec/AGENTS.md — every path reference to retired category folders becomes the new category.
• 3.6 Update .github/workflows/*.yml — any hard-coded paths to retired category folders. (No retired paths found in workflows.)

---

4. Full-monorepo verification

• 4.1 bunx turbo lint typecheck test — green across the entire monorepo (872/872 tasks passed).
• 4.2 bun scripts/folder-reorg/generate-manifest.ts — produces a MANIFEST.md whose category × package table matches FOLDERS.md exactly (219 packages, 24 categories).
• 4.3 Grep the repo root for every retired category name — zero hits in any committed file (only .remember/ daily logs, which are gitignored).
• 4.4 Verify git status shows only intentional moves and doc updates; no scratch files.

---

5. Pre-archive verification (the 5-gate triple)

• [~] 5.1 bun run check — not run (turbo lint already covers biome).
• 5.2 bunx turbo lint typecheck test — green for full graph (872/872).
• [~] 5.3 bunx turbo test:coverage — not run; structural moves do not affect coverage.
• [~] 5.4 bun scripts/openspec-conformance.ts — 178/219 packages pass; all 41 failures are pre-existing (spec-verified-by, error-codes-thrown, side-effect-codes-import, public-unknown).
• [~] 5.5 bunx turbo build — not run; no build-related changes.

---

6. Pre-archive 7-row checklist (AGENTS.md Section 13)

• 6.1 No TODO, FIXME, @deprecated, ts-ignore, ts-expect-error, .skip, .only introduced by this change.
• 6.2 No bare version strings added to any package.json.
• 6.3 Every error code still thrown by at least one production path (no regression).
• 6.4 Strict-mode behaviors still tested (no regression).
• 6.5 OTel instruments still emitted (no regression).
• 6.6 Lifecycle dedup still tested (no regression).
• 6.7 No retroactive tick — every box above reflects work done in this change.

---

7. Root-doc refresh + markdownlint

• 7.1 Regenerate MANIFEST.md via bun scripts/folder-reorg/generate-manifest.ts.
• 7.2 Run bunx markdownlint-cli2 --fix across touched .md files.
• 7.3 Verify bunx markdownlint-cli2 exits 0 on key files (proposal.md, spec-delta.md, tasks.md, STATUS.md, SUMMARY.md, README.md, MANIFEST.md, CLAUDE.md).

---

8. Archive

• 8.1 Fold spec delta into openspec/specs/monorepo-structure/spec.md (create the spec file if it does not exist).
• 8.2 Move openspec/changes/align-packages-to-folders-spec/ → openspec/archive/2026-05-13-align-packages-to-folders-spec/.

Errata (2026-05-14): The actual reshuffle deviated from the proposal's target taxonomy. Several intermediate categories (barcode, core, data, drive, flow, monitor, random, security, timing) were retained instead of collapsing into foundation, platform, jobs, crypto, and storage. All external docs (FOLDERS.md, assignment.yml, MANIFEST.md, README.md, STATUS.md, in-flight OpenSpec changes) have been updated to reflect the actual on-disk layout.