baya-monorepo/docs/_plan/phase-1-rules-consolidation.md

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	161 KB	22 sections; lines 103–421 are a structure listing, 421+ is reference
server/CLAUDE.md	75 KB	11 sections; lines 89–603 are the project map
server/CONVENTIONS.md	27 KB	naming, layering, CQRS shape
client/messages/STYLE.md	8 KB	Persian copy rules (enforced by lint:copy)
.claude/skills/frontend-designer/SKILL.md	21 KB	brand, tokens, typography, component library, layout, icons
dev/phases/_shared/agent-operating-rules.md	13 KB	how agents were told to work
dev/phases/_shared/definition-of-done.md	3 KB	the gate
dev/phases/_shared/backend-conventions-checklist.md	4 KB
dev/phases/_shared/frontend-conventions-checklist.md	3 KB
dev/contracts/conventions/api-conventions.md	3 KB	→ Phase 2 owns this; read for cross-check only
dev/contracts/conventions/money-and-types.md	3 KB	→ Phase 2 owns this; read for cross-check only
root CLAUDE.md · 3× AGENTS.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). 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 § 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

• client/CLAUDE.md 177 lines, server/CLAUDE.md 184 — both under 250.
• 20 ledger rules spot-checked for single-home placement; the 6 stale ones are gone from every file.
• No rule describes pre-iteration-1/2 client behaviour (R-1…R-6 rewritten against the code).
• 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).
• cd client && npm run check passes — check-copy: 2005 strings checked, 0 banned variants found.
• All 3 AGENTS.md resolve; a link check over all 27 new/changed markdown files found 0 broken links.
• 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 § Resolved.