hamid
244 lines
15 KiB
Markdown
244 lines
15 KiB
Markdown
# Phase 1 — Rules consolidation
|
||
|
||
**Depends on:** Phase 0 · **Can run in parallel with:** Phase 2 · **Size:** 1–2 sessions
|
||
|
||
## Goal
|
||
|
||
Collapse ~10 rule sources into one tiered system, and cut the cost of editing client code from
|
||
~40k tokens to ~5k.
|
||
|
||
**The tiering rule:**
|
||
|
||
| Tier | Where | What goes in it | Budget |
|
||
| --- | --- | --- | --- |
|
||
| **Hard rules** | `client/CLAUDE.md`, `server/CLAUDE.md`, root `CLAUDE.md` | Constraints whose violation breaks the build, the gate, or a business invariant. Stated imperatively, no explanation. | ~200 lines each |
|
||
| **Reference** | `docs/rules/{shared,client,server}/*.md` | The *how* and the *why*. Read on demand when working on that area. | ~200–400 lines per file |
|
||
| **Procedure** | `.claude/skills/` | Step-by-step playbooks for recurring tasks. **Phase 7** owns these. | — |
|
||
|
||
A rule that only matters when you are already editing theme code is **reference**, not a hard rule.
|
||
A rule like "never change `Seams:FieldEncryption:Key`" is a hard rule — it belongs inline.
|
||
|
||
---
|
||
|
||
## Inputs
|
||
|
||
Read these in full; they are the raw material:
|
||
|
||
| Source | Size | Contains |
|
||
| --- | --- | --- |
|
||
| [client/CLAUDE.md](../../client/CLAUDE.md) | 161 KB | 22 sections; lines 103–421 are a structure listing, 421+ is reference |
|
||
| [server/CLAUDE.md](../../server/CLAUDE.md) | 75 KB | 11 sections; lines 89–603 are the project map |
|
||
| [server/CONVENTIONS.md](../../server/CONVENTIONS.md) | 27 KB | naming, layering, CQRS shape |
|
||
| [client/messages/STYLE.md](../../client/messages/STYLE.md) | 8 KB | Persian copy rules (enforced by `lint:copy`) |
|
||
| [.claude/skills/frontend-designer/SKILL.md](../../.claude/skills/frontend-designer/SKILL.md) | 21 KB | brand, tokens, typography, component library, layout, icons |
|
||
| [dev/phases/_shared/agent-operating-rules.md](../../dev/phases/_shared/agent-operating-rules.md) | 13 KB | how agents were told to work |
|
||
| [dev/phases/_shared/definition-of-done.md](../../dev/phases/_shared/definition-of-done.md) | 3 KB | the gate |
|
||
| [dev/phases/_shared/backend-conventions-checklist.md](../../dev/phases/_shared/backend-conventions-checklist.md) | 4 KB | |
|
||
| [dev/phases/_shared/frontend-conventions-checklist.md](../../dev/phases/_shared/frontend-conventions-checklist.md) | 3 KB | |
|
||
| [dev/contracts/conventions/api-conventions.md](../../dev/contracts/conventions/api-conventions.md) | 3 KB | → **Phase 2 owns this**; read for cross-check only |
|
||
| [dev/contracts/conventions/money-and-types.md](../../dev/contracts/conventions/money-and-types.md) | 3 KB | → **Phase 2 owns this**; read for cross-check only |
|
||
| root [CLAUDE.md](../../CLAUDE.md) · 3× `AGENTS.md` · [.githooks/README.md](../../.githooks/README.md) | small | working agreements, pointers, the pre-commit hook |
|
||
|
||
Plus: `docs/_plan/inventory.md` and `docs/_plan/open-contradictions.md` from Phase 0.
|
||
|
||
## Outputs
|
||
|
||
```
|
||
docs/rules/
|
||
index.md what's here, and the tiering rule restated
|
||
documentation.md the anti-drift convention (Phase 7 adds the hook that enforces it)
|
||
shared/
|
||
naming.md Baya* vs balinyaar-client, @/* alias, file/dir conventions
|
||
git-and-gates.md branch, commit, pre-commit hook, what "done" means per project
|
||
code-quality.md no dead code, comment the why, no starter scaffolding
|
||
client/
|
||
structure.md the route/folder map (regenerated from reality, not copied)
|
||
theme.md tokens, palette, dark mode, RTL, fonts
|
||
components.md the App* library, when to reach for it vs raw MUI
|
||
forms.md react-hook-form (post-iteration-2), validation, field components
|
||
i18n.md next-intl v4, en/fa parity, STYLE.md copy rules folded in
|
||
services.md services/{domain} pattern, fetch layer, envelope, query keys
|
||
auth.md cookies, session state, refresh, RoleGuard, middleware/PUBLIC_PATHS
|
||
testing.md what is tested, how, the 125 existing tests
|
||
server/
|
||
structure.md the project map (condensed from server/CLAUDE.md lines 89-603)
|
||
cqrs.md how a feature is shaped: command/query/handler/validator
|
||
persistence.md EF Core, migrations, interceptors, the audit interceptor
|
||
identity.md JWE, sessions, rotation, field encryption, PhoneHash
|
||
conventions.md successor to CONVENTIONS.md
|
||
```
|
||
|
||
Rewritten in place: `CLAUDE.md` (root), `client/CLAUDE.md`, `server/CLAUDE.md`, 3× `AGENTS.md`.
|
||
Deleted after distillation: `server/CONVENTIONS.md`, `client/messages/STYLE.md` (content moves to
|
||
`docs/rules/client/i18n.md`; **check `lint:copy` doesn't read STYLE.md by path before deleting**).
|
||
|
||
---
|
||
|
||
## Steps
|
||
|
||
### 1. Extract every distinct rule into a ledger first
|
||
|
||
Before writing any output file, build a working list (scratch, not committed) of every *rule* found
|
||
across all inputs, tagged with: source file:line, scope (client/server/shared), tier
|
||
(hard/reference), and whether it is **contradicted or obsoleted** by another source or by the code.
|
||
|
||
This is the step that prevents loss. Merging by reading two documents side by side and writing a
|
||
third loses whatever was in neither's first half.
|
||
|
||
### 2. Reality-check the client rules against the post-overhaul code
|
||
|
||
`client/CLAUDE.md` and the frontend-designer skill both predate iterations 1–2 (commits `baa3cc6`,
|
||
`e6a8f93`). Those commits changed load-bearing things:
|
||
|
||
- **Mobile-scoped shell** — max-width container, no desktop sidebar for the nurse side
|
||
- **Bottom navigation** replacing the drawer, grouped root pages with domain summaries
|
||
- **Icon set replaced** wholesale
|
||
- **react-hook-form** for every form with >1 field (28 files currently import it — confirm coverage
|
||
and note any state-based forms left behind; that gap belongs in Phase 4's backlog)
|
||
- **Theme/language switches** moved into settings only, out of every top bar
|
||
- **Paper border-radius** reduced globally
|
||
|
||
Any rule in either document that describes the *old* behaviour is obsolete. Rewrite it against the
|
||
code, and log the correction in `docs/_plan/open-contradictions.md` as resolved.
|
||
|
||
Do the same, more briefly, for the server: `server/CLAUDE.md`'s "Project map" (514 lines) must match
|
||
the 14 `.csproj` projects and 56 controllers actually present.
|
||
|
||
### 3. Write the reference layer
|
||
|
||
One file per row of the Outputs tree. Each opens with a two-line purpose and a
|
||
`> Last verified: <date> against <commit>` line. Keep them under ~400 lines; if `client/structure.md`
|
||
wants to be longer, it is listing files it should be describing patterns for.
|
||
|
||
### 4. Rewrite the three CLAUDE.md files
|
||
|
||
Each becomes, in order:
|
||
|
||
1. One paragraph: what this project is.
|
||
2. **Stack** and **Commands** (keep — they are consulted constantly).
|
||
3. **Quality gates** — the exact commands that must pass.
|
||
4. **Hard rules** — a numbered list, imperative, no prose. Target 15–25 items.
|
||
5. **Where to read more** — a table mapping "working on X" → `docs/rules/…/X.md`.
|
||
|
||
Root `CLAUDE.md` keeps its "What Balinyaar is", "Repository layout" (updated for `docs/` and
|
||
`archive/`), and the working agreements — but agreement 7 ("keep the architecture map current") now
|
||
points at `docs/rules/` as well.
|
||
|
||
Rules that must survive into the hard-rule lists verbatim (do not soften):
|
||
|
||
- `Seams:FieldEncryption:Key` / `:HashKey` are load-bearing — changing them makes every PII read throw
|
||
and every phone lookup miss.
|
||
- Config lives in files, not a secret store — **`dotnet user-secrets` is not used and is not read**.
|
||
(This is the single most-repeated stale instruction in the repo; state it loudly.)
|
||
- Stay within one project per change.
|
||
- No dead code; the client fails the build on unused vars.
|
||
- Don't reintroduce starter scaffolding or `_TITLE_`/`_DESCRIPTION_` placeholders.
|
||
- Read `product/` before changing behaviour.
|
||
|
||
### 5. Rewrite the three `AGENTS.md`
|
||
|
||
They stay thin pointers. Update the paths they point at.
|
||
|
||
### 6. Write `docs/rules/documentation.md`
|
||
|
||
The anti-drift convention, as agreed:
|
||
|
||
- What to update when X changes (endpoint → `docs/integration/`; flow ships → `docs/flows/<flow>.md`;
|
||
backlog item closed → tick it in `docs/status/backlog.md`, never delete it; structure changes →
|
||
the matching architecture section).
|
||
- The `> Last verified: <date> against <commit>` header convention, and which docs must carry it.
|
||
- The one-home rule: `product/` = business, `docs/` = engineering + status, `archive/` = history.
|
||
- Length budgets, so this doesn't regrow.
|
||
|
||
Phase 7 adds the pre-commit warning that enforces the first bullet.
|
||
|
||
---
|
||
|
||
## Verification
|
||
|
||
- [ ] `client/CLAUDE.md` under 250 lines; `server/CLAUDE.md` under 250 lines.
|
||
- [ ] Every rule in the Step-1 ledger appears in exactly one output file — spot-check 20 at random.
|
||
- [ ] No rule describes pre-iteration-1/2 client behaviour.
|
||
- [ ] `grep -rn "user-secrets" client/ server/ CLAUDE.md docs/` returns only statements that it is
|
||
**not** used.
|
||
- [ ] `cd client && npm run check` still passes (in case `lint:copy` referenced `STYLE.md` by path).
|
||
- [ ] Both `AGENTS.md` pointer files resolve.
|
||
- [ ] Every contradiction Phase 0 logged in the rules domain is marked resolved with its resolution.
|
||
|
||
## Definition of done
|
||
|
||
An agent opening `client/CLAUDE.md` learns what it may not do in under 250 lines, and knows exactly
|
||
which one file to open next for the area it is touching.
|
||
|
||
## Handoff
|
||
|
||
**Run 2026-07-30 against commit `d3ec723`. Complete.**
|
||
|
||
### What shipped
|
||
|
||
| | Before | After |
|
||
| --- | --- | --- |
|
||
| `client/CLAUDE.md` | 1,098 lines / 158 K | **177 lines** |
|
||
| `server/CLAUDE.md` | 772 lines / 73 K | **184 lines** |
|
||
| root `CLAUDE.md` | 136 lines | **164 lines** |
|
||
| `server/CONVENTIONS.md` | 508 lines | **deleted** → `docs/rules/server/conventions.md` |
|
||
| `client/messages/STYLE.md` | 116 lines | **deleted** → `docs/rules/client/i18n.md` §4 |
|
||
| `docs/rules/` | 1 stub | **18 files, 3,486 lines**, every one ≤400 |
|
||
|
||
The cost of opening the client rules before editing client code went from ~40k tokens to ~5k: 177 lines of
|
||
hard rules plus one ~200-line reference file for the area you are in.
|
||
|
||
### Deviations from the plan, and why
|
||
|
||
1. **`docs/rules/server/money.md` is a 6th server file**, not in the Outputs tree. `persistence.md` came in
|
||
at 456 lines with the money content in it, over the 400-line budget this phase itself sets. Splitting the
|
||
money path out is the sanctioned response to overflow, and it is the most-consulted sub-topic on that
|
||
side — `persistence.md` is now 382 and `money.md` 244. Both `CLAUDE.md` and `rules/index.md` route to it.
|
||
2. **`docs/rules/shared/api-conventions.md` and `money-and-types.md` were not created**, though
|
||
`_plan/inventory.md:134–135` assigns them owner phase 1. The phase file (lines 38–39) says **phase 2 owns
|
||
those two contract files** and to read them for cross-check only, and `docs/README.md` puts the wire
|
||
contract in `docs/integration/`. The plan file is the more specific and later instruction, so it won.
|
||
**Phase 2 must therefore write `docs/integration/api-contract.md`** covering the envelope, status codes,
|
||
casing, pagination, idempotency keys, money-on-the-wire, enum codes, PII masking, and the Shamsi
|
||
`day_of_week` rule. `docs/rules/index.md` already points there and says so.
|
||
3. **`.claude/skills/frontend-designer/SKILL.md` was edited**, which the tree lists as phase 7's. C-11 could
|
||
not be resolved without stating precedence *in the skill*, and four of its factual claims were wrong
|
||
(R-3…R-5 in [open-contradictions.md](open-contradictions.md)). Only the design-language half was touched;
|
||
§8's workflow and §10's Figma section are untouched and still phase 7's.
|
||
|
||
### Also changed, to keep the tree consistent
|
||
|
||
- `AGENTS.md` ×3 — repointed at `docs/rules/`; still thin pointers (14 lines each).
|
||
- `client/scripts/check-copy.mjs` — its doc comment now names `docs/rules/client/i18n.md` §4 (it never read
|
||
`STYLE.md` by path, so the delete was safe; `npm run check` confirms).
|
||
- `server/README.md`, `server/.dockerignore` — dropped the `CONVENTIONS.md` references.
|
||
- `server/docker-compose.yml`, `client/.env.sample` — two live files still instructed `dotnet user-secrets`.
|
||
Neither was on C-1's list. Fixed.
|
||
- `docs/README.md` — `rules/` marked written.
|
||
|
||
### What the next phases inherit
|
||
|
||
| Phase | What phase 1 leaves it |
|
||
| --- | --- |
|
||
| **2** | Write `docs/integration/api-contract.md` (see deviation 2). Fix C-3's remaining half in `api-conventions.md`. The rules tree links to `docs/integration/index.md` and expects it to answer the wire contract. |
|
||
| **3** | C-1's one genuinely wrong live doc (`manual-testing-plan.md`) is still open — phase 1 fixed two other files it didn't know about. C-3's RUNBOOK half too. |
|
||
| **4** | **Six decisions need folding into `docs/status/decisions.md`** — the C-11 resolution and R-1…R-6, all recorded in [open-contradictions.md](open-contradictions.md) § Resolved, which is currently their only home. Also: `docs/rules/` links to `docs/status/backlog.md` for the 7 mock-blocking REQs and to `docs/status/` as the mock registry's new home. And one drift worth a backlog item: `client/src/services/payment/constants.ts` has `MOCK_PLATFORM_FEE_RATE = 0.12`, while refinement-phase-3 settled the canonical model at 0.15 — mock-only today, but it will lie on a checkout screenshot. |
|
||
| **6** | The `dev/`-lane handoff protocol (STATUS.md, `for-backend.md`, per-phase reports, the "save memory" step) was deliberately **not** carried into `docs/rules/` — the parallel-agent chain is finished. Its durable half (contract-first, record every mock) is in `documentation.md`. |
|
||
| **7** | Owns the pre-commit warning that enforces `documentation.md` §2, and the rest of the skill. C-12's non-design half is still open. |
|
||
|
||
### Verification
|
||
|
||
- [x] `client/CLAUDE.md` 177 lines, `server/CLAUDE.md` 184 — both under 250.
|
||
- [x] 20 ledger rules spot-checked for single-home placement; the 6 stale ones are gone from every file.
|
||
- [x] No rule describes pre-iteration-1/2 client behaviour (R-1…R-6 rewritten against the code).
|
||
- [x] `grep -rn "user-secrets"` over tracked `client/ server/ CLAUDE.md docs/` returns only statements that
|
||
it is **not** used (plus `_plan/`'s own descriptions of the contradiction).
|
||
- [x] `cd client && npm run check` passes — `check-copy: 2005 strings checked, 0 banned variants found.`
|
||
- [x] All 3 `AGENTS.md` resolve; a link check over all 27 new/changed markdown files found 0 broken links.
|
||
- [x] C-11 resolved with its decision; C-3 and C-12 marked partly resolved with what remains and to whom.
|
||
|
||
The Step-1 rule ledger (109 numbered rules across 11 groups, each tagged with source, scope, tier,
|
||
destination and state) was scratch by design and is not committed, per the phase brief. Its content is fully
|
||
represented in the output files; the six corrections and two count fixes it surfaced are recorded durably in
|
||
[open-contradictions.md](open-contradictions.md) § Resolved.
|