# 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///` 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.