docs/GITHUB_ENTERPRISE_ACCESS_RUNBOOK.md

GitHub Enterprise access runbook

This runbook explains how the additional GitHub Enterprise seats can help the remaining cross-repo phases. It does not assume that buying seats alone grants write access. The observed runtime pattern is:

• szl-holdings/a11oy is writable from this environment.
• sibling repos such as .github, agi-forecast, lutar-lean, uds-mesh, sentra, amaru, rosie, and vessels have previously returned 403 for direct pushes from the current bot/token context.

What the new licenses can fix

Additional Enterprise seats can help if the blocker was seat capacity:

1. assign seats to the human or service accounts that should operate the ecosystem;
2. invite those accounts to szl-holdings;
3. ensure the invitations are accepted;
4. add the accounts or GitHub App installation to teams with repo-level write access.

What the new licenses cannot fix by themselves

Seats do not automatically grant:

• write permission to sibling repos;
• SSO authorization for an existing PAT;
• GitHub App installation scope on sibling repos;
• workflow-edit permission;
• branch-protection bypass;
• accepted org membership for pending invites.

Required access target

The current Cursor/bot or designated service account needs:

Repo	Minimum permission	Why
szl-holdings/.github	Write	Org profile, coordination, reusable workflows, issue/PR templates.
szl-holdings/lutar-lean	Write	Apply Lean kernel/proof proxy patches directly instead of via A11oy handoff.
szl-holdings/agi-forecast	Write	Apply competition-math/FG pipeline patches directly.
szl-holdings/uds-mesh	Write	Update mesh pointers, release topology, and UDS bundle indexes.
szl-holdings/amaru	Write	Receipt minting/anchor UDS component upgrades.
szl-holdings/sentra	Write	Drift/telemetry UDS component upgrades.
szl-holdings/rosie	Write	Receipt DAG / CSS ingress component upgrades.
szl-holdings/vessels	Write	Active vertical demo wedge.
szl-holdings/platform	Write	Product integration monorepo changes, if in-scope and authorized.

Token / app requirements

For a fine-grained PAT:

• include every target repo above;
• grant Contents: Read and write;
• grant Pull requests: Read and write if PR creation should be direct;
• grant Workflows: Read and write only if workflow files will be edited;
• SSO-authorize the token for szl-holdings.

For a GitHub App:

• install the app on every target repo;
• grant the app contents and pull-request write scopes;
• include workflow write scope only if workflow edits are required.

Read-only checks

These checks do not modify resources:

gh auth status
gh api user -q .login
gh repo view szl-holdings/a11oy --json viewerPermission
gh repo view szl-holdings/.github --json viewerPermission
gh repo view szl-holdings/agi-forecast --json viewerPermission
gh repo view szl-holdings/lutar-lean --json viewerPermission
gh repo view szl-holdings/uds-mesh --json viewerPermission

If viewerPermission is empty, READ, or not present, direct write phases remain blocked and the proxy-patch pattern stays correct.

Live read-only audit

After seats, invitations, teams, SSO, or GitHub App installation scopes are updated, run:

npm run github:access:live:validate

This writes dist/github-access-audit.json with the current gh integration's viewer permission for each target repo. It uses only read-only gh auth, gh api user, and gh repo view commands. It does not push, create PRs, edit repos, mutate teams, or call write-method GitHub APIs.

Interpretation:

Status	Meaning
write-ready	Current auth context reports WRITE, MAINTAIN, or ADMIN. Direct feature-branch work may be tried.
read-only	Repo is visible but write phases remain blocked.
unavailable	Repo cannot be inspected from this token/app context.

Write-readiness check

Only after permissions are updated, test by pushing a new cursor/*-2f18 feature branch to a sibling repo, not to main. Do not merge to protected branches without explicit approval.

Doctrine boundary

Access changes are operational plumbing. They do not change public claim status. A sibling repo becomes “directly operational” only after:

1. patches are applied in that repo;
2. repo-native tests pass;
3. CI is green;
4. release/HF/UDS surfaces are regenerated from GitHub truth;
5. public docs avoid unsupported all-green, endorsement, or catalog claims.