Governance

Governance

CI gates — merge-blocking, in this order

1. Typecheck (tsc --noEmit) and lint (ESLint + Stylelint per tooling).
2. Unit + story tests (Vitest incl. Storybook Vitest addon), with a11y violations at serious/critical failing.
3. E2E on critical paths (Playwright) + axe scan spec.
4. Dependency audit — high + critical block.
5. Secrets scan (gitleaks or equivalent) — any finding blocks.
6. License check — denied license blocks (policy below).
7. Bundle-size budget check (size-limit or Lighthouse CI).
8. Security-review (Semgrep heuristics in templates/.semgrep/ for webhook-missing-verification, SSRF, secret exposure, and unsanitized HTML; zod-at-boundary and IDOR have no reliable static rule and stay review-only).

Classify the deliverable first: production app, component/library package, static content site, prototype, or policy/docs repository. The gates above are mandatory for a production app; for other types, mark a gate NOT APPLICABLE only with a concrete reason (for example, no client bundle or no browser journey). A missing applicable gate is NOT CONFIGURED and blocks merging; it is not a pass. Temporary exceptions record reason, owner, expiry, and human approval. Starter configs implementing these gates (CI workflow, gitleaks, ESLint, Stylelint) live in templates/ — copy and adapt them rather than authoring from scratch.

Toolchain pinning

• Node: engines in package.json + .nvmrc (same version); CI uses the same pin.
• Package manager: packageManager field + corepack; enforce a single PM with only-allow in preinstall. Never mix lockfiles.

Dependency lifecycle

• Updates via Renovate/Dependabot: grouped, with a minimum release age of 3 days (cooldown) so freshly-published compromised versions don't auto-merge. Break-glass: a fix for a known exploited/critical CVE may bypass the cooldown with a named approver's sign-off recorded on the PR.
• Emit an SBOM (CycloneDX) in CI for release builds.
• Pin GitHub Actions (and other CI plugins) by commit SHA; pin CI container images (e.g. the Semgrep job's semgrep/semgrep) by digest (@sha256:…), not a floating tag.
• Add-time vetting rules live in frontend-security (install scripts, typosquatting, registry pinning).

License policy

• Allowed for shipped frontend code: MIT, Apache-2.0, BSD-2/3-Clause, ISC, 0BSD.
• A real framework tree (Astro/Vite) also legitimately carries permissive-but-unlisted licenses: CC0-1.0 and CC-BY-4.0 (data packages like caniuse-lite), Python-2.0 (argparse), BlueOak-1.0.0 (lru-cache, sax). These are non-copyleft — add them to the allowlist rather than failing the gate. Run license-checker --summary FIRST when the gate goes red: --onlyAllow stops at the first offender, so a bare allowlist turns license triage into whack-a-mole.
• Self-application: this rules repo itself is MIT-licensed (LICENSE) — the policy it demands of dependencies holds for its own artifact.
• Denied: GPL/LGPL/AGPL, SSPL, BUSL, unlicensed/unknown. Anything else: ask before adding.
  • Carve-out (named legal/human sign-off, per case): LGPL is acceptable ONLY for a prebuilt shared-library binary that is dynamically used and never enters the shipped bundle — e.g. @img/sharp-libvips-* pulled in by Astro's image tooling. Exclude it explicitly (--exclude "LGPL-3.0-or-later") with an in-file comment naming the package and reason; LGPL in shipped, statically-linked code stays denied.
• Exclude your own private root package (--excludePrivatePackages) — it reports as UNLICENSED and is not a third-party dependency.
• Enforce in CI (license-checker / FOSSA / Snyk). Dev-only tooling may be reviewed case-by-case, but default to the same list.

Secrets scanning

• gitleaks (or equivalent) in pre-commit AND CI; enable push protection on the hosting platform.
• A detected leak = rotate immediately, then purge; rotation is the fix, history rewriting is cleanup.

Change control — the rules themselves

• The privileged instruction paths enumerated under "Sensitive paths" below can silently change every AI agent's behavior. Protect that complete set with CODEOWNERS requiring platform/security-team review, and require CODEOWNERS review in branch protection.
• Disclosure and incident response are defined in SECURITY.md; every release is recorded in CHANGELOG.md.
• This rules repo is versioned (git + CHANGELOG); projects consume a tagged version, not ad-hoc copies, so audits can tell which rules governed which commits.
• Security and a11y rules are EXEMPT from "prune rules that are being followed" maintenance — a control that is working is not redundant.

Sensitive paths — human sign-off required

AI agents must not modify without explicit human approval: CI/release/deploy configuration; auth/session/payment modules; security headers/CSP; lockfiles; and privileged Codex instructions, profiles, generated plugin output, or build/install scripts (AGENTS*.md, profiles/**, .agents/**, .codex/**, platforms/codex/**, plugins/codex-frontend-skills/**, and their generators/installers). Propose the specific diff and wait before the write; approval cannot be backdated. Codex PreToolUse cannot pause for an approval prompt, so enforce this with pre-write sign-off plus CODEOWNERS/branch protection.

Git & PR conventions

• Conventional Commits (feat:, fix:, chore:…); imperative subject ≤ 72 chars; body explains why.
• Branch naming: feat/<slug>, fix/<slug>, chore/<slug>.
• PRs: small and single-purpose; description includes what/why and test evidence (commands run + result); note AI assistance where the org requires disclosure. Squash-merge to keep main linear.

Observability

• Production applications with user traffic or business-critical workflows need owned error monitoring: release tagging, source maps uploaded privately (never publicly served), PII scrubbing, sampling, and actionable alerts. A static demo, prototype, library, or policy/docs repository may omit runtime monitoring when the reason and owner are documented; do not add a monitoring dependency merely to satisfy this sentence.

Performance budgets

• Core Web Vitals targets: LCP ≤ 2.5 s, INP ≤ 200 ms, CLS ≤ 0.1 (p75, field data).
• Client JS budget per route enforced in CI (size-limit); a sensible default initial-load ceiling is ~170 kB gzipped JS per route (tune per product/device profile). Adding a dependency that breaks the budget requires the frontend-security/governance dependency review, not a budget bump.

Browser support

• Define a browserslist (default: Baseline Widely Available) — it drives transpilation/polyfills, which CSS features are usable without fallback, and the Playwright browser matrix. Don't leave support implicit.