milkywayrules Security: see references/scanner-notes.md and upstream SECURITY.md for expected scanner signals and trust model.
Verasic GitHub Governance — Factory + Soft Enforcement
Workflows
New repo factory path — bootstrap a repo once:
- Read
references/governance-protocol.md(model, plan matrix, mutation routing) andreferences/factory-protocol.md(ordered checklist). - Create a private repo (default). Do not apply GitHub branch protection on Free private plans.
- Prefer init orchestrator:
bash .cursor/skills/verasic-github-governance-init/scripts/factory.sh --yes - Or manually:
bootstrap-repo.sh→wire-hooks.sh→lefthook install→doctor.sh - Open first PR to prove CI merge + Actions. Required status check name:
ci. - Verify:
bash .cursor/skills/verasic-github-governance/scripts/doctor.sh
Existing repo with CI: bootstrap stops on foreign workflows (exit 2). Read references/existing-repo-conflicts.md and pass --ci-strategy=skip|merge|replace.
Turborepo: when turbo.json exists at repo root, bootstrap uses ci-turborepo.yml (bun + turbo + gate job ci).
Hard protection path — when plan allows (Team/Pro/public Free):
- Confirm plan eligibility in
references/plan-matrix.md. - Apply OpenTofu from a dogfood registry repo at
infra/github-governance/(public-free or private-free) withenable_hard_protection=true. - Re-run
doctor.sh; plan-gated items should report ready for hard apply.
Mutation routing — any GitHub write (create repo, settings, protection, CI bootstrap, transfer prep):
- Load this skill and follow
references/governance-protocol.mdmutation routing. - Read-only
gh(status, log, view) elsewhere is fine without this skill.
Source of truth
| doc | role |
|---|---|
references/governance-protocol.md |
Governance model, plan matrix summary, mutation routing, enforcement layers |
references/factory-protocol.md |
Ordered new-repo bootstrap checklist |
references/existing-repo-conflicts.md |
CI conflict tiers and --ci-strategy |
references/plan-matrix.md |
Free private vs public vs Team — branch protection eligibility |
hooks/pre-push |
Block direct push to default branch (soft layer) |
hooks/pre-commit |
Lightweight reminder on default-branch commits |
scripts/bootstrap-repo.sh |
Copy CI/CONTRIBUTING/lefthook/AGENTS templates (idempotent) |
scripts/wire-hooks.sh |
Wire lefthook or core.hooksPath |
scripts/doctor.sh |
Soft-governance readiness (0) vs gaps (2) |
scripts/detect-posture.sh |
Read-only posture tier; init/factory recommend hard when eligible |
Dogfood registry infra/github-governance/ |
OpenTofu scaffold for hard rules when plan allows — not copied to product repos |
The Cursor subagent (.cursor/agents/verasic-github-governor.md) is a thin pointer — never duplicate the spec elsewhere.
Registered in verasic-init manifest (wire-hooks + doctor). Install via npx skills add Milkywayrules/verasic-skills or bundle tag @v0.2.5.
Hard rules
- Default: private + Free → no GitHub branch protection; enforce via hooks + CI culture + doctor.
- OpenTofu holds intended hard rules; apply branch protection only when
enable_hard_protection=true. - Required CI job name is
ci— matches future required status checks. - No signed commits in v1.
- Standard floor when hard protection is enabled: no direct push to default branch, PR + 1 review, required check
ci, delete branch on merge. - Never commit secrets or apply OpenTofu against production repos without explicit user approval.