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

(filled in by the agent that runs this phase)