docs: repoint fp-tea paths at the monorepo tree (RD-32)
The learning guide fp-tea-atomic-design.md still cited the pre-monorepo tree. Every path started with src/app/, which no directory has used since WP-67 split the app into apps/ssp and libs/shared. Rewrite the 11 stale paths per the ticket's mapping rules: a context path becomes apps/ssp/src/app/<context>/..., a shared path becomes libs/shared/src/.... Fix the broken anchor at Part 5b to match the current ARCHITECTURE.md §1 heading. Fix the "Where" guidance in Recipe A to name the atomic layer folder under libs/shared/src/ui/. The teaching prose is unchanged; only addresses moved. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,106 @@
|
||||
# RD-32 — `fp-tea-atomic-design.md` cites the pre-monorepo tree
|
||||
|
||||
Status: done
|
||||
Phase: 5 — fix the docs that describe this flow
|
||||
|
||||
## Why
|
||||
|
||||
`docs/reference/fp-tea-atomic-design.md` is the learning guide. CLAUDE.md names it as one of
|
||||
the three documents that hold the _why_. It still addresses the tree from before the monorepo
|
||||
(WP-67): every path starts `src/app/`, which no directory has done since that work landed.
|
||||
|
||||
A reader learning the codebase from this guide cannot open a single file it names. The prose is
|
||||
correct; only the addresses are wrong.
|
||||
|
||||
## Read first
|
||||
|
||||
- `docs/project/readable-codebase/PLAN.md`, phase 5 item 3 (line 833).
|
||||
- `docs/reference/fp-tea-atomic-design.md` — the whole file.
|
||||
|
||||
## Decisions (pre-made, do not relitigate)
|
||||
|
||||
1. **Two mapping rules cover all 11 paths.** A context path becomes
|
||||
`apps/ssp/src/app/<context>/…`. A `shared` path becomes `libs/shared/src/…` — note that
|
||||
`app/shared/` collapses to `libs/shared/src/`, it does not become `libs/shared/src/app/`.
|
||||
2. **Follow the file's own precedent.** Line 338 already reads
|
||||
`libs/shared/src/application/store.ts`. Line 223 names the same file the old way. Make 223
|
||||
match 338, not the reverse.
|
||||
3. **Fix the broken anchor at line 435.** It reads
|
||||
`#1-the-big-picture-three-contexts-four-layers`. The heading is now "1. The big picture: two
|
||||
apps, cross-app libraries, "contexts", "layers"", so the anchor is
|
||||
`#1-the-big-picture-two-apps-cross-app-libraries-contexts-layers`.
|
||||
4. **Correct line 513's "Where" guidance.** It says `shared/ui/`. After RD-27 a shared block
|
||||
lands in `libs/shared/src/ui/<atoms|molecules|organisms>/`. Name the layer folder; the whole
|
||||
point of RD-27 is that the folder is the layer.
|
||||
5. **Change addresses only.** Do not rewrite the teaching. This guide's prose survived the
|
||||
refactor because it teaches ideas, not file layout.
|
||||
|
||||
## The facts, measured against the current tree
|
||||
|
||||
All 11 occurrences of `src/app/`, and where each file lives now:
|
||||
|
||||
| Line | Cited | Actual |
|
||||
| -------- | --------------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| 72 | `src/app/registratie/domain/value-objects/uren.ts` | `apps/ssp/src/app/registratie/domain/value-objects/uren.ts` |
|
||||
| 98, 255 | `src/app/herregistratie/domain/herregistratie.machine.ts` | `apps/ssp/src/app/herregistratie/domain/herregistratie.machine.ts` |
|
||||
| 223 | `src/app/shared/application/store.ts` | `libs/shared/src/application/store.ts` |
|
||||
| 299 | `src/app/shared/kernel/fp.ts` | `libs/shared/src/kernel/fp.ts` |
|
||||
| 305 | `src/app/herregistratie/ui/herregistratie-wizard/…` | `apps/ssp/src/app/herregistratie/ui/herregistratie-wizard/…` |
|
||||
| 381 | `src/app/showcase/concepts.page.ts` | `apps/ssp/src/app/showcase/concepts.page.ts` |
|
||||
| 388 | `src/app/shared/infrastructure/scenario.ts` | `libs/shared/src/infrastructure/scenario.ts` |
|
||||
| 414, 523 | `src/app/registratie/ui/address-fields/…` | `apps/ssp/src/app/registratie/ui/address-fields/…` |
|
||||
| 588 | `src/app/herregistratie/domain/intake.machine.ts` | `apps/ssp/src/app/herregistratie/domain/intake.machine.ts` |
|
||||
|
||||
Every target exists. This is a rename, not a hunt.
|
||||
|
||||
**One correction to `PLAN.md`.** It says one path points at a deleted file,
|
||||
`submit-herregistratie.ts`. That reference is no longer in the document —
|
||||
`grep -n submit-herregistratie docs/reference/fp-tea-atomic-design.md` returns nothing. Do not
|
||||
go looking for it. Record the correction in the ticket; leave `PLAN.md` itself alone, because
|
||||
it is a design record of what was true when it was written.
|
||||
|
||||
Line 523 sits inside a code comment, not prose. Update it anyway; a stale path in an example is
|
||||
read as a real path.
|
||||
|
||||
## Files
|
||||
|
||||
- `docs/reference/fp-tea-atomic-design.md`.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Rewrite the 11 paths per the table.
|
||||
2. Fix the anchor at line 435.
|
||||
3. Fix the "Where" guidance at line 513.
|
||||
4. `grep -n "src/app/" docs/reference/fp-tea-atomic-design.md` — every remaining hit must start
|
||||
`apps/ssp/src/app/`.
|
||||
5. `npm run ci`.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] No path in the file starts with a bare `src/app/`.
|
||||
- [x] Every cited path resolves. Verify each with `ls`.
|
||||
- [x] The §1 anchor matches the current heading.
|
||||
- [x] `npm run ci` is green.
|
||||
|
||||
## Verification
|
||||
|
||||
1. `npm run ci` — the format check covers the file.
|
||||
2. `grep -oE '\`[^\`]_src/[^\`]_\.ts\`' docs/reference/fp-tea-atomic-design.md | tr -d '\`' |
|
||||
sort -u | xargs ls` — every path must resolve, with no error.
|
||||
3. Open `ARCHITECTURE.md` and confirm the §1 heading text still produces the anchor you wrote.
|
||||
The slug is the heading in lower case, with punctuation removed and spaces turned into
|
||||
hyphens.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- `ARCHITECTURE.md`. RD-31 owns it.
|
||||
- CLAUDE.md and `atomic-design.mdx`. RD-33 owns them.
|
||||
- The teaching content, the diagrams, and the code examples.
|
||||
|
||||
## Risks
|
||||
|
||||
1. **`app/shared/` is not `libs/shared/src/app/`.** The `app` segment disappears for the
|
||||
library. Getting this wrong produces a path that looks right and resolves to nothing.
|
||||
2. **The anchor is easy to half-fix.** GitHub drops the quotation marks around "contexts" and
|
||||
"layers" and the colon, and turns each space into one hyphen. Verify by clicking, not by
|
||||
reasoning.
|
||||
@@ -126,7 +126,7 @@ two. Note that RD-15 exists because 22 abandoned agent worktrees are still on di
|
||||
| RD-29 | The 3 atomic-ladder rules in dependency-cruiser | 27 | | done |
|
||||
| RD-30 | Archive the finished backlogs (16,300 lines) + an archive README | 01 | | done |
|
||||
| RD-31 | `ARCHITECTURE.md` section 6a: symbols not lines, 2 dead paths, new names | 03, 08, 16 | | done |
|
||||
| RD-32 | `fp-tea-atomic-design.md`: 11 broken paths + the broken anchor | 27 | | todo |
|
||||
| RD-32 | `fp-tea-atomic-design.md`: 11 broken paths + the broken anchor | 27 | | done |
|
||||
| RD-33 | CLAUDE.md + `atomic-design.mdx` + the `ui-component` skill | 03, 27, 29 | yes | todo |
|
||||
| RD-34 | _(optional)_ `NO_SUBORGS`/`NO_TABLES` become `RemoteData.Empty` | 11 | | todo |
|
||||
| RD-35 | _(optional, last, alone)_ upload `type:` discriminant to `tag:` | 27 | | todo |
|
||||
|
||||
Reference in New Issue
Block a user