Skip to content

Enforce trunk-based branching policy (no direct commits to protected branches) #75

Description

@wimaan3

Problem

borromeanRings already follows trunk-based development in practice — short-lived feature branches → PR → gated merge (merge.sh --delete-branch) → delete — so main only ever receives PR merges (0 direct commits, verified via the GitHub activity log). But the policy is implicit, not enforced: nothing actually prevents a direct commit/push to main. Governed projects inherit the same gap, and at a glance they look "main-only" because feature branches are auto-deleted after merge.

Decision: standardize on trunk-based (chosen over GitFlow — for an always-green gated project a long-lived develop branch adds ceremony without payoff) and make the branching policy a declared, enforced borromeanRings capability.

Scope

  • Declare protected branches in the spine (e.g. [branching] protected = ["main"], default ["main"]).
  • Preventive guard (PreToolUse): block git commit when HEAD is on a protected branch, and block direct git push to a protected branch — with a clear message ("create a feature branch; land via PR + gate"). Pure logic unit-tested; fail-open on guard error (server-side protection is the backstop).
  • Works for governed projects (reads policy from the project's borromeanrings.toml, reference-mode safe).
  • Document the model (trunk-based) and how it composes with the gated merge.

Out of scope / complementary

Acceptance criteria

  • [branching].protected declared in the spine (default ["main"]); empty ⇒ enforcement off (opt-in, consistent with [git]/[layout]).
  • Guard denies a commit made while on a protected branch (with a fix hint).
  • Guard denies a direct git push to a protected branch.
  • Unit tests for the decision logic; verified in a governed temp project.
  • ADR; docs note the trunk-based model.

Relates to: #60 (server-side branch protection), and the existing PreToolUse guard (.claude/hooks/pre_bash_guard.sh) + gated merge flow (merge.sh).

Metadata

Metadata

Assignees

No one assigned

    Labels

    harness-featureA borromeo meta-harness capabilitypriority:medNormal priorityqualityEngineering rigor: tests, lint, verification

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions