docs(security): add enterprise AI governance guide + templates

New section for org-level Claude Code governance — fills the gap between individual dev security (security-hardening.md) and what engineering managers actually need when deploying at scale. New files: - guide/security/enterprise-governance.md (1117 lines) 6 sections: local/shared split, usage charter, MCP approval workflow, 4 guardrail tiers (Starter/Standard/Strict/Regulated), policy enforcement at scale, SOC2/ISO27001 compliance guide - examples/scripts/mcp-registry-template.yaml Org-level MCP registry with approved/pending/denied tracking - examples/hooks/bash/governance-enforcement-hook.sh SessionStart hook validating MCPs against approved registry - examples/scripts/ai-usage-charter-template.md Full charter template with data classification, use case rules, compliance mapping (SOC2/ISO27001/HIPAA/PCI DSS/GDPR) Enriched sections: - adoption-approaches.md: enterprise rollout (50+ devs) with 3-phase approach and common mistakes - observability.md: manager audit checklist, compliance reporting - ai-traceability.md: evidence collection table for auditors - production-safety.md + security-hardening.md: cross-references with explicit scope boundaries Integration: guide/README.md, reference.yaml (22 new entries), CHANGELOG.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-10 11:05:21 +01:00 · 2026-03-10 11:05:21 +01:00 · 77b48db01b
commit 77b48db01b
parent b65630641b
12 changed files with 1797 additions and 1 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -6,6 +6,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

 ## [Unreleased]

+### Added
+
+- **Enterprise AI Governance section** (`guide/security/enterprise-governance.md`) — New guide covering org-level governance for teams deploying Claude Code at scale. 6 sections: (1) Local vs Shared governance split (risk matrix, decision framework); (2) AI Usage Charter — lean template covering approved tools, data classification, use case boundaries, approval matrix; (3) MCP Governance Workflow — approval pipeline (request → review → approve → deploy), YAML registry format, enforcement hook; (4) Guardrail Tiers — 4 pre-configured tiers (Starter/Standard/Strict/Regulated) with ready-to-copy `settings.json` and `CLAUDE.md` additions; (5) Policy Enforcement at Scale — config distribution, onboarding checklist, compliance audit script, role-based guardrails, CI/CD gates; (6) Audit & Compliance — what SOC2/ISO27001 auditors actually ask, audit trail setup, AI Governance Committee minimal structure. Audience: tech leads, engineering managers, security officers. Complements security-hardening.md (individual dev security) and production-safety.md (6 prod rules).
+
+- **MCP Registry Template** (`examples/scripts/mcp-registry-template.yaml`) — Ready-to-use YAML format for tracking approved MCP servers at org level. Includes approved/pending/denied sections, version bump policy, risk classification (LOW/MEDIUM/HIGH), data scope classification (PUBLIC/INTERNAL/CONFIDENTIAL/RESTRICTED), and expiry dates.
+
+- **Governance Enforcement Hook** (`examples/hooks/bash/governance-enforcement-hook.sh`) — SessionStart hook validating active MCP configuration against org's approved registry, checking deny rules for secret files, and detecting dangerous `permissions.allow` overrides. Warns without blocking (governance-first, not friction-first).
+
+- **AI Usage Charter Template** (`examples/scripts/ai-usage-charter-template.md`) — Org-level charter template covering approved tools, data classification (4 levels), approved/prohibited use cases, MCP server governance, code review and attribution requirements, accountability roles, incident response, and compliance mapping (SOC2/ISO27001/HIPAA/PCI DSS/GDPR).
+
+### Documentation
+
+- **`guide/roles/adoption-approaches.md`** — Added "Enterprise Rollout (50+ developers)" section with 3-phase rollout approach (Foundation/Adoption/Optimization), common rollout mistakes at scale, and pointer to enterprise-governance.md for compliance programs.
+
+- **`guide/ops/observability.md`** — Added "Manager Audit Checklist" section with weekly spot-check bash queries (files accessed outside project scope, destructive commands run) and a monthly compliance report script.
+
+- **`guide/ops/ai-traceability.md`** — Added "Evidence Collection for Auditors" subsection under §7.3 Enterprise/Compliance — practical table mapping auditor questions to evidence sources and generation commands.
+
+- **`guide/security/production-safety.md`** — Added cross-reference to enterprise-governance.md in See Also section.
+
+- **`guide/security/security-hardening.md`** — Added cross-reference to enterprise-governance.md with explicit scope boundary ("this guide = individual MCP vetting; that guide = org-level policy"), plus MCP registry template reference.
+
+- **`guide/README.md`** — Added enterprise-governance.md entry in Security section.
+
+- **`machine-readable/reference.yaml`** — Added 22 entries for enterprise governance guide, templates, and hooks.
+
 ### Changed

 - **GEO/SEO optimization — llms.txt, llms-full.txt, guide meta descriptions** — Phase 1 (repo): `machine-readable/llms.txt` updated (v3.8.0→3.32.2, 87→238 templates, 9.6K→22.7K lines); `llms.txt` created at repo root (convention llmstxt.org — AI crawlers expect root); `llms-full.txt` created (~20KB: full cheatsheet, 238-template catalog, 10 Q&A FAQ); `mcp-server/content/llms.txt` synced. Phase 2 (landing): `public/llms.txt` synced, `public/llms-full.txt` created; stale root `robots.txt` (wrong sitemap URL, missing 6 AI bots) and `sitemap.xml` (6 URLs only) deleted — `public/` versions are canonical. Phase 3 (landing): JSON-LD counts fixed (113→238 in `examples/index.astro`, description sync in `index.astro`); `twitter:site` + `twitter:creator` added to `Layout.astro`; CVE stat 19→24 in security page; `lastmod` added to all sitemap entries in `astro.config.mjs`. Phase 4 (README): invisible HTML keyword comment replaced with visible 5 Q&A mini-FAQ (GEO crawlers + humans). Phase 5 (guide section): 13 `CHAPTERS` descriptions rewritten in `scripts/prepare-guide-content.mjs` (source of truth for Starlight frontmatter) — avg 40→150 chars, now include specific agent names, hook event types, MCP server names, pattern names.
--- a/examples/hooks/bash/governance-enforcement-hook.sh
+++ b/examples/hooks/bash/governance-enforcement-hook.sh
@ -0,0 +1,177 @@
+#!/bin/bash
+# governance-enforcement-hook.sh
+# Event: SessionStart
+#
+# Validates active Claude Code MCP configuration against the org's approved registry.
+# Warns about unapproved MCPs and checks that security deny rules are in place.
+#
+# Related: guide/security/enterprise-governance.md §3.3 and §5
+#
+# Installation:
+#   cp governance-enforcement-hook.sh ~/.claude/hooks/
+#   chmod +x ~/.claude/hooks/governance-enforcement-hook.sh
+#
+#   Then add to ~/.claude/settings.json:
+#   {
+#     "hooks": {
+#       "SessionStart": ["~/.claude/hooks/governance-enforcement-hook.sh"]
+#     }
+#   }
+#
+# Or in project .claude/settings.json:
+#   {
+#     "hooks": {
+#       "SessionStart": [".claude/hooks/governance-enforcement-hook.sh"]
+#     }
+#   }
+
+set -euo pipefail
+
+SETTINGS_FILE="${HOME}/.claude.json"
+REGISTRY_FILE="${PWD}/.claude/mcp-registry.yaml"
+PROJECT_SETTINGS="${PWD}/.claude/settings.json"
+
+# ─────────────────────────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────────────────────────
+
+warn() { echo "GOVERNANCE WARNING: $*" >&2; }
+info() { echo "GOVERNANCE: $*" >&2; }
+
+has_command() { command -v "$1" &>/dev/null; }
+
+# ─────────────────────────────────────────────────────────────────
+# Check 1: Project governance config present
+# ─────────────────────────────────────────────────────────────────
+
+check_project_config() {
+  if [[ ! -f "$PROJECT_SETTINGS" ]]; then
+    warn "No .claude/settings.json in project. Governance not applied to this repo."
+    warn "Set up governance: see guide/security/enterprise-governance.md"
+    return
+  fi
+
+  # Check that deny rules exist for secrets
+  if has_command jq; then
+    local has_deny
+    has_deny=$(jq -e '.permissions.deny // [] | length' "$PROJECT_SETTINGS" 2>/dev/null || echo "0")
+    if [[ "$has_deny" == "0" ]]; then
+      warn "No permissions.deny rules in .claude/settings.json."
+      warn "Add deny rules for .env, *.key, *.pem files."
+    fi
+
+    # Check for dangerous allow rules
+    local dangerous_allows
+    dangerous_allows=$(jq -r '.permissions.allow[]? // ""' "$PROJECT_SETTINGS" 2>/dev/null | \
+      grep -iE '(env|secret|credential|password|token|key)' || true)
+    if [[ -n "$dangerous_allows" ]]; then
+      warn "DANGEROUS: permissions.allow contains sensitive patterns:"
+      echo "$dangerous_allows" | while read -r line; do
+        warn "  Allowed: $line"
+      done
+    fi
+  fi
+}
+
+# ─────────────────────────────────────────────────────────────────
+# Check 2: MCP registry compliance
+# ─────────────────────────────────────────────────────────────────
+
+check_mcp_registry() {
+  if [[ ! -f "$REGISTRY_FILE" ]]; then
+    # No registry = no enforcement (opt-in)
+    return
+  fi
+
+  if ! has_command jq || ! has_command yq; then
+    warn "jq or yq not installed — cannot check MCP registry compliance."
+    warn "Install: brew install jq yq"
+    return
+  fi
+
+  if [[ ! -f "$SETTINGS_FILE" ]]; then
+    return
+  fi
+
+  # Get active MCPs
+  local active_mcps
+  active_mcps=$(jq -r '.mcpServers // {} | keys[]' "$SETTINGS_FILE" 2>/dev/null || true)
+
+  if [[ -z "$active_mcps" ]]; then
+    return
+  fi
+
+  # Get approved MCPs from registry
+  local approved_mcps
+  approved_mcps=$(yq e '.approved[].name' "$REGISTRY_FILE" 2>/dev/null || true)
+
+  # Compare
+  local unapproved=()
+  while IFS= read -r mcp; do
+    if [[ -n "$mcp" ]] && ! echo "$approved_mcps" | grep -q "^${mcp}$"; then
+      unapproved+=("$mcp")
+    fi
+  done <<< "$active_mcps"
+
+  if [[ ${#unapproved[@]} -gt 0 ]]; then
+    warn "Unapproved MCP servers detected:"
+    for mcp in "${unapproved[@]}"; do
+      warn "  - $mcp (not in .claude/mcp-registry.yaml)"
+    done
+    warn "Submit approval request per your org's AI usage charter."
+    warn "Session continues — remediate within 48 hours per policy."
+  else
+    info "MCP registry check passed. All MCPs approved."
+  fi
+
+  # Check for expired approvals
+  local today
+  today=$(date +%Y-%m-%d)
+  while IFS= read -r name; do
+    local expires
+    expires=$(yq e ".approved[] | select(.name == \"$name\") | .expires" "$REGISTRY_FILE" 2>/dev/null || true)
+    if [[ -n "$expires" && "$expires" < "$today" ]]; then
+      warn "MCP '$name' approval expired on $expires. Re-approval required."
+    fi
+  done <<< "$approved_mcps"
+}
+
+# ─────────────────────────────────────────────────────────────────
+# Check 3: Data classification context
+# ─────────────────────────────────────────────────────────────────
+
+check_data_classification() {
+  # Detect sensitive files in working directory
+  local sensitive_patterns=(".env" "*.pem" "*.key" "secrets/" "credentials")
+  local found_sensitive=()
+
+  for pattern in "${sensitive_patterns[@]}"; do
+    if compgen -G "${PWD}/${pattern}" &>/dev/null 2>/dev/null; then
+      found_sensitive+=("$pattern")
+    fi
+  done
+
+  if [[ ${#found_sensitive[@]} -gt 0 ]]; then
+    info "Sensitive file patterns detected in working directory:"
+    for f in "${found_sensitive[@]}"; do
+      info "  - $f"
+    done
+    info "Verify .claude/settings.json deny rules cover these files."
+  fi
+}
+
+# ─────────────────────────────────────────────────────────────────
+# Main
+# ─────────────────────────────────────────────────────────────────
+
+main() {
+  check_project_config
+  check_mcp_registry
+  check_data_classification
+
+  # Always exit 0 — governance hook warns but does not block session start
+  # Blocking at SessionStart creates too much friction; use periodic audits instead
+  exit 0
+}
+
+main
--- a/examples/scripts/ai-usage-charter-template.md
+++ b/examples/scripts/ai-usage-charter-template.md
@ -0,0 +1,200 @@
+# AI Coding Tools Usage Charter
+
+> **Template** — Copy to `docs/ai-usage-charter.md` in your organization's docs repo.
+> Adapt sections marked with `[BRACKETS]`.
+>
+> Related: guide/security/enterprise-governance.md §2
+
+---
+
+**Organization**: [Your Organization]
+**Applies to**: Claude Code and all AI coding assistants
+**Effective date**: [DATE]
+**Owner**: [Engineering Lead / CTO / CISO]
+**Review cadence**: Quarterly
+**Version**: 1.0.0
+
+---
+
+## 1. Purpose
+
+This charter defines how [Organization] employees may use AI coding assistants, which tools are approved, what data can be used with them, and who is accountable for compliance. The goal is to enable productive AI-assisted development while managing security, privacy, and regulatory risk.
+
+---
+
+## 2. Approved Tools
+
+| Tool | Plan / Tier | Scope | Administered by |
+|------|-------------|-------|----------------|
+| Claude Code | Team/Enterprise | All engineering work | Platform Team |
+| Claude Code | Personal Pro | Personal dev only (no company data above INTERNAL) | Individual |
+| [Other Tool] | [Plan] | [Scope] | [Team] |
+
+**Using non-approved AI coding tools on company systems is prohibited.** If you believe an additional tool would benefit your work, submit an approval request to [engineering-lead@company.com].
+
+---
+
+## 3. Data Classification Rules
+
+All data at [Organization] is classified into four levels. Your use of AI tools must comply with this classification.
+
+| Classification | Examples | Claude Code permitted? | Notes |
+|----------------|----------|----------------------|-------|
+| **PUBLIC** | Open-source code, public documentation | Yes — no restrictions | |
+| **INTERNAL** | Internal tools, non-sensitive business code | Yes — standard config | Use company accounts |
+| **CONFIDENTIAL** | Customer data (non-PII), business secrets, proprietary algorithms | Yes — Enterprise plan only, with approved config | |
+| **RESTRICTED** | PCI card data, PHI, credentials, auth tokens, encryption keys | **Never** | No exceptions |
+
+### Hard Rules
+
+- RESTRICTED data **never** enters an AI context window — not in prompts, not in files Claude reads, not as examples.
+- Personal AI accounts (personal Pro subscriptions) may only be used with PUBLIC or INTERNAL data.
+- Company credentials and API keys are RESTRICTED. Never paste them into prompts.
+
+### Technical Enforcement
+
+Projects handling CONFIDENTIAL or RESTRICTED data must configure `permissions.deny` in `.claude/settings.json` to block AI access to sensitive files. See the [Standard or Regulated tier config](../security/enterprise-governance.md#4-guardrail-tiers) for ready-to-use configurations.
+
+---
+
+## 4. Approved Use Cases
+
+The following uses of AI coding assistants are approved without additional review:
+
+- Code completion and generation for approved data classifications
+- Code review and quality analysis
+- Test generation and mutation testing
+- Documentation drafting and updating
+- Debugging, root cause analysis, log analysis
+- Architecture analysis of internal systems
+- CLI scripting, automation, build tooling
+- Refactoring and code cleanup
+
+---
+
+## 5. Prohibited Use Cases
+
+The following are **not permitted** without explicit written approval:
+
+| Prohibited use | Reason | Exception process |
+|----------------|--------|------------------|
+| Processing raw PCI cardholder data | Regulatory (PCI DSS) | None — technically enforced |
+| Generating code handling unencrypted PHI without security review | Regulatory (HIPAA) | Security review required |
+| Autonomous deployment to production | Human oversight requirement | Approval from Eng Director |
+| Using personal AI accounts for CONFIDENTIAL data | Data residency/privacy | Upgrade to company account |
+| Sharing customer data as examples in prompts | Privacy, data handling | Use synthetic data |
+| Bypassing governance controls (hooks, deny rules) | Policy violation | None |
+
+---
+
+## 6. MCP Server Governance
+
+Model Context Protocol (MCP) servers extend Claude Code's capabilities and introduce additional risk surface. All MCP servers used on company projects must be:
+
+1. Listed in the approved registry (`.claude/mcp-registry.yaml` in the platform config repo)
+2. Pinned to an exact version (never `@latest`)
+3. Re-reviewed every 6 months or on major version bumps
+
+**Approval process**: Submit a request with server name, source URL, intended use case, and data scope to [platform-team@company.com] or [#claude-code-requests Slack channel].
+
+Unapproved MCPs detected in project configs will be flagged at session start. Developers have 48 hours to remove or seek approval.
+
+---
+
+## 7. Code Review and Attribution
+
+### AI Attribution
+
+All pull requests where AI assisted in writing code must include an AI disclosure section:
+
+```markdown
+## AI Assistance
+- AI tool used: Claude Code
+- Scope: [e.g., "Generated tests for auth module", "Refactored payment handler"]
+- Human review: Reviewer checked logic, security implications, and edge cases
+```
+
+The standard `Co-Authored-By: Claude <noreply@anthropic.com>` commit trailer (added automatically by Claude Code) satisfies attribution for routine changes. Explicit PR disclosure is required for:
+- Any change to authentication or authorization
+- Any change to payment or financial logic
+- Any database schema change
+- Any new external API integration
+
+### Code Review Expectations
+
+AI-generated code is not exempt from code review. Reviewers should apply the same — or stricter — scrutiny to AI-generated sections, particularly for:
+- Security-sensitive paths (auth, crypto, access control)
+- Data handling (PII, financial data)
+- Edge cases and error conditions that AI tools often miss
+
+---
+
+## 8. Accountability
+
+### Developer Responsibilities
+
+By using Claude Code on company systems, you agree to:
+- Follow this charter
+- Report suspected data exposure to [security@company.com] within 24 hours
+- Participate in quarterly access reviews
+- Complete AI tools onboarding checklist when joining or switching teams
+- Not circumvent governance controls (hooks, deny rules, registry)
+
+### Team Lead Responsibilities
+
+- Ensure projects are configured with the appropriate guardrail tier
+- Review MCP registry quarterly
+- Include AI charter in team onboarding
+- Escalate charter violations per §9
+
+### Platform Team Responsibilities
+
+- Maintain shared governance config (settings.json templates, hooks)
+- Review MCP approval requests within 1 week
+- Update charter when tools, tiers, or risks change
+- Conduct semi-annual governance audit
+
+---
+
+## 9. Incident Response
+
+### If you suspect data exposure
+
+1. **Stop** the current AI session immediately
+2. **Document** what data may have been included in the context (which files, what prompts)
+3. **Report** to [security@company.com] with "AI Data Exposure" in subject, within 24 hours
+4. **Do not** attempt to investigate or remediate without security guidance
+
+### Charter violations
+
+| Severity | Examples | Response |
+|----------|----------|---------|
+| **Minor** | Forgot AI attribution in PR, used unapproved MCP briefly | Coaching, remediation |
+| **Moderate** | Used personal account with CONFIDENTIAL data, bypassed a hook | Formal warning, re-training |
+| **Severe** | Processed RESTRICTED data with AI, persistent bypass of controls | HR/legal involvement |
+
+---
+
+## 10. Compliance Mapping
+
+This charter addresses the following compliance requirements:
+
+| Framework | Relevant Controls | This Charter Addresses |
+|-----------|------------------|----------------------|
+| **SOC 2** | CC6.1 (Logical access), CC7.1 (Monitoring), CC9.2 (Vendor risk) | Data classification, MCP registry, audit logging |
+| **ISO 27001** | A.8.3 (Access restriction), A.8.25 (Secure dev lifecycle), A.5.23 (Cloud services) | Approved tools, governance tiers, data handling |
+| **HIPAA** (if applicable) | Security Rule §164.312 (Access control, Audit controls) | RESTRICTED data prohibition, compliance-mode logging |
+| **PCI DSS** (if applicable) | Req 6.3 (Security vulnerabilities), Req 12 (Policy) | PCI data prohibition, code review requirements |
+| **GDPR/CCPA** | Data minimization, purpose limitation | CONFIDENTIAL/RESTRICTED classification, data scope rules |
+
+---
+
+## 11. Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0.0 | [DATE] | [Name] | Initial version |
+
+---
+
+*Questions or exceptions: [engineering-lead@company.com] | Slack: [#ai-tools-governance]*
--- a/examples/scripts/mcp-registry-template.yaml
+++ b/examples/scripts/mcp-registry-template.yaml
@ -0,0 +1,138 @@
+# MCP Registry Template
+# Copy to: .claude/mcp-registry.yaml in your shared config repo
+#
+# Purpose: Track approved MCP servers, their scope, and review status.
+# This is the org-level source of truth for permitted MCP usage.
+#
+# Related: guide/security/enterprise-governance.md §3.2
+
+metadata:
+  organization: "[Your Organization Name]"
+  review_cycle: quarterly
+  last_reviewed: "YYYY-MM-DD"
+  next_review: "YYYY-MM-DD"
+  owner: "platform-team@company.com"
+  policy_doc: "https://your-wiki/ai-usage-charter"
+
+# ─────────────────────────────────────────────────────────────────
+# APPROVED MCPs
+# ─────────────────────────────────────────────────────────────────
+approved:
+
+  # Example: Read-only documentation lookup (LOW risk)
+  - name: context7
+    version: "1.2.3"                # Pin exact version — never "latest"
+    source: "https://github.com/context7/mcp-server"
+    npm_package: "@context7/mcp-server"
+    approved_by: "john.doe@company.com"
+    approved_date: "2026-01-15"
+    expires: "2026-07-15"           # 6 months default
+    data_scope: PUBLIC              # PUBLIC | INTERNAL | CONFIDENTIAL | RESTRICTED
+    risk: LOW                       # LOW | MEDIUM | HIGH
+    rationale: "Read-only documentation lookup. No data egress, no credentials."
+    config:
+      command: npx
+      args: ["-y", "@context7/mcp-server@1.2.3"]
+      env: {}
+
+  # Example: Local reasoning (LOW risk)
+  - name: sequential-thinking
+    version: "0.6.2"
+    source: "https://github.com/modelcontextprotocol/servers"
+    npm_package: "@modelcontextprotocol/server-sequential-thinking"
+    approved_by: "jane.smith@company.com"
+    approved_date: "2026-01-15"
+    expires: "2026-07-15"
+    data_scope: INTERNAL
+    risk: LOW
+    rationale: "Local reasoning only. No network access, no file I/O beyond scratch."
+    config:
+      command: npx
+      args: ["-y", "@modelcontextprotocol/server-sequential-thinking@0.6.2"]
+      env: {}
+
+  # Example: Read-only internal database (MEDIUM risk, shorter expiry)
+  - name: internal-db-readonly
+    version: "2.1.0"
+    source: "internal"              # "internal" for company-built MCPs
+    approved_by: "security@company.com"
+    approved_date: "2026-02-01"
+    expires: "2026-05-01"           # Shorter expiry for higher risk
+    data_scope: CONFIDENTIAL
+    risk: MEDIUM
+    rationale: "Read-only replica. Allowlisted tables exclude PII, payments, audit."
+    restrictions:
+      - "Read-only database user only (no INSERT/UPDATE/DELETE)"
+      - "No access to: users, payments, audit_log, sessions tables"
+      - "Only connect to readonly replica, never primary"
+    config:
+      command: npx
+      args: ["-y", "@company/db-mcp@2.1.0"]
+      env:
+        DB_HOST: "readonly-replica.internal"
+        DB_USER: "claude_readonly"
+        # DB_PASS: loaded from secrets manager at runtime
+
+# ─────────────────────────────────────────────────────────────────
+# PENDING REVIEW
+# ─────────────────────────────────────────────────────────────────
+pending_review:
+
+  - name: github-mcp
+    requested_by: "dev@company.com"
+    requested_date: "2026-03-05"
+    source: "https://github.com/modelcontextprotocol/servers"
+    use_case: "Automated PR creation, issue management"
+    proposed_data_scope: INTERNAL
+    status: under_review            # under_review | sandbox_trial | awaiting_security
+    reviewer: "jane.smith@company.com"
+    expected_decision: "2026-03-20"
+    notes: "Check GitHub token scope — should be limited to specific repos"
+
+# ─────────────────────────────────────────────────────────────────
+# DENIED
+# ─────────────────────────────────────────────────────────────────
+denied:
+
+  - name: browser-automation-mcp
+    denied_date: "2026-02-10"
+    requested_by: "dev2@company.com"
+    reason: >
+      Full browser automation with no scope restriction. Can navigate to arbitrary URLs,
+      exfiltrate data via screenshots, and access internal sites via authenticated sessions.
+      Risk too high without a sandboxed browser environment.
+    alternative: "Use Playwright MCP with restricted URL allowlist if browser access required."
+
+  - name: filesystem-mcp-unrestricted
+    denied_date: "2026-01-20"
+    requested_by: "dev3@company.com"
+    reason: >
+      Unrestricted filesystem access. CVE-2025-53109/53110 not patched in requested version.
+      Would allow sandbox escape via prefix bypass + symlinks.
+    alternative: "Use Claude Code's built-in Read/Write/Edit tools with permissions.deny rules."
+
+# ─────────────────────────────────────────────────────────────────
+# VERSION BUMP POLICY
+# ─────────────────────────────────────────────────────────────────
+version_bump_policy:
+  patch:                            # e.g., 1.2.3 → 1.2.4
+    requires: check_release_notes   # Check for CVEs/breaking changes, then auto-approve
+    approver: tech_lead
+    turnaround: "48h"
+  minor:                            # e.g., 1.2.3 → 1.3.0
+    requires: full_security_review
+    approver: security_team
+    turnaround: "1 week"
+  major:                            # e.g., 1.2.3 → 2.0.0
+    requires: full_security_review + sandbox_trial
+    approver: security_team + engineering_director
+    turnaround: "2 weeks"
+
+# ─────────────────────────────────────────────────────────────────
+# SECURITY INCIDENT CONTACTS
+# ─────────────────────────────────────────────────────────────────
+incident_response:
+  report_to: "security@company.com"
+  slack: "#security-incidents"
+  response_time_sla: "4 hours business hours"
+  escalation: "engineering-director@company.com"
--- a/guide/README.md
+++ b/guide/README.md
@ -34,6 +34,7 @@ Core documentation for mastering Claude Code, organized by topic.
 | [security/sandbox-native.md](./security/sandbox-native.md) | Native Claude Code sandbox: configuration and security model | 10 min |
 | [security/production-safety.md](./security/production-safety.md) | Production safety: guardrails, review gates, rollback strategies | 15 min |
 | [security/data-privacy.md](./security/data-privacy.md) | Data retention and privacy guide | 10 min |
+| [security/enterprise-governance.md](./security/enterprise-governance.md) | **Org-level governance**: usage charters, MCP approval workflow, guardrail tiers (Starter/Standard/Strict/Regulated), compliance | 25 min |

 ---

--- a/guide/ops/ai-traceability.md
+++ b/guide/ops/ai-traceability.md
@ -735,6 +735,23 @@ git-ai init
   - Mandatory human-only review for security-critical?
   - Approval workflow for AI-heavy PRs?

+### Evidence Collection for Auditors
+
+When SOC2, ISO27001, or HIPAA auditors ask for evidence of AI code governance, here's what to provide and where to find it:
+
+| Auditor request | Evidence source | How to generate |
+|-----------------|----------------|-----------------|
+| "Show your AI usage policy" | `docs/ai-usage-charter.md` | See [charter template](../../examples/scripts/ai-usage-charter-template.md) |
+| "Show access controls for AI tools" | `.claude/settings.json` (permissions.deny) | Committed to each project repo |
+| "Show third-party AI component vetting" | `.claude/mcp-registry.yaml` | See [registry template](../../examples/scripts/mcp-registry-template.yaml) |
+| "Show audit log of AI actions" | `~/.claude/projects/**/*.jsonl` | Native session logs |
+| "Show code review process for AI code" | PR descriptions with AI disclosure | PR template + attribution policy |
+| "Show how AI incidents are handled" | Incident response runbook | Add AI section to existing IR docs |
+
+**Practical tip**: Run `./scripts/claude-governance-audit.sh` (see [enterprise-governance.md §5.3](../security/enterprise-governance.md#53-compliance-checking)) before each audit to verify controls are in place and generate a baseline report.
+
+**For session-level audit trails** with full context (prompts, reasoning, tool calls, diffs), Entire CLI creates cryptographically-linked checkpoints in Git. This is one approach among several — evaluate based on your retention requirements and team size. See [§5.1 Entire CLI](#51-entire-cli) for setup and evaluation criteria.
+
 ---

 ## Templates
--- a/guide/ops/observability.md
+++ b/guide/ops/observability.md
@ -916,11 +916,70 @@ find ~/.claude/logs -name "*.jsonl" -mtime +30 -delete

 ---

+---
+
+## Manager Audit Checklist
+
+For engineering managers and team leads who need to verify Claude Code is being used appropriately within their team, these are the practical audit queries.
+
+### Weekly Spot Check (5 minutes)
+
+```bash
+# Did anything unusual happen this week?
+
+# 1. Files accessed outside project scope
+find ~/.claude/projects/ -name "*.jsonl" -newer "$(date -d '7 days ago' +%Y-%m-%d 2>/dev/null || date -v-7d +%Y-%m-%d)" 2>/dev/null | \
+  xargs jq -r 'select(.type == "assistant") |
+    .message.content[]? |
+    select(.type == "tool_use" and .name == "Read") |
+    .input.file_path' 2>/dev/null | \
+  grep -v "^$(pwd)" | sort -u
+
+# 2. Destructive commands run
+find ~/.claude/projects/ -name "*.jsonl" -newer "$(date -d '7 days ago' +%Y-%m-%d 2>/dev/null || date -v-7d +%Y-%m-%d)" 2>/dev/null | \
+  xargs jq -r 'select(.type == "assistant") |
+    .message.content[]? |
+    select(.type == "tool_use" and .name == "Bash") |
+    .input.command' 2>/dev/null | \
+  grep -iE "(drop|delete|truncate|rm -rf|git push --force)"
+```
+
+### Compliance Reporting
+
+For regulated environments, generate a summary of AI activity for auditors:
+
+```bash
+#!/bin/bash
+# Monthly compliance report for Claude Code activity
+
+START_DATE=${1:-$(date -d '30 days ago' +%Y-%m-%d 2>/dev/null || date -v-30d +%Y-%m-%d)}
+END_DATE=${2:-$(date +%Y-%m-%d)}
+REPORT_FILE="ai-activity-report-${START_DATE}-${END_DATE}.json"
+
+echo "Generating compliance report: $START_DATE to $END_DATE"
+
+# Count sessions, tool calls, and file accesses
+jq -s '{
+  report_period: {start: "'"$START_DATE"'", end: "'"$END_DATE"'"},
+  tool_usage: (group_by(.tool) | map({tool: .[0].tool, count: length})),
+  unique_files_accessed: ([.[].file] | unique | length),
+  sessions: ([.[].session_id] | unique | length)
+}' ~/.claude/logs/activity-*.jsonl 2>/dev/null > "$REPORT_FILE" || \
+  echo "No activity logs found. Set up session-logger.sh hook to enable."
+
+echo "Report saved: $REPORT_FILE"
+```
+
+For a full governance setup with automatic audit trail logging, see [Enterprise AI Governance §6.2](../security/enterprise-governance.md#62-audit-trail-setup).
+
+---
+
 ## Related Resources

 - [Session Search Script](../examples/scripts/session-search.sh) - Fast session search & resume
 - [Session Logger Hook](../examples/hooks/bash/session-logger.sh)
 - [Stats Analysis Script](../examples/scripts/session-stats.sh)
+- [Enterprise AI Governance](../security/enterprise-governance.md) - Org-level governance, audit trails, compliance
 - [Third-Party Tools](../ecosystem/third-party-tools.md) - Community GUIs, TUIs, and dashboards (ccusage, ccburn, claude-code-viewer)
 - [Data Privacy Guide](../security/data-privacy.md) - What data leaves your machine
 - [Cost Optimization](./ultimate-guide.md#cost-optimization) - Tips to reduce spend
--- a/guide/roles/adoption-approaches.md
+++ b/guide/roles/adoption-approaches.md
@ -284,6 +284,41 @@ These are starting points, not rules. Team dynamics matter more than headcount.

 > **Emerging approach**: Some organizations explore "corporate AI marketplaces" to pool AI skills, agents, and rules at the organizational level rather than individual teams (Hugo/Writizzy 2026[^hugo2026]). Few documented production implementations yet, but the concept addresses governance at scale.

+### Enterprise Rollout (50+ developers or regulated environments)
+
+At this scale, individual team setups are not enough. You need a shared config baseline that applies consistently across all projects.
+
+**Phased rollout approach:**
+
+**Phase 1 — Foundation (Week 1–2)**: Establish the governance baseline.
+- Create org-level shared config repo (`.claude/` templates per tier)
+- Publish AI Usage Charter (see [charter template](../../examples/scripts/ai-usage-charter-template.md))
+- Start MCP registry with currently-used MCPs (even if just 3 entries)
+- Install global safety hooks on all developer machines via onboarding script
+
+**Phase 2 — Adoption (Week 3–6)**: Roll out project configs.
+- Classify existing projects by tier (Starter / Standard / Strict / Regulated)
+- Bootstrap each project with the appropriate tier config via setup script
+- Add Claude Code onboarding to engineering onboarding checklist
+- Run first governance audit to baseline the current state
+
+**Phase 3 — Optimization (Month 2–3)**: Refine based on friction.
+- Review hook false positive rate — tune rules that block legitimate work
+- Identify MCP requests and process them through registry workflow
+- Add CI/CD governance gates to catch config drift
+- Conduct first quarterly MCP registry review
+
+**Common rollout mistakes at this scale:**
+
+| Mistake | Effect | Fix |
+|---------|--------|-----|
+| Rolling out Strict tier everywhere on day 1 | Developer resistance, workarounds | Start with Standard, move critical projects to Strict |
+| No central config repo | Every team diverges within weeks | Platform team owns shared templates |
+| Governance checks that block work | Developers disable hooks | Warn-only hooks, fix the root cause |
+| No onboarding → charter ignored | Policy exists on paper only | 30-min onboarding session per team |
+
+**For formal compliance programs** (SOC2, ISO27001, HIPAA), the additional requirements around audit trails, data classification, and review cycles are covered in [Enterprise AI Governance](../security/enterprise-governance.md).
+
 [^hugo2026]: Hugo, ["AI's Impact on State of the Art in Software Engineering in 2026"](https://eventuallymaking.io/p/ai-s-impact-on-the-state-of-the-art-in-software-engineering-in-2026), Feb 6, 2026. Based on interviews with Doctolib, Malt, Alan, Google Cloud, Brevo, ManoMano, Ilek, Clever Cloud engineering teams.

 ---
--- a/guide/security/enterprise-governance.md
+++ b/guide/security/enterprise-governance.md
--- a/guide/security/production-safety.md
+++ b/guide/security/production-safety.md
@ -915,7 +915,8 @@ Team settings take precedence, but individuals can opt-in to stricter rules.
 - [Ultimate Guide §9.12 Git Best Practices](./ultimate-guide.md#912-git-best-practices--workflows) — Commit workflow, Plan → Act pattern
 - [Security Hardening Guide](./security-hardening.md) — MCP security, secret protection, hook stack
 - [Data Privacy Guide](./data-privacy.md) — MCP database risks, retention policies
- [Adoption Approaches](../roles/adoption-approaches.md) — Team setup, shared conventions
+- [Enterprise AI Governance](./enterprise-governance.md) — Org-level governance: usage charters, MCP approval workflow, guardrail tiers, compliance
+- [Adoption Approaches](../roles/adoption-approaches.md) — Team setup, shared conventions, enterprise rollout
 - [Plan Mode](./ultimate-guide.md#25-plan-mode) — Safe exploration before execution
 - [Permissions System](./ultimate-guide.md#33-settings--permissions) — Allow/deny rules, hooks

--- a/guide/security/security-hardening.md
+++ b/guide/security/security-hardening.md
@ -855,12 +855,14 @@ Beyond securing Claude Code itself, Anthropic offers a dedicated vulnerability s

 ## See Also

+- [Enterprise AI Governance](./enterprise-governance.md) — Org-level MCP governance (approval workflow, registry, guardrail tiers). This guide covers individual MCP vetting; that guide covers org-level policy.
 - [Data Privacy Guide](./data-privacy.md) — Retention policies, compliance, what data leaves your machine
 - [AI Traceability](../ops/ai-traceability.md) — PromptPwnd vulnerability, CI/CD security, attribution policies
 - [Security Checklist Skill](../examples/skills/security-checklist.md) — OWASP Top 10 patterns for code review
 - [Security Auditor Agent](../examples/agents/security-auditor.md) — Automated vulnerability detection (read-only)
 - [Security Patcher Agent](../examples/agents/security-patcher.md) — Applies patches from audit findings (human approval required)
 - [Security Gate Hook](../examples/hooks/bash/security-gate.sh) — Blocks vulnerable code patterns at write time (7 patterns)
+- [MCP Registry Template](../../examples/scripts/mcp-registry-template.yaml) — YAML format for tracking approved MCPs at org level
 - [Ultimate Guide §7.4](./ultimate-guide.md#74-security-hooks) — Hook system basics
 - [Ultimate Guide §8.6](./ultimate-guide.md#86-mcp-security) — MCP security overview

--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@ -250,6 +250,29 @@ deep_dive:
  sandbox_anti_patterns: "guide/security/sandbox-isolation.md:546"  # Anti-Patterns
  sandbox_comparison_matrix: "guide/security/sandbox-isolation.md:477"  # Comparison Matrix
  sandbox_score: "4/5"
+  # Enterprise AI Governance (guide/security/enterprise-governance.md) - Added 2026-03-10
+  enterprise_governance_guide: "guide/security/enterprise-governance.md"
+  enterprise_governance_local_vs_shared: "guide/security/enterprise-governance.md#1-local-vs-shared-the-governance-split"
+  enterprise_governance_charter: "guide/security/enterprise-governance.md#2-ai-usage-charter"
+  enterprise_governance_charter_template: "examples/scripts/ai-usage-charter-template.md"
+  enterprise_governance_mcp_workflow: "guide/security/enterprise-governance.md#3-mcp-governance-workflow"
+  enterprise_governance_mcp_registry: "guide/security/enterprise-governance.md#32-mcp-registry-format"
+  enterprise_governance_mcp_registry_template: "examples/scripts/mcp-registry-template.yaml"
+  enterprise_governance_guardrail_tiers: "guide/security/enterprise-governance.md#4-guardrail-tiers"
+  enterprise_governance_tier_starter: "guide/security/enterprise-governance.md#tier-1-starter"
+  enterprise_governance_tier_standard: "guide/security/enterprise-governance.md#tier-2-standard"
+  enterprise_governance_tier_strict: "guide/security/enterprise-governance.md#tier-3-strict"
+  enterprise_governance_tier_regulated: "guide/security/enterprise-governance.md#tier-4-regulated"
+  enterprise_governance_policy_at_scale: "guide/security/enterprise-governance.md#5-policy-enforcement-at-scale"
+  enterprise_governance_onboarding_checklist: "guide/security/enterprise-governance.md#52-onboarding-checklist"
+  enterprise_governance_compliance_check: "guide/security/enterprise-governance.md#53-compliance-checking"
+  enterprise_governance_cicd_gates: "guide/security/enterprise-governance.md#55-cicd-gates"
+  enterprise_governance_audit: "guide/security/enterprise-governance.md#6-audit-compliance--governance-structure"
+  enterprise_governance_soc2_iso27001: "guide/security/enterprise-governance.md#61-what-soc2-and-iso27001-auditors-actually-ask"
+  enterprise_governance_audit_trail: "guide/security/enterprise-governance.md#62-audit-trail-setup"
+  enterprise_governance_hook: "examples/hooks/bash/governance-enforcement-hook.sh"
+  enterprise_governance_audience: "Tech leads, engineering managers, security officers"
+  enterprise_governance_scope: "Org-level policy (vs security-hardening.md = individual dev security)"
  # Third-Party Tools (guide/ecosystem/third-party-tools.md) - Added 2026-02-01
  third_party_tools_guide: "guide/ecosystem/third-party-tools.md"
  third_party_tools_cost_tracking: "guide/ecosystem/third-party-tools.md:42"