|
| 1 | +--- |
| 2 | +id: plan-broad-filesystem-reorg-from-audit |
| 3 | +title: Plan and stage a broad filesystem reorg from the layout audit |
| 4 | +status: doing |
| 5 | +priority: high |
| 6 | +created: 2026-03-28 |
| 7 | +updated: 2026-03-28 |
| 8 | +target_release: next |
| 9 | +estimate: L |
| 10 | +risk: high |
| 11 | +tags: |
| 12 | + - work-item |
| 13 | + - kanban |
| 14 | + - refactor |
| 15 | + - repo-layout |
| 16 | + - filesystem |
| 17 | + - restructuring |
| 18 | +owner: pi |
| 19 | +blocked-by: |
| 20 | + - audit-project-filesystem-layout |
| 21 | +--- |
| 22 | + |
| 23 | +# Plan and stage a broad filesystem reorg from the layout audit |
| 24 | + |
| 25 | +## Summary |
| 26 | + |
| 27 | +Use the completed filesystem audit as the basis for a deliberate **broad repo |
| 28 | +reorganization** rather than only a series of small local cleanups. |
| 29 | + |
| 30 | +This ticket exists because the earlier audit intentionally leaned conservative, |
| 31 | +but project direction has now changed: a wider reorg is desired, provided it is |
| 32 | +planned, staged, and validated rather than executed as an ad-hoc move sweep. |
| 33 | + |
| 34 | +## Objective |
| 35 | + |
| 36 | +Produce and begin executing a broad reorganization plan that improves: |
| 37 | + |
| 38 | +- repo-root vs `runtime/` ownership clarity |
| 39 | +- placement of docs/scripts/artifacts |
| 40 | +- containment of generated/transient output under `runtime/` |
| 41 | +- board/work-item path clarity (`kanban/` vs possible `workitems/`) |
| 42 | +- source/module discoverability where grouping is already justified |
| 43 | + |
| 44 | +## Scope |
| 45 | + |
| 46 | +Potentially in scope, pending plan decisions: |
| 47 | + |
| 48 | +- root vs `runtime/` boundary clarification and accompanying moves |
| 49 | +- `docs/` / `runtime/docs/` rationalization |
| 50 | +- `scripts/` / `runtime/scripts/` rationalization |
| 51 | +- `artifacts/` / `runtime/artifacts/` / `runtime/reports/` rationalization |
| 52 | +- generated/transient runtime layout policy and moves where justified |
| 53 | +- `kanban/` path rename follow-up if still desired after review |
| 54 | +- downstream regrouping such as `runtime/src/channels/web/` flattening cleanup |
| 55 | + |
| 56 | +## Non-goals |
| 57 | + |
| 58 | +- Do **not** perform a blind all-at-once move sweep without a reviewed plan. |
| 59 | +- Do **not** mix unrelated behavioral refactors into the layout work. |
| 60 | +- Do **not** break packaging/runtime/tooling paths without explicit validation. |
| 61 | + |
| 62 | +## Recommended approach |
| 63 | + |
| 64 | +### Phase 1 — design the target shape |
| 65 | +1. Turn the audit findings into a concrete target layout map. |
| 66 | +2. Decide which moves are mandatory vs nice-to-have. |
| 67 | +3. Identify compatibility shims/aliases/documentation needed during transition. |
| 68 | +4. Split execution into reviewable batches if one-shot migration is too risky. |
| 69 | + |
| 70 | +### Phase 2 — execute in staged slices |
| 71 | +1. Land the highest-value structural moves first. |
| 72 | +2. Re-run path-sensitive validation after each batch. |
| 73 | +3. Update docs, helpers, and board/tooling references alongside the moves. |
| 74 | + |
| 75 | +## Acceptance Criteria |
| 76 | + |
| 77 | +- [ ] A concrete target layout is documented from the audit findings. |
| 78 | +- [ ] The broad reorg is broken into explicit execution stages or committed as a justified one-shot migration plan. |
| 79 | +- [ ] Path-sensitive docs/helpers/tooling impacted by the reorg are identified up front. |
| 80 | +- [ ] Validation expectations are documented for each execution batch. |
| 81 | +- [ ] The plan clearly distinguishes must-move areas from acceptable current structure. |
| 82 | + |
| 83 | +## Test / Validation Plan |
| 84 | + |
| 85 | +- [ ] Search for stale path references after each staged move. |
| 86 | +- [ ] Run affected lint/typecheck/tests depending on the directories touched. |
| 87 | +- [ ] Re-check packaging/install/documentation paths when boundary directories move. |
| 88 | +- [ ] Re-check board/skill/helper behavior if `kanban/` is renamed. |
| 89 | + |
| 90 | +## Definition of Done |
| 91 | + |
| 92 | +- [ ] The broad reorg plan is approved and broken into executable stages. |
| 93 | +- [ ] At least the first execution stage is clearly defined or landed. |
| 94 | +- [ ] The board reflects the new reorg sequence clearly enough for follow-up work. |
| 95 | + |
| 96 | +## Updates |
| 97 | + |
| 98 | +### 2026-03-28 |
| 99 | +- Created immediately after reviewing `audit-project-filesystem-layout` in light of new project guidance. |
| 100 | +- The audit findings still stand, but its earlier conservative recommendation against broad churn is now explicitly superseded. |
| 101 | +- Starting point inputs for this planning/execution umbrella: |
| 102 | + - `docs/filesystem-layout-audit-2026-03-28.md` |
| 103 | + - `kanban/10-next/clarify-root-vs-runtime-ownership-boundaries.md` |
| 104 | + - `kanban/10-next/rationalize-runtime-generated-output-layout.md` |
| 105 | + - `kanban/10-next/group-web-channel-flat-files.md` |
| 106 | + - `kanban/10-next/rename-project-kanban-to-workitems-and-update-skilling.md` |
| 107 | +- Immediate next step: turn the audit into a target-state reorg map and decide whether execution should happen in 2–4 staged batches or a more aggressive single migration. |
| 108 | + |
| 109 | +## Links |
| 110 | + |
| 111 | +- `kanban/40-review/audit-project-filesystem-layout.md` |
| 112 | +- `docs/filesystem-layout-audit-2026-03-28.md` |
| 113 | +- `kanban/10-next/clarify-root-vs-runtime-ownership-boundaries.md` |
| 114 | +- `kanban/10-next/rationalize-runtime-generated-output-layout.md` |
| 115 | +- `kanban/10-next/group-web-channel-flat-files.md` |
| 116 | +- `kanban/10-next/rename-project-kanban-to-workitems-and-update-skilling.md` |
0 commit comments