30. Build, Continuous Integration, and Documentation

cargo xtask is the cross-platform command surface. doctor validates the host, bootstrap installs repository-scoped tools, check runs shared merge gates, test runs selectable test tiers, docs runs documentation gates, package builds development artifacts, and release-check validates release-only state and credentials. CI invokes the same subcommands with locked dependencies.

flowchart TB
  change["Pull request"] --> classify["Classify affected paths"]
  classify --> docs["Documentation and version gates"]
  classify --> shared["Rust and TypeScript shared checks"]
  classify --> security["Security, licenses, and supply chain"]
  shared --> platform["Affected native platform checks"]
  docs --> aggregate{"Required aggregate status"}
  security --> aggregate
  platform --> aggregate
  aggregate -->|Fail| blocked["Merge blocked"]
  aggregate -->|Pass| review["Human review and merge"]

Every pull request runs formatting, Clippy with warnings denied, TypeScript typecheck, JavaScript lint, unit and contract tests, documentation gates, dependency/license checks, secret scan, and an always-reporting aggregate status. Path filtering MAY skip irrelevant heavy platform jobs, but scheduled and release workflows run the complete matrix and the aggregate gate must distinguish skipped from failed jobs.

Documentation gates include Prettier, markdownlint, internal-anchor validation, external-link validation, Mermaid parse and render validation, top-to-bottom direction validation for project-authored documentation diagrams, spelling and terminology, UTF-8 without BOM, mojibake detection, specification/product version equality, capability-claim consistency, and documentation-impact declaration. User-document fixtures MAY contain any valid authored Mermaid direction and MUST be excluded from the project-direction rule while remaining included in parser and renderer conformance.

Release CI performs no unreviewed source rewrite. Documentation reconciliation, changelog assembly, version bumps, and the release receipt are committed and reviewed before tagging. Tag workflows verify, build, test, sign, attest, and publish.