From 9d5898e8d5b1354006d44f7d0918f6e55316112b Mon Sep 17 00:00:00 2001 From: gnezim Date: Tue, 14 Apr 2026 22:07:58 +0300 Subject: [PATCH] Document frozen-barrel rule and A1 rename-pass rework plan --- docs/superpowers/phase-1/frozen-barrels.md | 17 +++++++++++++++ docs/superpowers/phase-1/rename-pass-plan.md | 23 ++++++++++++++++++++ 2 files changed, 40 insertions(+) create mode 100644 docs/superpowers/phase-1/frozen-barrels.md create mode 100644 docs/superpowers/phase-1/rename-pass-plan.md diff --git a/docs/superpowers/phase-1/frozen-barrels.md b/docs/superpowers/phase-1/frozen-barrels.md new file mode 100644 index 00000000..7a3f17f6 --- /dev/null +++ b/docs/superpowers/phase-1/frozen-barrels.md @@ -0,0 +1,17 @@ +# Frozen public barrels + +**Rule.** Cross-module imports inside `src/` go through exactly these five public entries: + +- `@/features/online-board` +- `@/features/schedule` +- `@/features/flights-map` +- `@/features/popular-requests` +- `@/ui` + +No file outside `src/features//` may import from `src/features//components/...` or any deeper path. No file outside `src/ui/` may import `src/ui/primitives/Button`. Enforcement lands in sub-plan **1A-3** via `eslint-plugin-boundaries` + `no-restricted-imports`. + +**Why this is frozen.** Phase 0 assumption **A1** (customer's standard remote-frontend module template) may arrive after 1A-1 ships. When it does, the rename pass documented in `rename-pass-plan.md` must be a mechanical move: rename directories, update import paths at the five barrels, done. If cross-module imports fan out through deep paths, the rename becomes a surgery across dozens of files. + +**What this unblocks.** Every Phase 1 sub-plan can add *internal* files to a feature/UI directory without coordinating with other sub-plans, because nothing outside the barrel depends on internals. The barrel file itself is the review gate. + +**What this costs.** Small friction when a sub-plan wants to expose a new symbol — it must update the barrel. Acceptable cost for the refactor safety it buys. diff --git a/docs/superpowers/phase-1/rename-pass-plan.md b/docs/superpowers/phase-1/rename-pass-plan.md new file mode 100644 index 00000000..643137be --- /dev/null +++ b/docs/superpowers/phase-1/rename-pass-plan.md @@ -0,0 +1,23 @@ +# A1 rename-pass rework plan + +**Trigger.** Phase 0 assumption **A1** — "customer's standard remote-frontend module template" — resolves to a directory layout that differs from the one this repo uses. + +**Scope.** Move/rename directories inside `src/` to match the customer template. Update import paths *only at the five frozen public barrels* (see `frozen-barrels.md`). Do not restructure feature internals. + +**Preconditions.** +- The frozen-barrel rule has been enforced since 1A-1 (Task 11) and 1A-3 ESLint rules are passing on `main`. +- Customer template document is in hand and reviewed for explicit directory conventions. + +**Steps (to be fleshed out when A1 resolves).** +1. Create a target-layout scratch file mapping current path → new path for every file under `src/`. +2. Run the rename as a single automated pass (`git mv`) inside an isolated worktree. +3. Update `tsconfig.json` `paths` aliases if the top-level segments change. +4. Update `vitest.config.ts` aliases to match. +5. Update the five barrel files — this is the *only* hand-edit needed for consumer code. +6. Run `pnpm typecheck && pnpm lint && pnpm test` — green before commit. +7. Run all Phase 1 exit-gate checks (from master plan) — green before PR. +8. Single commit: `Rename src/ layout to match customer module template (A1)`. + +**Escape valve.** If the rename touches more than the five barrels, something violated the frozen-barrel rule between 1A-1 and now. Fix the violation first (move the cross-boundary import through a barrel), then retry the rename. + +**Owner.** This task is attached to 1A-1's exit gate and fires on A1 resolution, whether that happens during Phase 1 or early Phase 2.