Add report-only SME review gate (editorial + SME dual review)

[anegg0]

Description

Adds a report-only SME review gate so technical doc PRs can require both an editorial (Technical Writing) and a technical (SME) approval, with authors tagging just the parts that need SME eyes.

This PR is advisory only — it blocks nothing when merged. It publishes a sme-review-gate check that reports which SME team(s) a PR needs and whether they've approved. Turning it into an actual merge gate is a separate, admin-owned step (per-domain SME teams + a members:read token + a branch ruleset) documented in .github/SME_REVIEW_GATE.md.

SME tags are transient. After a PR merges to master, a cleanup workflow strips the {/* sme:* */} markers it introduced (committing to master as a bypass bot), so tags are per-PR signals rather than durable content. Always-on protection for whole technical sections still comes from the path globs in .github/sme-config.json.

What's included:

• .github/workflows/sme-review-gate.yml — runs on pull_request_target (fork-safe) + pull_request_review + workflow_dispatch; checks out only the trusted base and reads PR content over the API (never executes PR code).
• scripts/sme-review-gate.ts — maps the PR diff to required SME teams via {/* sme:start team=… */} region markers and a technical-path fallback, then checks team approvals. Report-only → neutral; enforcing → success / failure / action_required.
• scripts/sme-markers.ts — single source of truth for the marker regexes, imported by both the gate (detection) and the stripper (removal) so they can't drift.
• scripts/strip-sme-markers.ts (+ scripts/strip-sme-markers.test.ts) — pure stripMarkers() + a CLI (--all sweep or explicit file list). Run via yarn test:sme.
• .github/workflows/sme-marker-cleanup.yml — post-merge (pull_request_target: closed, merged) workflow that strips markers from master via a bypass bot (SME_CLEANUP_TOKEN). Direct commit, not a PR, so it can't loop.
• .github/sme-config.json — SME team → path map (pilot sections).
• .github/CODEOWNERS — auto-requests TW + per-domain SME reviewers (routing only).
• .github/rulesets/docs-review-gates.json — importable ruleset for admins.
• .github/SME_REVIEW_GATE.md — operator runbook (enable steps + transient-cleanup token + sandbox smoke-test).
• scripts/sme-gate-sandbox.sh — sandbox harness (--bootstrap installs the gate and the cleanup workflow into a sandbox repo; default mode opens a test matrix; closing notes show how to verify cleanup).
• README + CONTRIBUTE + PR-template guidance for the {/* sme:start … */} convention, including that tags are transient/single-line.

Document type

• Codebase changes

SME review

• No content here needs SME review (editorial only) — this PR is tooling, not docs content.

Checklist

• I have read the CONTRIBUTE.md guidelines
• My changes follow the style conventions
• I have tested my changes locally (yarn test:sme, actionlint, shellcheck/shfmt, gate dry-run, MDX-marker compile, and an end-to-end run in a sandbox repo)
• My code follows the existing code style and conventions

How reviewers can test this

The gate is report-only, so trying it is risk-free. Pick any of:

1. Stripper unit tests (no setup):

yarn test:sme

Six node:test cases covering marker removal (marker-only lines, shared-line content, reason= attributes, multiple regions, no-op, unbalanced markers).

2. Local gate dry-run against any open PR:

GH_TOKEN="$(gh auth token)" yarn tsx scripts/sme-review-gate.ts --pr <PR_NUMBER>

Try a PR that touches docs/stylus/** or docs/how-arbitrum-works/** — the gate should report the matching SME team via the path fallback. (Teams show as unverifiable until the SME teams + SME_GATE_TOKEN exist — that's expected report-only behavior.)

3. Region markers + cleanup CLI: add a block like the following to an .mdx file in a scratch PR, then run the dry-run above against it — the gate should require stylus-sme even if the file isn't under a technical path:

{/* sme:start team=stylus-sme reason="testing" */}
…technical content…
{/* sme:end */}

Then confirm the stripper removes it: yarn tsx scripts/strip-sme-markers.ts <that-file> leaves the content but deletes the marker lines. A malformed marker (unbalanced, or unknown team) reports action_required.

4. Real CI + the full matrix: the gate is installed in the sandbox repo OffchainLabs/arbitrum-docs-gate-sandbox, where four matrix PRs (editorial-only, path-fallback, region-tag, malformed-marker) have run under pull_request_target. Re-run with scripts/sme-gate-sandbox.sh --repo OffchainLabs/arbitrum-docs-gate-sandbox.

5. MDX safety: the markers compile to a bare JS comment and don't break the build (yarn build).

Additional Notes

• Design + usage overview: Notion "Solving TW's PR Bottleneck Issue". Admin enablement (incl. the SME_CLEANUP_TOKEN cleanup bot + bypass) + sandbox steps: .github/SME_REVIEW_GATE.md.
• The fatal TS5101 (baseUrl) tsconfig fix was split into its own PR (Silence TS5101 baseUrl deprecation in tsconfig #3354) so this PR stays feature-only. Related: yarn typecheck still has ~80 pre-existing repo-wide type errors (previously masked by the TS5101 abort); cleaning those up is out of scope here. The gate/stripper scripts themselves are exercised by yarn test:sme and the gate dry-run.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
arbitrum-docs	Ready	Preview	Jun 17, 2026 3:36am