adr-sml/CLAUDE.md

# CLAUDE.md — operating instructions for Claude Code

## Read this first

1. **`AGENTS.md` is the source of truth for this project.** Read it in full
   before your first edit in any session. It carries the locked decisions, the
   credential register, the open questions, and the full history.
2. **You are required to maintain `AGENTS.md`** under the constitution written at
   the top of it. Update *Current Truth* in place; append to the *Change Log*,
   newest first; never edit a past entry; never delete history. Record decisions
   and plans, not only executed work. Stamp facts `[verified YYYY-MM-DD]` or
   `[assumed]`.
3. Update it **at the end of every working session**, not only when something
   ships. A session that produced a decision and no code still produces a Change
   Log entry.
4. **Read `AGENTS.md` §12 Standing Reminders at the start of every substantial
   session and surface anything live to Pouya.** These are decisions he parked
   deliberately, not settled matters — R1 in particular is his explicit
   instruction to keep raising the licensure wording. A parked decision that
   stops being raised has quietly become permanent, which is the failure mode
   §12 exists to prevent.

## The one rule that matters more than the code

Pouya is a licensed legal professional. **No factual claim about him, his
credentials, his experience, or his practice may appear on a public page unless
it is in the Verified table in `AGENTS.md` §4.**

If a page needs a fact you do not have:

- Do not infer it from context.
- Do not soften it into something defensible ("extensive experience", "years of").
- Do not carry it over from the old site — the old site contained a fictitious
  founder, invented matter values, and a fabricated testimonial.
- **Leave `TODO(pouya): <the exact question>` in the source, and add the question
  to `AGENTS.md` §9.** A build that fails on an unanswered question is a correct
  build.

Read the Forbidden table in §4 before writing any statistic, number, or
superlative.

## How work is executed here

Pouya is the architect. He makes the decisions and hands you the task. **You
implement, then you adversarially review your own work before calling it done.**
This is the standing agreement — it applies to every substantial change without
being restated in the prompt.

**Run `/build <task>` for any substantive change.** It encodes the loop:

1. **Plan** — read `AGENTS.md` (including §12 Standing Reminders, and surface
   anything live), read the governing specs, name the decisions the task touches,
   and **stop and ask on any conflict**. A blocked build is a correct build.
2. **Implement** — following the conventions below.
3. **Adversarial review** — invoke `adversarial-reviewer` and `claims-auditor` in
   parallel on the diff.
4. **Resolve** — fix each finding or decline it with a stated reason. Re-review
   material fixes.
5. **Verify** — run the checks. Never report a check as passing that you did not
   run.
6. **Record** — append the `AGENTS.md` Change Log entry.

`/review` runs phase 3 alone. `/wrap` runs phase 6 at session end.

**Think deeply before acting.** Extended thinking is on by default for this
project (`.claude/settings.json`), and `/build` and `/review` request it
explicitly. The planning and review phases are where it earns its cost — a defect
reasoned out before implementation is far cheaper than one found after.

### Why the review is adversarial, and what would break it

Two rules make the difference between a review and a rubber stamp:

**Do not brief the reviewers on why your work is correct.** Give them the diff
and the specs, nothing else. Your rationale anchors them, and an anchored
reviewer produces agreement rather than review. They must form an independent
view from the artefact — that independence *is* the mechanism.

**The reviewers are instructed to treat uncertainty as a defect.** They will
sometimes be wrong, and that is the intended trade. Explaining why a finding is
mistaken costs minutes; a missed defect on a licensed professional's public
marketing page costs considerably more. Do not read a finding as an accusation,
and do not argue a reviewer down — either fix it, or record the reason you
declined it so a later reader can see the judgement was made rather than missed.

**Two reviewers, because they catch different things.** `adversarial-reviewer`
reads the code. `claims-auditor` reads the copy against the §4 register and knows
nothing about whether the code is elegant. A generic reviewer consistently
under-weights the professional-conduct check, which is the highest-stakes failure
mode on this project — so it gets its own pass.

## Commands

```bash
npm install
npm run dev        # local dev server
npm run build      # static build to ./dist
npm run preview    # serve ./dist locally
npm run check      # astro check — type and template errors
npm run lint       # eslint + prettier check
```

## Where things live

```
AGENTS.md              living project record — read first, maintain always
docs/                  the specs you build from
  01-architecture.md   sitemap, URL map, per-page content outline
  02-design-system.md  tokens, type scale, motion, contrast constraints
  03-content-spec.md   voice, copy rules, per-page copy deck
  04-seo-spec.md       metadata, structured data, sitemap, crawlability
  05-backend-spec.md   intake form, Lambda/DynamoDB/SES, booking, PIPEDA
  06-deployment.md     S3/CloudFront, GitHub Actions OIDC, cutover checklist
src/
  styles/tokens.css    design tokens — the single source of colour and scale
  styles/global.css    reset, base type, utilities
  layouts/             page shells
  components/          UI components
  pages/               routes (file-based)
  content/             content collections; Insights MDX lives here
  data/site.ts         site-wide constants, nav, contact details
public/                static assets served as-is
```

## Conventions

**Framework.** Astro, `output: 'static'`. Never introduce a server runtime
without a Change Log entry recording why.

**JavaScript.** Default to zero. Reach for an Astro island only when a feature
genuinely cannot be CSS or progressive HTML. If you add a `client:*` directive,
say why in the Change Log. A `<details>` element beats a JS accordion.

**Styling.** Plain CSS with custom properties. No Tailwind, no CSS-in-JS, no
utility framework. Every colour, space, and font size comes from a token in
`tokens.css` — no raw hex values and no magic numbers in component styles.

**Accessibility is a build requirement, not a polish pass.** Semantic landmarks,
one `<h1>` per page, heading levels never skipped, visible focus states, all
interactive elements reachable by keyboard, `prefers-reduced-motion` honoured on
every animation. Gold `#c9a876` never sits on cream — it fails contrast at
2.10:1. See `docs/02-design-system.md`.

**Images.** Astro `<Image>` with explicit width and height. AVIF/WebP with
fallback. Never base64-inline an image into HTML — the old site did this with
~1 MB of logo PNGs.

**Fonts.** Self-hosted, subset, `font-display: swap`, preloaded. No Google Fonts
request at runtime — it costs a round trip and adds a third-party call to a
page that collects legal inquiries.

**Every page ships with:** a unique `<title>` and meta description, a canonical
URL, Open Graph and Twitter card tags, and appropriate JSON-LD. See
`docs/04-seo-spec.md`. A page without these is not finished.

**Commits.** Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`).
One logical change per commit. Never commit secrets, `.env` files, or AWS
credentials — deploys use OIDC role assumption.

**Performance budget.** Lighthouse ≥ 95 on all four categories, on mobile, for
every page. Under 100 KB of JS on any route. LCP under 2.0 s on a simulated
Slow 4G connection. Treat a budget breach as a failing build.

## What "done" means for a page

- [ ] Copy written from `docs/03-content-spec.md`, every claim traceable to `AGENTS.md` §4
- [ ] No `TODO(pouya)` left unlogged in §9
- [ ] Unique title, meta description, canonical, OG/Twitter tags, JSON-LD
- [ ] Semantic HTML; keyboard navigable; reduced-motion honoured
- [ ] Lighthouse ≥ 95 mobile, all four categories
- [ ] Renders correctly with JavaScript disabled
- [ ] `AGENTS.md` Change Log entry appended