cleanup phases 6
This commit is contained in:
hamid
@@ -0,0 +1,221 @@
|
||||
# Phase 0 — Inventory & scaffold
|
||||
|
||||
**Depends on:** nothing · **Blocks:** every other phase · **Size:** one session
|
||||
|
||||
## Goal
|
||||
|
||||
Before anything is moved, merged, or deleted, produce two things:
|
||||
|
||||
1. **A disposition for every one of the ~260 markdown files in the repo** — so that "summarize
|
||||
without losing data" is a checkable claim rather than a hope.
|
||||
2. **The empty `docs/` skeleton** with a real entry point, so later phases have somewhere to write.
|
||||
|
||||
Plus one piece of housekeeping every later phase needs: a **fresh OpenAPI snapshot**, because the
|
||||
committed one is 16 days behind the server code.
|
||||
|
||||
This phase writes almost no prose. It is a survey.
|
||||
|
||||
---
|
||||
|
||||
## Inputs
|
||||
|
||||
- The whole repo. Specifically: `dev/` (199 files), `product/` (48), root (4), `client/` (5),
|
||||
`server/` (6), `telegram-otp-bot/` (2), `.claude/skills/` (1), `.githooks/` (1).
|
||||
- [`../README.md`](README.md) — the target tree and the decisions.
|
||||
|
||||
## Outputs
|
||||
|
||||
| File | What it is |
|
||||
| --- | --- |
|
||||
| `docs/_plan/inventory.md` | The disposition table — every markdown file, one row |
|
||||
| `docs/README.md` | The single entry point: a map of `docs/`, `product/`, `archive/` and what belongs where |
|
||||
| `docs/rules/index.md` `docs/integration/index.md` `docs/flows/index.md` `docs/status/index.md` `docs/roadmap/index.md` | Stub indexes, each with a one-line purpose and a "populated by phase N" note |
|
||||
| `docs/integration/openapi/swagger.v1.json` | Regenerated from the running server |
|
||||
| `docs/_plan/open-contradictions.md` | Running list of doc-vs-doc and doc-vs-code conflicts spotted during the survey — later phases resolve these |
|
||||
|
||||
---
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Build the inventory
|
||||
|
||||
Walk every `.md` file (exclude `node_modules`, `bin`, `obj`, `.git`). For each, record:
|
||||
|
||||
| Column | Meaning |
|
||||
| --- | --- |
|
||||
| `path` | repo-relative |
|
||||
| `bytes` | size |
|
||||
| `last commit` | `git log -1 --format=%ad --date=short -- <path>` |
|
||||
| `kind` | `rule` · `reference` · `contract` · `plan` · `report` · `history` · `business` · `ops` · `feedback` |
|
||||
| `disposition` | `keep-as-is` · `move` · `distill` · `merge-into` · `archive` · `delete` |
|
||||
| `target` | where its content ends up (a `docs/…` path, or `archive/…`) |
|
||||
| `owner phase` | which phase (1–7) handles it |
|
||||
| `live facts?` | `yes` / `no` — does it contain anything not yet captured elsewhere? |
|
||||
|
||||
Rules for assigning disposition:
|
||||
|
||||
- **`dev/phases/backend/*` and `dev/phases/frontend/*`** (32 files, ~1 MB): these are *prompts that
|
||||
were already executed*. Disposition `archive`. But scan each for **decisions and constraints stated
|
||||
in the prompt that are not visible in the code** — those are `live facts: yes` and go to Phase 1
|
||||
(if a rule) or Phase 4 (`decisions.md`).
|
||||
- **`dev/shared-working-context/reports/*` (50 files)**: `archive`, but every "Follow-ups for later
|
||||
phases" / "Deferred" / "Known gap" section is a live fact for **Phase 4**. Extract the section
|
||||
headings now; Phase 4 reads them in detail.
|
||||
- **`dev/shared-working-context/*/STATUS.md`** (86 KB combined): `distill` → Phase 4 (`decisions.md`
|
||||
+ `implemented.md`), then `archive`.
|
||||
- **`dev/shared-working-context/frontend/requests/for-backend.md`** (67 REQs): `distill` → Phase 4.
|
||||
- **`dev/post-phase/hardening/issues.md`** (18 open items): `distill` → Phase 4, **with
|
||||
re-verification** — the UI and refinement chains ran after this file was written and some items are
|
||||
probably already fixed.
|
||||
- **`dev/contracts/**`**: `move` → `docs/integration/` — Phase 2 owns it, and refreshes it against code.
|
||||
- **`dev/post-phase/manual-testing-plan.md`** + **`refinement/RUNBOOK.md`**: `distill` → Phase 3
|
||||
(`docs/flows/testing-setup.md` + the per-flow files). Both are stale on secrets handling.
|
||||
- **`dev/manual-testing/iteration-*/`**: `distill` → Phase 4 (unfinished items) then `archive`
|
||||
(**keep the PNG screenshots** — they are the only visual record of the pre-overhaul UI).
|
||||
- **`product/**`**: `keep-as-is`, every one. Not this chain's business.
|
||||
- **`client/CLAUDE.md`, `server/CLAUDE.md`, `server/CONVENTIONS.md`, `client/messages/STYLE.md`,
|
||||
`dev/phases/_shared/*`, `dev/contracts/conventions/*`, `.claude/skills/*/SKILL.md`**: `distill` →
|
||||
Phase 1.
|
||||
- **`DEPLOY.md`**: `keep-as-is` at root (it is the deploy *procedure* and it is current) — but Phase 2
|
||||
fixes its stale `user-secrets` reference and Phase 2's `topology.md` links to it.
|
||||
- **`Prompt.md`** (0 bytes): `delete`.
|
||||
- **`temp/swagger.json`** (stale duplicate): `delete` — Phase 2 replaces it.
|
||||
- **`client/graphify-out/GRAPH_REPORT.md`, `server/graphify-out/GRAPH_REPORT.md`**: generated tool
|
||||
output. Decide `keep-as-is` if the tool is still used, else `delete`; check `.gitignore` first.
|
||||
|
||||
### 2. Log contradictions as you go
|
||||
|
||||
Write `docs/_plan/open-contradictions.md` with one row per conflict: *claim A (file:line) vs claim B
|
||||
(file:line or code:line) — unresolved*. Seed it with the ones already known:
|
||||
|
||||
- **`user-secrets` is required** (18 files) vs **`user-secrets` was removed and the store isn't read**
|
||||
(root [CLAUDE.md](../../CLAUDE.md) §6, commit `5885280`).
|
||||
- **`dev/contracts/` describes the API** (frozen 2026-07-13) vs **`server/src`** (through 2026-07-28).
|
||||
- **Design language in [.claude/skills/frontend-designer/SKILL.md](../../.claude/skills/frontend-designer/SKILL.md) §§1–7**
|
||||
vs **[client/CLAUDE.md](../../client/CLAUDE.md) "Theme System" / "Anti-patterns"** — overlapping, possibly divergent.
|
||||
- **Both** vs **the reality after iterations 1–2** (mobile-scoped shell, bottom nav, react-hook-form,
|
||||
new icon set) — the skill predates that overhaul.
|
||||
- **18 hardening items open** (2026-07-16) vs **UI phases 0–13 and the deploy commits that ran after**.
|
||||
|
||||
Do **not** resolve these here. Phase 0 only finds them.
|
||||
|
||||
### 3. Regenerate the OpenAPI snapshot
|
||||
|
||||
Boot the server and capture the live swagger document:
|
||||
|
||||
```bash
|
||||
cd server && dotnet run --project src/API/Baya.Web.Api/Baya.Web.Api.csproj
|
||||
# then, from another shell:
|
||||
curl -sk https://localhost:5002/swagger/v1/swagger.json -o docs/integration/openapi/swagger.v1.json
|
||||
```
|
||||
|
||||
Record in the file's sibling `README.md`: the date, the commit, and the endpoint count. Diff the
|
||||
endpoint *paths* against the old `dev/contracts/openapi/swagger.v1.json` and write the added/removed
|
||||
list into `docs/_plan/open-contradictions.md` — Phase 2 uses it as its worklist.
|
||||
|
||||
If the server will not boot (config, DB reachability), **stop and report** rather than guessing. A
|
||||
stale snapshot is what caused half of this mess.
|
||||
|
||||
### 4. Scaffold `docs/`
|
||||
|
||||
Create the directories and stub index files from the target tree in [`README.md`](README.md). Each
|
||||
stub is ~10 lines: what lives here, which phase fills it, and a `> Populated by phase N — not yet
|
||||
written` banner. `docs/README.md` is the only one with real content: the map, and the
|
||||
`product/` vs `docs/` vs `archive/` rule.
|
||||
|
||||
Do **not** create `archive/` yet — Phase 6 does that, once there is something safe to put in it.
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
- [ ] `docs/_plan/inventory.md` has a row for every `.md` file the survey walked; the count matches
|
||||
`find . -name "*.md" -not -path "./node_modules/*" … | wc -l` (~260 at baseline).
|
||||
- [ ] No row has an empty `disposition` or `owner phase`.
|
||||
- [ ] Every row with `live facts: yes` names the phase that will extract them.
|
||||
- [ ] `docs/integration/openapi/swagger.v1.json` exists and its endpoint count is recorded.
|
||||
- [ ] Every stub index exists and says which phase fills it.
|
||||
- [ ] Nothing outside `docs/` was modified, except deleting `Prompt.md` and `temp/swagger.json`.
|
||||
|
||||
## Definition of done
|
||||
|
||||
You can answer, for any markdown file in the repo, "where does this end up and who handles it?"
|
||||
without re-reading the file.
|
||||
|
||||
## Handoff
|
||||
|
||||
**Run 2026-07-29 against commit `c99e3f4`. All six outputs delivered; all six verification boxes pass.**
|
||||
|
||||
### Counts
|
||||
|
||||
| | Planned | Actual |
|
||||
| --- | --- | --- |
|
||||
| Markdown files surveyed | ~260 | **275** (273 tracked + 2 gitignored `graphify-out/GRAPH_REPORT.md`) |
|
||||
| `dev/` | 199 | 199 ✓ |
|
||||
| `dev/shared-working-context/reports/` | 50 | **53** reports + `README.md` + `mocks-registry.md` |
|
||||
| `dev/phases/backend|frontend` prompts | 32 | 32 ✓ |
|
||||
| REQs in `for-backend.md` | 67 | 67 ✓ |
|
||||
| Hardening items | 18 open | 18 of 18 unticked ✓ |
|
||||
| `product/` | 48 | 48 ✓ |
|
||||
|
||||
The extra 15 over "~260" are the 9 files of `docs/_plan/` itself, the 2 gitignored graph reports, and 3
|
||||
more reports than the plan counted.
|
||||
|
||||
Disposition split: **172 archive · 59 keep-as-is · 24 distill · 17 move · 2 merge-into · 1 delete**.
|
||||
**209 of 275 carry live facts.** Owner phases: **4 → 149 files**, 7 → 31, 2 → 23, 1 → 17, 6 → 17, 3 → 2,
|
||||
0 → 1, none → 35.
|
||||
|
||||
### Four things that change a later phase's scope
|
||||
|
||||
1. **Phase 2 is smaller than budgeted at the OpenAPI layer.** The 16-day-stale snapshot differs from the
|
||||
live server by **one endpoint** (`POST /api/v1/webhooks/payouts/{provider}`) and **one schema**
|
||||
(`GeneratePayoutBatchCommand`). Zero removals, zero method changes, identical schema count (339).
|
||||
Spend the budget on the 17 hand-written `domains/*.md` instead — that is where drift can hide, and
|
||||
nothing has ever checked them mechanically.
|
||||
|
||||
2. **Phase 3 fixes one stale bring-up doc, not two.** The plan says `manual-testing-plan.md` *and*
|
||||
`RUNBOOK.md` are both stale on secrets. `RUNBOOK.md` was updated in `5885280` and is correct — it even
|
||||
has a troubleshooting row for the error you now get. Only `manual-testing-plan.md` (last commit
|
||||
`bd06ef0`, the day before) still instructs `dotnet user-secrets`. But Phase 3 inherits a **bigger**
|
||||
bring-up problem the plan did not list: contradictions **C-3/C-4/C-5** — the API is `http://`, not
|
||||
`https://`, in ~18 places; the `dev-certs` step is therefore dead; and `RUNBOOK.md` builds a *local*
|
||||
Docker SQL Server while the committed dev config uses a *remote, already-seeded* one. Those are two
|
||||
different worlds and Phase 3 must pick one and walk it.
|
||||
|
||||
3. **Phase 7's premise is wrong in one direction and right in another.** The frontend-designer skill does
|
||||
**not** predate the UI overhaul — it was rewritten at `baa3cc6` (manual improvement 1) and already
|
||||
covers `AppFrame`, `BottomBar`, `APP_FRAME_MAX_WIDTH` and the Lucide-only registry. It is stale by
|
||||
exactly **one iteration**: `client/CLAUDE.md` was updated at `e6a8f93` (manual improvement 2), which
|
||||
changed **44 files, +3419/−2449** under `client/src`. Diff against iteration 2, not against the whole
|
||||
overhaul.
|
||||
|
||||
4. **Phase 4 is the heavy phase, not Phase 3.** 149 of 275 files land on it. Two structural findings make
|
||||
it tractable: every `dev/phases/*` prompt shares a fixed layout where **§5 "Critical rules you must not
|
||||
get wrong"** is exactly the not-in-the-code decision set (verified in all 32), and **all 53 reports**
|
||||
carry a "Follow-ups for later phases" section (verified). Both are mechanically extractable.
|
||||
|
||||
### Smaller notes
|
||||
|
||||
- **`temp/swagger.json` was never committed** — `.gitignore:1` ignores `temp`. Deleting it removed local
|
||||
clutter, not repo content. The `_plan/README.md` diagnosis calls it a "second stale copy" in the repo;
|
||||
it is not in the repo.
|
||||
- **`dev/contracts/domains/messaging.md`** (851 B) is a headerless fragment that silently amends
|
||||
`messaging-notifications-admin.md`. Phase 2 should **merge**, not move both (C-8).
|
||||
- **`SET_VIA_USER_SECRETS_OR_ENV`** is still the placeholder string in `appsettings.json` and is enforced
|
||||
by `StartupSecretsGuard` and the pre-commit hook. Behaviour is correct; the *name* instructs a reader to
|
||||
use a store that no longer exists (C-2).
|
||||
- **The `graphify-out/` reports are gitignored generated output**, so the plan's "decide keep or delete"
|
||||
is moot — they are not repo content and were left alone.
|
||||
- **Leaf directories are not pre-created.** `docs/rules/{shared,client,server}/` and
|
||||
`docs/integration/domains/` are named in their index stubs but not made on disk: git does not track
|
||||
empty directories, so an empty scaffold would silently vanish. Each phase creates its own with its
|
||||
first file.
|
||||
- **Server boot gotchas worth reusing** (recorded in `docs/integration/openapi/README.md`): it binds
|
||||
**HTTP**, first boot takes ~40 s because Development migrates and seeds against the *remote* DB, and
|
||||
`curl` to localhost returns **502** unless you pass `--noproxy '*'`.
|
||||
|
||||
### Contradictions
|
||||
|
||||
14 logged in [open-contradictions.md](open-contradictions.md), including a
|
||||
[corrections section](open-contradictions.md#corrections-to-the-seeded-list) covering the three seeded
|
||||
claims that did not reproduce as stated. Phase 0 resolved none, by design.
|
||||
Reference in New Issue
Block a user