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

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

---

## 2. Script & manifest updates

- [x] 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__`).
- [x] 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.
- [x] 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.
- [x] 2.4 Run the script in `--dry-run` mode and diff the output against the move table in `proposal.md`.
- [x] 2.5 Run the script in execute mode with a clean git working tree.
- [x] 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.

- [x] 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.
- [x] 3.2 Scan every moved `tsconfig.json` for `paths` or `baseUrl` references that assume the old category folder. None broke because depth stayed identical.
- [x] 3.3 Scan every moved `vitest.config.ts` for `__dirname`-relative references to sibling packages. None broke because depth stayed identical.
- [x] 3.4 Update `CLAUDE.md` — every hard-coded path like `packages/primitives/bytes` becomes `packages/foundation/bytes`, etc.
- [x] 3.5 Update `openspec/AGENTS.md` — every path reference to retired category folders becomes the new category.
- [x] 3.6 Update `.github/workflows/*.yml` — any hard-coded paths to retired category folders. (No retired paths found in workflows.)

---

## 4. Full-monorepo verification

- [x] 4.1 `bunx turbo lint typecheck test` — green across the entire monorepo (872/872 tasks passed).
- [x] 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).
- [x] 4.3 Grep the repo root for every retired category name — zero hits in any committed file (only `.remember/` daily logs, which are gitignored).
- [x] 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).
- [x] 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)

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

---

## 7. Root-doc refresh + markdownlint

- [x] 7.1 Regenerate `MANIFEST.md` via `bun scripts/folder-reorg/generate-manifest.ts`.
- [x] 7.2 Run `bunx markdownlint-cli2 --fix` across touched `.md` files.
- [x] 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

- [x] 8.1 Fold spec delta into `openspec/specs/monorepo-structure/spec.md` (create the spec file if it does not exist).
- [x] 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.