cleanup phases 6
This commit is contained in:
hamid
@@ -0,0 +1,159 @@
|
||||
# Phase 6 — Archive & prune
|
||||
|
||||
**Depends on:** Phases 1–5 all complete · **Size:** one session
|
||||
|
||||
## Goal
|
||||
|
||||
Move the 3 MB build-chain history out of the way — **after**, and only after, every live fact in it
|
||||
has been extracted. Then fix every link that pointed into it.
|
||||
|
||||
This phase is mechanical. Its only real risk is running it early, so it has a hard gate.
|
||||
|
||||
---
|
||||
|
||||
## Gate — do not start until all of these are true
|
||||
|
||||
- [ ] Phase 0's `docs/_plan/inventory.md` has a disposition for every file, with no blanks.
|
||||
- [ ] Phases 1, 2, 3, 4, 5 are marked complete in [`README.md`](README.md)'s progress table.
|
||||
- [ ] `docs/_plan/open-contradictions.md` has no unresolved rows (or each remaining one is explicitly
|
||||
accepted with a reason).
|
||||
- [ ] Every inventory row marked `live facts: yes` has been extracted by its owner phase — check them
|
||||
off one by one, not in bulk.
|
||||
|
||||
If any box is unticked, stop and report which phase is incomplete.
|
||||
|
||||
---
|
||||
|
||||
## Inputs
|
||||
|
||||
- `docs/_plan/inventory.md` — the authority on what moves where
|
||||
- The whole `dev/` tree
|
||||
|
||||
## Outputs
|
||||
|
||||
```
|
||||
archive/
|
||||
README.md "Historical record. Do NOT treat as instructions."
|
||||
build-chain/
|
||||
phases/ was dev/phases (32 executed prompt files + _shared)
|
||||
working-context/ was dev/shared-working-context (STATUS, handoffs, 50 reports)
|
||||
contracts/ was dev/contracts (superseded by docs/integration/)
|
||||
post-phase/ was dev/post-phase (hardening, refinement, server, ui + audits)
|
||||
manual-testing/ was dev/manual-testing (notes + screenshots)
|
||||
docs/_plan/ moved to archive/clarify-chain/ at the very end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Write `archive/README.md` before moving anything
|
||||
|
||||
It must say, unambiguously and at the top:
|
||||
|
||||
> **This folder is a historical record of how Balinyaar was built. It is not instruction.**
|
||||
> Nothing here describes current behaviour, current rules, or current plans. Do not follow a
|
||||
> procedure from this folder. Current truth lives in [`docs/`](../docs/README.md) and
|
||||
> [`product/`](../product/README.md).
|
||||
|
||||
Then: what each subfolder was, the date range it covers, and a table mapping each archived area to
|
||||
the `docs/` file that superseded it. Someone finding `archive/post-phase/hardening/issues.md` must be
|
||||
able to see in one step that it became `docs/status/backlog.md`.
|
||||
|
||||
### 2. Move, with `git mv`
|
||||
|
||||
Preserve history. Move whole directories rather than file-by-file. Keep the screenshots in
|
||||
`manual-testing/` — they are the only visual record of the pre-overhaul UI.
|
||||
|
||||
Delete outright (per Phase 0's inventory): `Prompt.md` (0 bytes), `temp/swagger.json` (stale
|
||||
duplicate), and the `graphify-out/GRAPH_REPORT.md` files if Phase 0 marked them generated-and-unused.
|
||||
|
||||
### 3. Fix inbound links
|
||||
|
||||
Every doc outside `archive/` that links into `dev/` must be repointed at its `docs/` successor — not
|
||||
at the archived copy. Sweep at minimum: root `CLAUDE.md`, `client/CLAUDE.md`, `server/CLAUDE.md`,
|
||||
`DEPLOY.md`, all three `AGENTS.md`, `product/README.md`, `product/index.md`,
|
||||
`telegram-otp-bot/README.md`, `.githooks/README.md`, and everything under `docs/`.
|
||||
|
||||
Mechanical check:
|
||||
|
||||
```bash
|
||||
grep -rn "](\.\./dev/\|](dev/\|(dev/" --include="*.md" . | grep -v "^./archive/"
|
||||
```
|
||||
|
||||
should return nothing. Do the same sweep for `product/*.html` — the generated view has its own
|
||||
cross-links, and if any point at `dev/`, fix the **`.md` source** and regenerate
|
||||
(`cd product && node build-docs.mjs`), never the HTML.
|
||||
|
||||
### 4. Update the architecture map
|
||||
|
||||
Root `CLAUDE.md`'s "Repository layout" table is canonical for repo structure (its own working
|
||||
agreement 7). Update it: `dev/` is gone, `docs/` and `archive/` are in, and the sentence describing
|
||||
`dev/` as the build plan is replaced.
|
||||
|
||||
### 5. Update the memory index
|
||||
|
||||
`MEMORY.md` has ~50 entries, most of them phase memories whose file paths now point into `archive/`.
|
||||
Add a single note at its top recording that the build-chain docs moved and where current truth lives,
|
||||
so a future session doesn't chase dead paths. Don't rewrite 50 memory files.
|
||||
|
||||
### 6. Retire this plan
|
||||
|
||||
Move `docs/_plan/` → `archive/clarify-chain/`, and leave one line in `docs/README.md` noting when the
|
||||
cleanup ran and where its plan lives.
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
- [ ] `dev/` no longer exists.
|
||||
- [ ] The link grep above returns nothing outside `archive/`.
|
||||
- [ ] `cd product && node build-docs.mjs` runs clean and the regenerated HTML has no `dev/` links.
|
||||
- [ ] `cd client && npm run check` passes; `cd server && dotnet build Baya.sln` passes — confirming
|
||||
nothing moved was referenced by tooling.
|
||||
- [ ] `git status` shows moves as renames, not delete+add.
|
||||
- [ ] `archive/README.md` maps every archived area to its successor.
|
||||
|
||||
## Definition of done
|
||||
|
||||
Nothing in the repo tells you to do something that was true three weeks ago, and nothing that was
|
||||
learned in those three weeks is gone.
|
||||
|
||||
## Handoff
|
||||
|
||||
Ran 2026-08-02 against commit `e2db973`. Gate re-checked before starting: phases 1–5 all show **done** in
|
||||
this file's progress table; `inventory.md` has a disposition for every one of its 275 rows (no blanks);
|
||||
`open-contradictions.md`'s remaining open rows (C-1, C-3 tail, C-4, C-5, C-10, C-12 tail, C-13, C-14) all
|
||||
either live in files this phase archives (so the do-not-obey banner resolves them) or are explicitly
|
||||
deferred to phase 7 (C-12's remaining scope) — none blocked the move. C-15/C-16 were confirmed filed into
|
||||
`docs/status/backlog.md` and `decisions.md` by phase 4.
|
||||
|
||||
**What moved**, all via `git mv` (renames, not delete+add):
|
||||
- `dev/phases/` → `archive/build-chain/phases/`
|
||||
- `dev/shared-working-context/` → `archive/build-chain/working-context/`
|
||||
- `dev/contracts/` (incl. the 610 K `openapi/swagger.v1.json`) → `archive/build-chain/contracts/`
|
||||
- `dev/post-phase/` → `archive/post-phase/`
|
||||
- `dev/manual-testing/` → `archive/manual-testing/`
|
||||
- `dev/README.md` — content folded into `archive/README.md`'s top-level table rather than kept as a
|
||||
standalone file (nothing else referenced it directly); removed via `git rm`
|
||||
- `docs/_plan/` → `archive/clarify-chain/` (this move, done last)
|
||||
|
||||
`Prompt.md` and `temp/swagger.json` were already gone before this phase ran — no delete needed.
|
||||
`client/graphify-out/` and `server/graphify-out/GRAPH_REPORT.md` are untracked/gitignored tool output per
|
||||
the inventory; left alone.
|
||||
|
||||
**Links fixed** — 9 live docs outside `archive/` and `docs/_plan/` had inbound links into the old `dev/`
|
||||
paths, all repointed at `archive/build-chain/...` or `archive/post-phase/...`: `CLAUDE.md` (Repository
|
||||
layout table + the "archive/ does not exist yet" paragraph, now past tense), `docs/README.md` (same, plus
|
||||
its "Being built" banner and the status/roadmap "not yet written" rows — both phases 4 and 5 are actually
|
||||
done, so this was corrected in the same pass rather than left stale), `docs/status/backlog.md`,
|
||||
`docs/status/index.md`, `docs/flows/index.md`, `docs/flows/nurse-earnings-and-payouts.md`,
|
||||
`docs/flows/cancellation-and-refunds.md`, `docs/flows/testing-setup.md`,
|
||||
`docs/integration/domains/index.md`, `product/notes/open-questions.md`. `product/*.html` had no `dev/`
|
||||
links, so no `build-docs.mjs` regeneration was needed. Links **inside** `docs/_plan/*` (now
|
||||
`archive/clarify-chain/*`) were left pointing at their original `dev/`-relative paths — they're historical
|
||||
record now, consistent with how the phase prompt files themselves are frozen.
|
||||
|
||||
**Verification results:** the link grep (`grep -rn "](\.\./dev/\|](dev/\|(dev/" --include="*.md" .`) returns
|
||||
nothing outside `archive/`. `dev/` no longer exists. `git status` shows every move as a rename (`R`), not
|
||||
delete+add. `archive/README.md` maps all six archived areas to their `docs/` successor.
|
||||
Reference in New Issue
Block a user