docs: require branches up-to-date before merge (strict status checks, #2021)

[sajclarke]

What

Documents option 1 from #2021 — the primary recommended fix — in CLAUDE.md and the trunk-based playbook (docs/trunk-based-development.md): the Main CI Required ruleset runs status checks in strict mode, so a branch must be up to date with main before it can merge, re-running the required checks against the latest trunk.

Why (addresses #2021)

main went red on the required Validate Recipes check for every open PR (incident #2017), yet no single PR "failed" — the break emerged from the combination of two individually-green PRs:

1. fix(forms): align CMS reference with submission reference for youth forms (#841) #1875 added recipes with placeholder webhook env refs (green — the lint didn't exist yet).
2. Per-form webhook destinations: fail-loud + guardrails (#1920, phase 1) #1970 added the lint that rejects them (green — its checks were not re-evaluated against fix(forms): align CMS reference with submission reference for youth forms (#841) #1875's recipes already on main).

Strict status checks force that re-run at merge time, catching this class of break. #2030 already added the post-merge push run on main (option 2) as the fast-visibility backstop; this PR documents the strict-mode policy that complements it.

⚠️ Required companion action (repo admin)

The ruleset toggle itself is a repo setting, not code, and requires admin permission (the PR author has maintain only). This PR documents the intended policy — a repo admin must flip it for the docs to be true:

Settings → Rules → Rulesets → Main CI Required → Require status checks to pass → enable "Require branches to be up to date before merging" (i.e. strict_required_status_checks_policy: true on the required_status_checks rule).

Until that toggle is flipped, #2021 is not fully resolved — hence Refs, not Closes.

Scope

• Docs only. No code/CI behavior change in this PR.
• Option 2 (post-merge push trigger) already merged in ci: re-validate trunk with a push trigger on main #2030.

Refs #2021

🤖 Generated with Claude Code

[amazon-inspector-n-virginia]

⏳ I'm reviewing this pull request for security vulnerabilities and code quality issues. I'll provide an update when I'm done

[amazon-inspector-n-virginia]

✅ I finished the code review, and didn't find any security or code quality issues.

[github-actions]

Amplify PR previews

App	Status	URL
forms	⏭ Not affected	—
landing	⏭ Not affected	—
chat	⏭ Not affected	—
form-builder	⏭ Not affected	—
analytics	⏭ Not affected	—

Commit: e3d60dd · Branches auto-delete when this PR closes.

ℹ️ feature-flagging uses a single shared preview slot at a fixed URL (preview.feature-flagging.sandbox.alpha.gov.bb) — GitHub login works, but only one FF preview exists at a time (the most recent FF PR build wins). It reads/writes sandbox flag data.

[sajclarke]

The strict-mode ruleset toggle documented here requires admin and is tracked separately in #2040 (assigned to @LaronGovT and @RootUserChris). Once that toggle is flipped, the policy described in this PR is fully enforced.