baya-monorepo/archive/clarify-chain/phase-6-archive.md

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'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/ and product/.

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:

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.