Branch Protection & Trunk Governance Specification

Branch Protection & Trunk Governance Specification

1. Architectural Overview & Context

SiteSwarm enforces a Trunk-Based Staging Architecture (governed under Epic #3). Under this paradigm:

1. Sole Trunk Branch: main is the single source of truth for integration and automated staging deployment. There are no permanent or long-lived staging branches.
2. Short-Lived Worktrees: Developers and autonomous AI agents work exclusively in isolated Git worktrees (feature/*, fix/*, chore/*) spawned via Worktrunk (wt).
3. No Direct Pushes: All changes to main must pass through a pull request.
4. Mandatory CI Gate: PRs must pass the aggregator Gate status check defined in .github/workflows/ci.yml before merging.
5. Declarative Synchronization: The branch protection ruleset is managed as code via .github/branch-ruleset.json and synchronized using scripts/sync-branch-protection.ts.

---

2. Active Ruleset Specification

SiteSwarm utilizes GitHub Repository Rulesets (main-branch-protection) targeting refs/heads/main.

2.1 Rules & Constraints Matrix

Rule	Type	Description
Branch Deletion	deletion	Prevents accidental or intentional deletion of the main branch.
Linear / Fast-Forward	non_fast_forward	Rejects force pushes (git push --force or --force-with-lease).
Pull Request Gate	pull_request	Restricts direct pushes to main. All modifications must be submitted via pull request.
Status Check Gate	required_status_checks	Enforces passing of the Gate aggregator job from .github/workflows/ci.yml.
Emergency Bypass	bypass_actors	Repository administrators retain bypass permissions for emergency disaster recovery.

2.2 CI Aggregator Status Check (Gate)

The CI workflow (.github/workflows/ci.yml) is architected with dynamic change detection (scripts/change-detector.ts). To prevent GitHub from requiring individual dynamic matrix jobs that might not run for every PR:

• The workflow terminates in a unified aggregator job named Gate.
• Gate evaluates the outcomes of detect-changes, fast-pass, platform-verification, and selective-verification.
• If any required verification step fails or is cancelled, Gate exits with code 1.
• If all touched apps and packages pass checks (or if the PR is documentation-only fast-pass), Gate succeeds.
• Branch protection requires only this single canonical context: Gate.

---

3. Declarative Configuration (.github/branch-ruleset.json)

The authoritative definition of repository rules is committed to the repository:

{
  "$schema": "https://json.schemastore.org/github-ruleset.json",
  "name": "main-branch-protection",
  "target": "branch",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "include": [
        "refs/heads/main"
      ],
      "exclude": []
    }
  },
  "rules": [
    {
      "type": "deletion"
    },
    {
      "type": "non_fast_forward"
    },
    {
      "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 0,
        "dismiss_stale_reviews_on_push": false,
        "require_code_owner_review": false,
        "require_last_push_approval": false,
        "required_review_thread_resolution": false,
        "require_extra_approval_for_unattributed_changes": true,
        "allowed_merge_methods": [
          "merge",
          "squash",
          "rebase"
        ]
      }
    },
    {
      "type": "required_status_checks",
      "parameters": {
        "strict_required_status_checks_policy": false,
        "do_not_enforce_on_create": false,
        "required_status_checks": [
          {
            "context": "Gate"
          }
        ]
      }
    }
  ],
  "bypass_actors": [
    {
      "actor_id": 5,
      "actor_type": "RepositoryRole",
      "bypass_mode": "always"
    }
  ]
}

---

4. CLI Tooling & Operations

Developers and CI can audit and synchronize branch protection rules using the monorepo tooling:

4.1 Audit Branch Protection Status

pnpm run ruleset:check

Outputs verification status and detects any configuration drift between .github/branch-ruleset.json and GitHub.

4.2 Synchronize / Apply Ruleset to GitHub

pnpm run ruleset:sync

Idempotently creates or updates the ruleset via GitHub API.

4.3 Native GitHub CLI Commands

# Check rules applicable to main
gh ruleset check main

# List all rulesets
gh ruleset list