# Governance-Chain Runbook

> A copyable, end-to-end checklist for taking AI coding from "individuals using
> tools" to "an organization that can prove control." Work the five links in order;
> a chain is only as strong as its weakest link, and most orgs are missing the
> middle three.
>
> QRefAI *AI Coding Field Guide*, Part 4 (Q4.x). Treat this as a living runbook —
> re-verify vendor specifics before relying on them.

Legend: `[ ]` to do · `[~]` in progress · `[x]` done · `[N/A]` not applicable

---

## Link 1 — Identity

Every agent action must trace to a human or a managed service account. No shared
keys, no anonymous agents.

- [ ] Claude Code authenticates via SSO / your IdP (not personal API keys).
- [ ] Copilot access is provisioned through GitHub Enterprise, tied to identity.
- [ ] Service accounts used by agentic workflows are named and owned.
- [ ] A single user identifier (e.g. `user_id`) is present in BOTH Claude telemetry
      and GitHub audit events, so the two can be correlated.
- [ ] Offboarding revokes AI tool access alongside everything else.

**Gate to proceed:** you can answer "who did this?" for any agent action.

---

## Link 2 — Policy distribution

Rules are distributed and enforced centrally — not left to each developer's local
config.

- [ ] `managed-settings.json` distributed via MDM (macOS plist / Windows registry /
      Linux `/etc/claude-code/`); developers cannot override it.
- [ ] Deny-list for sensitive reads/commands (`.env`, secrets, `sudo`, `curl`) set.
- [ ] Models pinned (specific inference-profile ARNs / deployment names), so updates
      can't silently swap the model.
- [ ] Marketplaces locked to your private host (`strictKnownMarketplaces`).
- [ ] Copilot policies set at org/enterprise level (allowed models, features).
- [ ] Repo-level config distributed via the template repo + `bootstrap-repo.sh`,
      not copy-paste.

**Gate to proceed:** a new laptop and a new repo both come up compliant by default.

---

## Link 3 — Mandatory review

Every AI-authored change gets both an automated and a human pass before it lands.

- [ ] Branch-protection ruleset requires ≥1 human approval on `main`.
- [ ] `automatic_copilot_code_review` enabled (remember: non-blocking — it adds a
      reviewer, it doesn't gate).
- [ ] Required status checks (build/test/lint) must pass.
- [ ] `require_code_owner_review` on, with a real `CODEOWNERS`.
- [ ] Claude inner-loop hooks gate edits locally (protect-paths, post-edit lint).
- [ ] A gh-aw `security-guard` workflow runs read-only on every PR.

**Gate to proceed:** no AI-authored change can reach `main` unreviewed.

---

## Link 4 — Audit

You can reconstruct what agents did, after the fact, from your own systems.

- [ ] OpenTelemetry pipeline live (`CLAUDE_CODE_ENABLE_TELEMETRY=1`) → collector →
      SIEM. **This is the only source covering prompt / tool-use content.**
- [ ] Compliance API daily pull into your warehouse (180-day source retention) for
      platform/identity/config activity.
- [ ] GitHub Enterprise audit log streamed to SIEM; detections on `actor_is_agent`
      with `git.push`, `copilot.*`, `repository_ruleset.*`.
- [ ] The two Claude pipelines are understood as complementary (OTel = content,
      Compliance API = platform) — neither alone is sufficient.
- [ ] Logs from Claude and GitHub correlate on the shared user identity.
- [ ] Retention meets your regulatory requirement (pull before the 180-day window).

**Gate to proceed:** given an incident, you could produce the timeline from your
own data, not a vendor support ticket.

---

## Link 5 — Rollout discipline

You expand in audit-first stages, with measured gates — not a big-bang switch-on.

- [ ] Phase 1–2 weeks: run in **audit mode** (observe, don't block) to baseline.
- [ ] Weeks 3–4: set baseline deny rules from what you actually saw.
- [ ] Week 5+: tighten denies; enable blocking hooks once false-positives are low.
- [ ] Each expansion has an explicit gate criterion (e.g. "<5% of sessions blocked
      by policy", "review SLA holds", ">25% self-reported productivity gain").
- [ ] A rollback path exists for each control (you can loosen a deny fast).
- [ ] Feedback channel for developers to report bad blocks; triaged weekly.

**Gate to proceed:** every tightening was justified by data from the prior stage.

---

## One-screen summary

| Link | The question it answers | Primary artifacts |
|------|--------------------------|-------------------|
| Identity | Who did this? | SSO/IdP, Enterprise, named service accounts |
| Policy distribution | Are the rules enforced everywhere? | managed-settings.json + MDM, org policies, template repo |
| Mandatory review | Did a human and a machine check it? | ruleset, Copilot review, hooks, security-guard |
| Audit | Can we reconstruct it later? | OTel + Compliance API + GitHub audit log → SIEM |
| Rollout discipline | Did we expand safely? | audit-first phases with measured gates |

_If you can check every "gate to proceed", you have a governance chain, not a pile
of configs. Mid-2026 snapshot._