Skip to content

github-governance.md

Latest commit

 

History

History
202 lines (150 loc) · 6.41 KB

github-governance.md

File metadata and controls

202 lines (150 loc) · 6.41 KB

GitHub Governance — Clawland-AI/Geneclaw

Actionable steps for branch protection, PR review, CI enforcement, and autopilot governance. All instructions reference the GitHub web UI.

Repository: https://github.com/Clawland-AI/Geneclaw Default branch: master

1. Branch Protection Rules

1.1 Navigate to Settings

  1. Open https://github.com/Clawland-AI/Geneclaw
  2. Click Settings (top tab, requires admin access)
  3. Left sidebar → Branches
  4. Under "Branch protection rules", click Add rule

1.2 Configure the Rule

Field Value
Branch name pattern master
Require a pull request before merging ✅ Checked
Required approvals 1 (minimum; increase for team)
Dismiss stale pull request approvals when new commits are pushed ✅ Recommended
Require status checks to pass before merging ✅ Checked
Require branches to be up to date before merging ✅ Recommended
Status checks that are required test (see Section 2)
Require conversation resolution before merging ✅ Recommended
Do not allow bypassing the above settings ✅ Checked (even admins must follow)
Restrict who can push to matching branches Optional — leave unchecked for now
Allow force pushes ❌ Unchecked (never)
Allow deletions ❌ Unchecked (never)
  1. Click Create (or Save changes)

1.3 Merge Strategy

Recommended: Squash and merge as default.

  1. Settings → General (left sidebar)
  2. Scroll to "Pull Requests"
  3. Uncheck "Allow merge commits"
  4. ✅ Check "Allow squash merging" → Default message: "Pull request title and description"
  5. Uncheck "Allow rebase merging" (optional, for cleaner history)
  6. Click Save

2. Required Status Checks

2.1 CI Workflow Overview

The CI pipeline is defined in .github/workflows/ci.yml:

name: CI
on: [push, pull_request]

jobs:
  test:                        # ← This is the job name for status checks
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12", "3.13"]
    steps:
      - pip install -e ".[dev]"
      - ruff check .           # advisory, continue-on-error: true
      - pytest -q              # must pass

2.2 Adding Status Checks

When configuring the branch protection rule (Section 1.2):

  1. Check Require status checks to pass before merging
  2. In the search box, type test
  3. Select the test job (it will appear after the first CI run completes)
  4. Optionally also add test (3.11), test (3.12), test (3.13) for matrix granularity

Note: Status checks only appear in the search after the workflow has run at least once. If test doesn't appear, push a commit or open a PR to trigger CI first, then come back to configure the rule.

2.3 What CI Validates

Step Command Blocking?
Lint ruff check . No (advisory, continue-on-error: true)
Test pytest -q Yes — must pass on all Python versions

3. PR Review Checklist

Every PR must use the template at .github/pull_request_template.md. Reviewers should verify:

3.1 Mandatory Fields

Field What to check
Summary Clear description of what changed and why
Risk Level low / medium / high — must match the actual change scope
Evo-Event-ID Present if the PR was generated by geneclaw evolve
Tests Run Specific pytest commands that were executed
Rollback Plan Concrete steps to undo the change

3.2 Review Actions

  • All CI checks pass (green)
  • Risk Level matches actual change scope
  • If Evo-Event-ID present: verify the proposal JSON in ~/.nanobot/workspace/geneclaw/proposals/
  • Files touched are within the allowlist (geneclaw/, docs/, tests/, nanobot/)
  • No secrets, API keys, or credentials in the diff
  • No eval(), exec(), os.system(), subprocess.call() without justification
  • Tests cover the changed code paths
  • Rollback plan is actionable

3.3 Merge Decision

  • Low risk, all checks green, 1+ approval → Squash and merge
  • Medium risk → Require 2 approvals or admin sign-off
  • High risk → Require team discussion + explicit approval from repo admin

4. Autopilot Governance

4.1 Default Mode: Dry-Run + Human PR

The recommended workflow for autopilot-generated changes:

nanobot geneclaw autopilot --dry-run --max-cycles 3
  ↓
Review proposals in ~/.nanobot/workspace/geneclaw/proposals/
  ↓
If acceptable: create a branch, apply manually, open PR
  ↓
PR goes through normal review (Section 3)
  ↓
Squash and merge after approval

4.2 When to Consider Auto-Apply

Prerequisites (all must be met):

  • ≥20 prior autopilot proposals have been human-reviewed and merged
  • Success rate ≥ 80% (nanobot geneclaw report)
  • auto_approve_risk set to low only (never medium or high)
  • allowlist_paths restricted to ["geneclaw/", "docs/"] (Phase 1)
  • max_patch_lines ≤ 100
  • tools.restrictToWorkspace = true
  • CI is enforced via branch protection (Section 1–2)

Auto-apply workflow:

nanobot geneclaw autopilot --apply --auto-approve low --max-cycles 1
  ↓
Autopilot creates evo/<timestamp>-<slug> branch
  ↓
Autopilot runs pytest; if fail → auto-rollback
  ↓
If pass → open PR from evo/ branch (manual or scripted)
  ↓
PR still requires human review + CI check (branch protection enforces this)

4.3 Exit Conditions (Revert to Dry-Run)

Immediately revert to dry-run mode if:

  • Any apply fails (nanobot geneclaw report shows apply_failed > 0)
  • Success rate drops below 70%
  • A proposal touches files outside the allowlist
  • A security concern is raised during review
  • The nanobot geneclaw doctor shows new warnings or errors

4.4 Monitoring

Regular health checks (recommend weekly):

nanobot geneclaw doctor
nanobot geneclaw report --since 168  # last 7 days
nanobot geneclaw report --format json --since 168 > weekly-report.json

5. Security Reminders

  • Never commit API keys or secrets to the repository
  • geneclaw.redact_enabled must remain true in production
  • All event logs and proposals are redacted before writing to disk
  • The .env file is in .gitignore and on the denylist
  • Review docs/specs/GEP-v0.md Section 10 for the full allowlist strategy