feat(contracts): authority-gated governance — GovernanceGate contract (#200)

[stackbilt-admin]

Summary

Names and contracts the propose→gate→commit invariant (#200). The pattern existed as an emergent unnamed mechanism (dryRun flag on applyPolicies) but was not contracted, not enforced at the type level, and not auditable.

What changed

@stackbilt/types — new generic contract (no deps):

• GovernanceDecision = 'approve' | 'override' | 'dismiss'
• GovernanceProposal — stable id, alreadyCompliant, delta: string[], optional expires
• GovernanceReceipt — proposalId, decision, committedAt
• GovernanceGate<Context, P extends GovernanceProposal> — propose(context) + commit(proposal, decision)

@stackbilt/policies — concrete implementation:

• PolicyGovernanceProposal extends GovernanceProposal (adds repoPath for commit replay)
• PolicyGovernanceGate implements GovernanceGate<string, PolicyGovernanceProposal>
  • propose() calls applyPolicies(dryRun: true) — never writes
  • commit('approve'|'override') calls applyPolicies(dryRun: false)
  • commit('dismiss') — no-op, receipt still emitted
  • Proposal id is sha256 of resolved repoPath + delta (deterministic for same state)

Invariants enforced

Invariant	How
propose() before commit()	TypeScript — commit() requires a PolicyGovernanceProposal which only propose() produces
propose() is idempotent	sha256 id is deterministic; same repo state → same id
dismiss leaves state unchanged	commit('dismiss') skips applyPolicies entirely
every commit() emits a receipt	return type GovernanceReceipt — non-nullable
autonomy ceiling externally set	PolicyGovernanceGate takes opts at construction; cannot self-elevate

applyPolicies unchanged — additive only

The existing applyPolicies function and StampOptions/PolicyStampResult types are untouched. The gate wraps them. OSS additive-only policy satisfied.

Test plan

• 6 new gate invariant tests pass (propose no-write, idempotent, approve writes, dismiss no-write, override on compliant, empty delta on compliant)
• All 659 tests pass
• pnpm run build clean

Closes #200

🤖 Generated with Claude Code