baya-monorepo/docs/_plan/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

(filled in by the agent that runs this phase)