# 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.
