Pouya/adr-sml

Fork 0

Files

T

Pouya LajevardiandClaude Opus 5 9f2d2eeb04

Build and deploy / build-and-deploy (push) Failing after 4s

Details

fix: resolve adversarial review round 2 — 9 findings, 8 of them in round 1's fixes

D19 caps the loop at two rounds, and this is what the second round is for.

BLOCKING. Round 1 made NO_RETAINER_NOTICE a requireEnv and added it to no
document, while the fix's own comment claimed docs/06 named it. The deployment
list said five variables for a handler that needs six, so an operator following
the cutover checklist would have deployed a function that throws at cold start
on every invocation — 5xx from API Gateway, every inquiry lost from the moment
/api/* was wired, loud in CloudWatch and silent to Pouya. docs/05 and docs/06
now name all six, and the comment that asserted the documentation existed is
corrected rather than deleted.

The intake route check added in round 1 could not fail: curl -w already prints
000 on a failed transfer, so `|| echo 000` double-appended and the failure arm
was unreachable, and the pass arm accepted anything that was not literally 404 —
including the 403 CloudFront returns when the /api/* behaviour is missing, which
is the one distinction the check exists to draw. It now sends the correct Origin
and asserts a positive: 303 to /contact/could-not-send/, which the handler
returns before any DynamoDB write or email. Probed on refused/501/403/303; the
old version passed the first three. Fixed in both deploy paths.

Removing priceRange left three statements saying it was present or pending, one
of them the stated reason /fees/ emits no Offer node. Deleting
overtimeStartsAfterSessionHours left AGENTS.md §9 naming it and left Q59
recorded as open. The Google-as-processor fix was applied to the privacy
policy's "Where it is stored" and not to "Who can see it", which still read
"Nobody else has access".

And the variable removal was justified with a path-scoped git grep — which also
cannot see untracked files. The unscoped sweep found docs/06's variable table,
the OIDC example, and .env.example still carrying them; .env.example also
restates the execute-api hostname, falsifying a live claim in intake.ts that has
been corrected. That file is not edited here: this environment denies read
access to it, and nothing may edit a file it cannot read. It is in the batched
list.

Also: og:image:alt was the page title rather than the card's headline on 20
pages; og-card.ts documented the wrong path and invocation for the contact
sheet; deploy-local.sh still said Q22's deploy credential "does NOT yet exist";
and the round-1 fix comments were trimmed per D19, though the ratio held at 0.44.

Round 2 also confirmed the round-1 fixes by measurement: all 56 .btn instances
across 22 pages, the consent checkbox's computed accessible name, the radio
labels hit-tested at 44px, and og:proof exercised against synthetic article
pages in a sandbox.

Verified: check/build/check:claims/og:proof/check:intake/lint/bio:pdf all exit 0
on a clean build; 22 pages; Lighthouse 99-100 / 100 / 100 / 100, CLS 0.000.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Md3GndFqWPzK78xAoebsg5

2026-08-31 11:21:07 -04:00

18 KiB

Raw Blame History

04 — Discoverability

The problem this project exists to fix. AGENTS.md §2 has the measurements.

Those measurements are under review — AGENTS.md Q34. They were taken on 2026-08-25; a re-fetch on 2026-08-26 returned a bundler harness whose real <head> sits JSON-escaped inside a <script> and whose application lives in nine UUID-named files that were not fetched. Some of §2 reproduced exactly (the 2.2 MB single file, the placeholder <title>); some could not be reproduced from the served HTML at all. Cite §2, and cite Q34 with it. Do not put any of these figures in public copy until Q34 closes.

The baseline being replaced

	Now `[verified 2026-08-25]`	Target
Content in server HTML	`SML Company · DISPUTE RESOLUTION · Unpacking...`	Every word
Indexable pages	1	17 + articles (19 fixed URLs, less the two `/legal/*` pages, which are `noindex` and excluded from the sitemap)
`<title>`	`SML Company · Dispute Resolution` — pre-rebrand placeholder	Unique per page
Meta description	none	Unique per page
`<meta viewport>`	absent	Present
Canonical URL	none	Every page
OG / Twitter tags	none	Every page
Structured data	none	Person, ProfessionalService, Article, FAQ, Breadcrumb
`robots.txt`	403	Served
Sitemap	none	Generated at build
Favicon	none	Full set

Astro's static output solves most of this by existing. The rest is the spec below.

Why static output matters more than usual here

Google can sometimes render client-side JavaScript. Bing largely does not. LinkedIn's preview crawler does not. Slack's unfurler does not. And the crawlers behind AI assistants — increasingly how counsel and in-house teams find a neutral — generally do not.

A site that requires three CDN round trips and an in-browser Babel compile before producing a sentence is invisible to all of them. That is the whole argument for D1.

Metadata

Every page passes through one SEO component. A page without it is not finished.

title            50–60 chars, unique. Pattern: "<Page> · Pouya Lajevardi".
                 `/` composes its own from the constants — `SITE.name` +
                 `SITE.tagline` — rather than a literal, so the masthead and
                 the title cannot drift. This spec carried the literal with an
                 ampersand after the composition shipped with interpuncts;
                 cite the constants, do not restate them (AGENTS.md §7 rule).
                 ARTICLES ARE THE EXCEPTION: no " · Pouya Lajevardi" suffix.
                 The suffix is 18 chars, so a headline that already reads
                 50–60 renders at 68–78 — over this ceiling. Measured against
                 the five launch headlines in 03-content-spec.md, the suffix
                 rule fails 5 of 5; without it, 4 of 5 pass. An article's
                 headline IS its <title>; `seoTitle` in the frontmatter
                 overrides it when a headline that reads well is out of range.
                 src/content.config.ts enforces this and names the offending
                 string and its length in the build error.
description      140–160 chars, unique, written for a human, not stuffed
canonical        absolute, https, trailing slash
og:title/description/image/url/type/site_name/locale  (en_CA)
twitter:card     summary_large_image
robots           index,follow — except /legal/* which is noindex,follow

OG images: 1200 × 630. Never a screenshot.

RULED 2026-08-27 (AGENTS.md Q40, R15) — TWO kinds of card, not one, and the generator is deferred to build step 7. This spec said "one template" for all nineteen pages. Pouya split it:

"A portrait is the right OG image for / and /about/ — a face is the strongest social preview for a personal brand. It is the wrong one for nineteen pages, where a typed card carrying the page title would do the work.

But do not build the generator now and do not leave 'portrait everywhere' as an untracked interim. Ship it at step 7 alongside Insights, which needs per-article cards anyway — one build, one dependency, one review."

So:

Pages	Card
`/` and `/about/`	The portrait crop, `src/assets/og-portrait.jpg`. Not an interim — the decided answer. Resolved from `PORTRAIT_PAGES` in `src/data/og-cards.ts`, not from a per-page prop
Every other page	Generated at build by `src/pages/og/[...slug].jpg.ts` from `satori` + `sharp`, in the site's own type and palette: display headline on cream, infinity mark, designation line
Each article	Per-article card from the same endpoint — the reason the two jobs were one build

✅ BUILT — step 7b, 2026-08-31. R15 IS DISCHARGED. satori@0.33.4 was chosen over astro-og-canvas@0.13.0 (both 0 vulnerabilities, verified that day): sharp is already a dependency to rasterise satori's SVG, so it adds one library rather than a CanvasKit wasm blob, and it renders with this site's own fonts and tokens rather than approximating them.

Four things about the implementation are load-bearing and are not style choices. Each is recorded because a later reader would otherwise "tidy" it:

Colours are parsed out of src/styles/tokens.css at build time, not copied into the generator. CLAUDE.md requires every colour to come from a token; the alternative was a duplicated hex table, which is the SES-DKIM shape. A missing token throws rather than falling back.
The fonts are @fontsource's static .woff cuts, not public/fonts/. satori parses TTF/OTF/WOFF and not WOFF2, and decompressing the site's own subset variable Geist to TTF throws inside satori's opentype.js fork — Fontsource's subsetting drops the name records the fvar table points at. Same typeface, same upstream version, same weight; build-time only.
Every card's headline is its page's own <h1>, character for character, and npm run og:proof enforces it against the built HTML. This is a compliance mechanism, not a convenience: text baked into a JPEG cannot be grepped by npm run check:claims, which under D20 is the only per-step claims control there is. A card must not carry a claim its page does not already make in auditable HTML. The same check confirms every page's og:image resolves to a file that exists — a 404 preview is invisible from inside the repo.
A page with no card entry is a BUILD ERROR, not a fallback to the portrait. R15's failure mode was never the wrong image; it was the wrong image shipping invisibly and reading as intentional. A silent fallback recreates it exactly.

Structured data

JSON-LD only. Validate against Google's Rich Results Test before cutover.

Type	Where	Notes
`Person`	`/about/`, referenced site-wide	Emitted: `name`, `url`, `jobTitle`, `description`, `alumniOf` (Bond University), `knowsLanguage` (en, fa), `hasCredential` (Q.Med, Q.Arb — both, since 2026-08-29), `sameAs` (LinkedIn), `email`, `image`. Emitted on `/about/` only: `memberOf` — the four §4 memberships as `Organization` nodes (Q53, ruled 2026-08-28). `/` shows no memberships, so its Person node omits it: structured data represents the page it sits on. Withheld: `worksFor` — Q49(b) declined the row 2026-08-28 and Pouya confirmed the reading 2026-08-29, so it is settled rather than pending; `provider → Person → worksFor` would assert a same-entity claim §4 does not row. (This enumeration listed `worksFor` as emitted while the same cell said it was withheld, and omitted `url` and `email`, which are — wrong in both directions. The enumeration is the part an implementer copies. Found by `adversarial-reviewer`.) CHANGED 2026-08-28 — Q47. This row read "`jobTitle` = 'Director of Firm Operations'; omit `worksFor`", which put the boutique title on a node whose `url` is this ADR practice's `/about/` — so a consumer could attach it to this entity. Pouya's ruling reframes the field: `jobTitle` describes this practice, not the boutique role, which D16 keeps unnamed. The visible role line is unchanged and still reads "Director of Firm Operations at a Toronto litigation and ADR boutique". THE VALUE IS `PRACTICE_JOB_TITLE` IN `src/data/site.ts` AND THIS ROW DOES NOT RESTATE IT — §7's rule, applied to a string with a live revert trigger on it: this row carried the literal text for one pass, and `adversarial-reviewer` noted it would go stale the moment the constant moved. Cite, do not copy. `worksFor` IS WITHHELD — set for one pass under Q47, then reverted: `ProfessionalService.provider` is this Person, so `provider → Person → worksFor` asserts the same-entity claim `schema.ts` explicitly declines, and §4 says "alongside the practice" where the ruling says "operates through". `memberOf` is emitted — see the sentence above; Q53 closed 2026-08-28. (This cell asserted `memberOf` was both emitted and withheld for one pass, which is the defect it already records itself being caught for on `worksFor`, in the opposite direction. The enumeration is the part an implementer copies.) See `src/data/schema.ts`
`ProfessionalService`	Home	`areaServed` Toronto/Ontario, `serviceType` Mediation / Commercial arbitration / Mediation-arbitration (med-arb) — scoped 2026-08-28 on `claims-auditor`'s finding; this row instructed the unscoped class form "Mediation/Arbitration" that Q39 struck and that `schema.ts` deliberately does not follow. Family arbitration carries prescribed training and has its own NOT OFFERED row, so unscoped "Arbitration" is the struck universal in a field nobody reads. Do not widen these strings without a §4 row to widen them from — `provider` → Person, ⚠️ *`priceRange` DECLINED 2026-08-31 — this row said "once `/fees/` is real", the page became real at step 9, the field went in, and it came out the same day.* Its own defence rejected a `min`/`max` over `FEES` because "a range whose ends mean different units is a range that misinforms" — and the ends it chose had different units too: the floor was the hourly rate, the ceiling a flat documents-only fee. The floor misinformed in the direction that matters, because the least anyone pays for the headline service is $2,000. Nothing on the site states a price in machine-readable form, and no `Offer` node either: every figure on `/fees/` is conditional on session length, party count or format, and schema.org's `Offer` models one price for one item. This row gates the field; it does not require it. Never `LegalService` — schema.org defines it as a business providing legal advice and representation, which asserts in machine-readable form exactly what D13 bars and §4 Forbidden calls out
`Service`	`/mediation/`, `/arbitration/`, `/med-arb/` and each practice page	`serviceType`, `provider` → Person, `areaServed`. The Person node travels in the same `@graph` so `provider: {'@id'}` resolves in one document rather than relying on a crawler joining two — `homeGraph`'s reasoning, applied. `serviceType` is scoped where §4 scopes it: Commercial arbitration, never a bare "Arbitration". No `BreadcrumbList` on the three — one hop from the root, no visible breadcrumb, and this spec requires the markup to match the visible one
`Article`	Each article	`headline`, `description`, `datePublished`, `dateModified`, `author` → Person, `image`
`BreadcrumbList`	All nested pages	Matches visible breadcrumbs
`FAQPage`	`/for-parties/`, `/med-arb/`	Only where the visible page genuinely is Q&A. Never fabricate questions to farm a rich result

hasCredential must reflect reality. ⚠️ Q.Med AND Q.Arb are both held as of 2026-08-29 (AGENTS.md §4) and the field carries both — it was Q.Med-only while Q.Arb was a commenced pathway. The rule is unchanged and cuts both ways: marking an unheld credential as held is a misrepresentation that happens to be machine-readable, and omitting a held one understates the record in a field whose whole meaning is "holds". personNode maps CREDENTIALS.designations rather than indexing it, so a designation added to that constant reaches the graph automatically. That links the CONSTANT to the graph, not §4 to the graph — a designation added to §4 and not to src/data/site.ts still drifts silently, and no mechanism catches it. src/data/schema.ts states the condition in full; this sentence overstated it for one pass.

Crawlability

public/robots.txt is the artefact — read it, do not read a copy of it here. This spec used to reproduce the file inline and the reproduction had already drifted from it by 2026-08-26, which is the failure mode the AGENTS.md §7 rule exists to stop.

It disallows nothing, and that is deliberate. This spec previously prescribed Disallow: /legal/ alongside noindex on those pages, and the two cancel each other: a crawler forbidden to fetch a URL never reads the noindex on it. /legal/privacy/ and /legal/terms/ are linked from the footer of every page, so they are discovered regardless — and the likely result of the pair was Google listing the bare URLs as "no information available", the opposite of the intent, with the directive that would have suppressed them sitting unread behind the wall. noindex is what de-indexes; Disallow is what prevents fetching. Use the one that matches the problem, and never both on the same path.

Do not block AI crawlers. Being read by an assistant that a general counsel is using to shortlist neutrals is the point.

Sitemap: @astrojs/sitemap, excluding /legal/* and any draft: true article. Submit to Google Search Console and Bing Webmaster Tools at cutover.

Internal linking. Every practice page links to /mediation/ and /arbitration/; those link back to the practice areas; every article links to at least one practice page. This is what turns Insights into ranking power for the pages that convert. Breadcrumbs on every nested page.

404 page. Real, styled, with search-intent links out. CloudFront must return it with a genuine 404 status — not a 200, which the S3 website-endpoint pattern gets wrong by default.

Performance

Core Web Vitals are a ranking input, and the current build fails all of them.

Metric	Budget
LCP	< 2.0 s, Slow 4G
CLS	< 0.05
INP	< 150 ms
JS per route	< 100 KB
Lighthouse (mobile)	≥ 95 all four categories — measurable again as of 2026-08-31, see below

✅ THE INSTRUMENT IS BACK — build step 7a, 2026-08-31. npm run lighthouse, and it is lighthouse rather than @lhci/cli. R11's re-add trigger said to put @lhci/cli back; this is a deliberate deviation from its literal wording and AGENTS.md §7 records both the reason and what it costs.

The reason is that §7's advisory attribution was wrong, and it was the attribution that made the tool look unusable. §7 recorded the ten findings as arriving "via lighthouse → puppeteer-core → extract-zip". Measured from two probe lockfiles: @lhci/cli@0.15.1 carries 10 (7 high) and pins lighthouse 12.6.1, and the two high carriers are tmp@0.1.0 — its own direct dependency — and extract-zip@2.0.1 via @puppeteer/browsers. lighthouse@13.4.1 standalone is 109 packages, and both are absent: npm audit returns 0. So Lighthouse was never the carrier, and the budget was unmeasurable for five days on a cause nobody re-derived.

What it does not do: run in CI. Standalone Lighthouse drives an installed browser and the Gitea runner has none (§7, Q23). So it is a local gate plus a blocking item on docs/06's cutover checklist, and it is deliberately not wired into npm run build or either deploy path — a check described as running where it cannot is the defect Q22 turned out to be.

⚠️ THE ACCESSIBILITY CATEGORY IS MEASURED WITH prefers-reduced-motion FORCED, and that is a deviation that has to travel with the number. Measured twice per condition on /process/: motion on gives 96 with color-contrast failing on 24 nodes; motion off gives 100 with 0. The 24 were the scroll-driven reveal caught mid-flight — axe reported foregrounds like #d0cbc4 on #f8f4ed, and neither is in this palette; they are the real colours blended toward the background by an in-progress opacity keyframe. A category reporting 24 known-false nodes on ten of fourteen pages cannot surface the twenty-fifth real one. The reduced-motion rendering is the branch global.css ships for a real user setting, and it is the one where every element sits at its final colour. Palette ratios are computed in docs/02-design-system.md; scripts/lighthouse.mjs carries the measurement.

How: static HTML, self-hosted preloaded subset fonts, AVIF/WebP with explicit dimensions, critical CSS inlined, no third-party scripts on any page except the booking embed on /contact/ — and that one is lazy-loaded behind a click.

Local and professional presence

Not code, but it belongs in the launch checklist: Google Business Profile for the practice; ADRIC and ADRIO directory listings pointing at the site; a LinkedIn profile whose headline and Featured section match the brand (brief §VIII); consistent naming across all of them. Not "name, address and phone" — §4 publishes no phone number and no street address, only "Toronto, Ontario; by appointment". Directory forms that demand a full NAP get what §4 verifies and nothing more.

Post-launch verification

curl -s https://adr.smlcompany.ca/ | grep -c "<h1" returns ≥ 1
Every page renders its full text with JavaScript disabled
Rich Results Test passes on Person, ProfessionalService, Article
OG preview renders correctly in LinkedIn Post Inspector and Slack
Sitemap submitted to Google Search Console and Bing
No page returns 200 for a URL that should 404
Lighthouse ≥ 95 mobile on every built page — npm run lighthouse, which enumerates dist/ rather than taking a list, so the set cannot go stale as pages are added. Do not tick this box from a manual Chrome DevTools run and call it the same check

18 KiB Raw Blame History Unescape Escape