create-interview-cockpit 0.28.0 → 0.29.0

package/template/client/src/githubActionsLab.ts

@@ -269,6 +269,29 @@ require("fs").readdirSync(".").forEach((f) => console.log("  -", f));
 
 # Docs are reviewed by the docs writer.
 *.md                            @acme/docs @carol
+`,
+
+  // PR template — github.com auto-fills the PR description from this
+  // file. Drop any *.md inside .github/PULL_REQUEST_TEMPLATE/ to get a
+  // multi-template picker instead.
+  ".github/pull_request_template.md": `## Summary
+
+<!-- Brief description of what this PR does and why. -->
+
+## Changes
+
+- 
+
+## Testing
+
+- [ ] Ran \`act -j build\` locally
+- [ ] Updated tests
+- [ ] Updated docs
+
+## Checklist
+
+- [ ] PR title follows conventional-commit style
+- [ ] Linked the related issue (Closes #...)
 `,
 };
 
@@ -489,6 +512,1675 @@ li {
 `,
 };
 
+// ─── Platform Governance Template ────────────────────────────────────────
+//
+// Mirrors a real-world "PLF-governance" mono-repo: one repo that owns
+// Azure PIM/RBAC, Azure Policy, AWS IAM, and user offboarding — all as
+// code, gated by CODEOWNERS + PR template + automated pipelines.
+//
+// In the lab the focus is the .github/ governance plumbing (CODEOWNERS,
+// PR template, validation workflow, deploy workflows). The cloud config
+// files (Terraform, policy JSON) are included so learners can read them,
+// but the workflows are what the lab actually runs.
+
+const GOVERNANCE_FILES: Record<string, string> = {
+  ".github/CODEOWNERS": `# CODEOWNERS for platform-governance.
+#
+# WHAT THIS FILE DOES
+# -------------------
+# GitHub auto-requests review from these owners whenever a matching path
+# changes. Combined with branch protection ("require review from Code
+# Owners"), it means governance changes CANNOT be merged without the
+# right team approving.
+#
+# WHY IT MATTERS
+# --------------
+# Governance is the repo that controls access to everything else. If
+# anyone could merge a PR here, they could grant themselves admin
+# everywhere. CODEOWNERS turns that into a hard, audit-friendly rule.
+#
+# SYNTAX
+# ------
+# <pattern>   <owner1> <owner2> ...
+# Last matching pattern wins.
+
+# Default: platform team owns everything in this repo.
+*                                   @acme/platform-team
+
+# Azure governance — PIM/RBAC and Azure Policy require platform + sec review.
+/azure-pim-solution/                @acme/platform-team @acme/security
+/azure-policy-solution/             @acme/platform-team @acme/security
+
+# AWS governance — same idea, plus AWS-specific reviewers.
+/aws-governance/                    @acme/platform-team @acme/aws-admins
+
+# User lifecycle — IT/IAM team co-owns offboarding logic.
+/user-management/                   @acme/platform-team @acme/iam
+
+# .github changes (workflows, this file, PR template) are highest-trust.
+/.github/                           @acme/platform-leads
+`,
+  ".github/pull_request_template.md": `<!--
+  PR TEMPLATE
+  ===========
+  This template loads automatically when a contributor opens a PR.
+  It forces them to declare WHAT changes, WHERE it deploys, and WHETHER
+  it has been validated — so reviewers (and auditors later) have the
+  context required to approve a governance change.
+
+  Senior signal: the repo *governs the process of changing governance*.
+  This is what separates a real platform team from a script collection.
+-->
+
+## ⚠️ Heads-up
+
+Merging to \`main\` may **automatically deploy to production** via the
+workflows in \`.github/workflows/\`. Re-read your diff before requesting
+review.
+
+---
+
+## Type of change
+
+<!-- Pick one. Helps reviewers know what risk to expect. -->
+
+- [ ] Azure PIM / RBAC assignment (user, group, or SPN)
+- [ ] Azure Policy / initiative
+- [ ] AWS IAM role / permission set / policy
+- [ ] User offboarding configuration
+- [ ] CI / workflow / repo governance
+- [ ] Documentation only
+
+## Environments affected
+
+- [ ] Test
+- [ ] Staging
+- [ ] Production
+- [ ] FedRAMP Test
+- [ ] FedRAMP Prod
+
+## Pre-merge checklist
+
+- [ ] Object IDs (user/group/SPN) verified to exist in the target tenant
+- [ ] Policy / role tested in **Test** before promotion
+- [ ] No secrets committed (use OIDC / federated identity, not keys)
+- [ ] Platform team notified in \`#platform-governance\` if scope is large
+- [ ] Terraform \`plan\` reviewed in CI artifacts
+
+## What does this change do?
+
+<!-- Plain English, 2–4 sentences. Pretend the reviewer is on call. -->
+
+## How was it tested?
+
+<!-- e.g. "applied to test subscription, confirmed role assignment in
+     Azure portal, ran \`terraform plan\` against staging — no drift." -->
+
+## Rollback plan
+
+<!-- How do we undo this if it breaks production after merge? -->
+`,
+  ".github/workflows/aws-governance-deploy.yml": `# Deploy AWS IAM roles, permission sets, and policies via Terraform.
+#
+# Notice the structural twin to azure-pim-deploy.yml — *that consistency
+# is itself a governance signal*. Multi-cloud governance is much easier
+# to audit when every cloud's pipeline looks the same.
+
+name: AWS governance deploy
+
+on:
+  push:
+    branches: [main]
+    paths: ["aws-governance/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  deploy:
+    strategy:
+      fail-fast: true
+      max-parallel: 1
+      matrix:
+        environment: [test, staging, prod]
+    runs-on: ubuntu-latest
+    environment: \${{ matrix.environment }}
+    concurrency:
+      group: aws-governance-\${{ matrix.environment }}
+    steps:
+      - uses: actions/checkout@v4
+
+      # OIDC -> AWS. The role's trust policy restricts which repo and
+      # which branch can assume it (see aws-governance/iam/github-oidc-role.tf
+      # in a real repo). No static AWS keys anywhere.
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: \${{ vars.AWS_DEPLOY_ROLE_ARN }}
+          aws-region: us-east-1
+
+      - uses: hashicorp/setup-terraform@v3
+      - working-directory: aws-governance
+        run: |
+          terraform init -backend-config=envs/\${{ matrix.environment }}.backend.hcl
+          terraform apply -auto-approve -var-file=envs/\${{ matrix.environment }}.tfvars
+`,
+  ".github/workflows/azure-pim-deploy.yml": `# Deploy Azure PIM + RBAC assignments.
+#
+# TRIGGERED BY
+# ------------
+# - Push to main (after PR review) -> deploy to test, then staging, then prod.
+# - Manual dispatch -> targeted env, useful for re-runs / drift correction.
+# - Schedule -> nightly drift check (no apply, just plan).
+#
+# DESIGN NOTES
+# ------------
+# - Environments use GitHub "Environment" protection rules so prod
+#   requires a separate approver beyond the PR review.
+# - Concurrency group prevents two deploys racing on the same env state.
+# - OIDC federation, no long-lived service principal secrets.
+
+name: Azure PIM deploy
+
+on:
+  push:
+    branches: [main]
+    paths: ["azure-pim-solution/**"]
+  workflow_dispatch:
+    inputs:
+      environment:
+        type: choice
+        options: [test, staging, prod, fedramp-test, fedramp-prod]
+        default: test
+  schedule:
+    # Nightly drift check at 02:00 UTC. Plan only, no apply.
+    - cron: "0 2 * * *"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  plan-and-apply:
+    strategy:
+      # Promote sequentially: test -> staging -> prod. If test fails,
+      # later envs never run. fail-fast=true is the safer default here.
+      fail-fast: true
+      max-parallel: 1
+      matrix:
+        environment:
+          - test
+          - staging
+          - prod
+    runs-on: ubuntu-latest
+    environment: \${{ matrix.environment }}
+    concurrency:
+      # One deploy per env at a time. Avoids racing Terraform state.
+      group: azure-pim-\${{ matrix.environment }}
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: azure/login@v2
+        with:
+          client-id: \${{ vars.AZURE_DEPLOY_CLIENT_ID }}
+          tenant-id: \${{ vars.AZURE_TENANT_ID }}
+          subscription-id: \${{ vars.AZURE_SUBSCRIPTION_ID }}
+
+      - uses: hashicorp/setup-terraform@v3
+
+      - name: Terraform init
+        working-directory: azure-pim-solution
+        run: terraform init -backend-config=envs/\${{ matrix.environment }}.backend.hcl
+
+      - name: Terraform plan
+        working-directory: azure-pim-solution
+        run: terraform plan -var-file=envs/\${{ matrix.environment }}.tfvars -out=tfplan
+
+      # Drift-only mode: scheduled nightly run stops here.
+      - name: Skip apply on schedule
+        if: github.event_name == 'schedule'
+        run: echo "Drift check complete; not applying."
+
+      - name: Terraform apply
+        if: github.event_name != 'schedule'
+        working-directory: azure-pim-solution
+        run: terraform apply -auto-approve tfplan
+`,
+  ".github/workflows/azure-policy-deploy.yml": `# Deploy Azure Policy definitions + assignments.
+#
+# Azure Policy is the rule engine that audits or blocks resources at
+# create/update time (e.g. "deny storage accounts without TLS 1.2").
+#
+# Same promotion model as PIM: test -> staging -> prod.
+
+name: Azure Policy deploy
+
+on:
+  push:
+    branches: [main]
+    paths: ["azure-policy-solution/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  deploy:
+    strategy:
+      fail-fast: true
+      max-parallel: 1
+      matrix:
+        environment: [test, staging, prod]
+    runs-on: ubuntu-latest
+    environment: \${{ matrix.environment }}
+    concurrency:
+      group: azure-policy-\${{ matrix.environment }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: azure/login@v2
+        with:
+          client-id: \${{ vars.AZURE_DEPLOY_CLIENT_ID }}
+          tenant-id: \${{ vars.AZURE_TENANT_ID }}
+          subscription-id: \${{ vars.AZURE_SUBSCRIPTION_ID }}
+
+      # Step 1: register / update every policy DEFINITION (the "rule").
+      - name: Upsert policy definitions
+        run: |
+          for f in azure-policy-solution/policies/*.json; do
+            name=$(jq -r '.name' "$f")
+            az policy definition create \\
+              --name "$name" \\
+              --rules "$(jq -c '.properties.policyRule' "$f")" \\
+              --params "$(jq -c '.properties.parameters // {}' "$f")" \\
+              --mode All \\
+              --description "$(jq -r '.properties.description' "$f")"
+          done
+
+      # Step 2: register / update INITIATIVES (a bundle of policies).
+      - name: Upsert initiatives
+        run: |
+          for f in azure-policy-solution/initiatives/*.json; do
+            az policy set-definition create \\
+              --name "$(jq -r '.name' "$f")" \\
+              --definitions "$(jq -c '.properties.policyDefinitions' "$f")"
+          done
+
+      # Step 3: ASSIGN initiatives to scopes (subscriptions / mgmt groups)
+      # via Terraform, so the assignments are tracked in state and can drift-correct.
+      - uses: hashicorp/setup-terraform@v3
+      - working-directory: azure-policy-solution/assignments
+        run: |
+          terraform init -backend-config=envs/\${{ matrix.environment }}.backend.hcl
+          terraform apply -auto-approve -var-file=envs/\${{ matrix.environment }}.tfvars
+`,
+  ".github/workflows/pr_validations.yml": `# PR validation workflow.
+#
+# WHAT THIS DOES
+# --------------
+# Runs on every PR to enforce baseline hygiene before reviewers spend
+# time on it: PR title format, Terraform fmt/validate, JSON schema for
+# Azure Policy files, and object ID validation for any RBAC assignments.
+#
+# WHY IT MATTERS
+# --------------
+# - Catches "fat-finger" object IDs *before* a deploy fails noisily in prod.
+# - Forces conventional PR titles so the changelog is readable.
+# - Makes "did the author actually run terraform fmt?" not a review topic.
+
+name: PR validations
+
+on:
+  pull_request:
+    branches: [main, "release/*"]
+
+# Least-privilege token. Workflows should never use the default
+# read-write token unless they truly need it.
+permissions:
+  contents: read
+  pull-requests: read
+  id-token: write   # for OIDC federation to Azure / AWS for read-only checks
+
+jobs:
+  pr-title:
+    name: Conventional PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        with:
+          # e.g. "feat(azure-pim): add platform-operator role assignment"
+          types: |
+            feat
+            fix
+            chore
+            docs
+            refactor
+            ci
+          requireScope: true
+
+  terraform:
+    name: Terraform fmt + validate
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Each governance area has its own Terraform root module.
+        dir:
+          - azure-pim-solution
+          - azure-policy-solution/assignments
+          - aws-governance
+    steps:
+      - uses: actions/checkout@v4
+      - uses: hashicorp/setup-terraform@v3
+      - run: terraform -chdir=\${{ matrix.dir }} fmt -check -recursive
+      - run: terraform -chdir=\${{ matrix.dir }} init -backend=false
+      - run: terraform -chdir=\${{ matrix.dir }} validate
+
+  azure-policy-schema:
+    name: Validate Azure Policy JSON
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate every policy definition has required fields
+        # Tiny shell check — real repos use a proper JSON schema, but this
+        # makes the *intent* obvious in a learning template.
+        run: |
+          set -euo pipefail
+          for f in azure-policy-solution/policies/*.json; do
+            jq -e '.properties.policyType and .properties.policyRule' "$f" >/dev/null \\
+              || { echo "::error file=$f::missing properties.policyType or .policyRule"; exit 1; }
+          done
+
+  object-id-validation:
+    name: Validate Azure object IDs exist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # OIDC = OpenID Connect. Lets GitHub Actions assume an Azure
+      # identity WITHOUT storing a long-lived secret. Big security win.
+      - uses: azure/login@v2
+        with:
+          client-id: \${{ vars.AZURE_RO_CLIENT_ID }}
+          tenant-id: \${{ vars.AZURE_TENANT_ID }}
+          subscription-id: \${{ vars.AZURE_SUBSCRIPTION_ID }}
+      - name: Check every principalId in PIM configs
+        run: ./scripts/validate-object-ids.sh azure-pim-solution
+`,
+  ".github/workflows/user-offboarding.yml": `# Scheduled user offboarding.
+#
+# WHAT THIS DOES
+# --------------
+# Compares the source-of-truth tenant (where HR-controlled identities
+# live) against R+D and SaaS tenants. Anyone present in R+D / SaaS but
+# missing from the source-of-truth gets removed.
+#
+# WHY IT'S SCHEDULED
+# ------------------
+# Offboarding is a *continuous* governance concern. People leave between
+# deploys. Running on a cron means stale access shrinks toward zero
+# without a human having to remember.
+#
+# SAFETY RAIL
+# -----------
+# If the diff would remove > N users (default 10), the workflow fails
+# loudly and refuses to proceed. Real platform teams burn themselves
+# *exactly once* on a runaway cleanup script before they add this rail.
+
+name: User offboarding
+
+on:
+  schedule:
+    - cron: "0 6 * * *"   # daily at 06:00 UTC
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  offboard:
+    runs-on: ubuntu-latest
+    environment: prod   # protects production with required reviewers if dispatched manually
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: azure/login@v2
+        with:
+          client-id: \${{ vars.AZURE_OFFBOARD_CLIENT_ID }}
+          tenant-id: \${{ vars.AZURE_TENANT_ID }}
+
+      - name: Run offboarding
+        env:
+          MAX_DELETIONS: "10"
+          SENDGRID_API_KEY: \${{ secrets.SENDGRID_API_KEY }}
+          DRY_RUN: \${{ inputs.dry_run || 'false' }}
+        run: pwsh -File ./user-management/scripts/offboard-users.ps1
+`,
+  "README.md": `# Platform Governance Template
+
+> A learning-friendly clone of a real **platform governance mono-repo**
+> (the kind a Cloud Platform / Platform Engineering team owns at a large
+> company). Use it to study, demo in interviews, or push to GitHub as a
+> real template repo.
+
+---
+
+## What this repo is
+
+This is the **central control repo** for defining and automatically
+applying the rules, permissions, policies, and identity setup used
+across a multi-cloud platform.
+
+In one sentence:
+
+> **Governance as code** — version-controlled config + automated
+> pipelines that keep cloud access, security policies, and user lifecycle
+> consistent across Azure, AWS, and multiple environments.
+
+It is **not** an end-user product. Think of it as the **control room**
+behind the scenes.
+
+---
+
+## What “governance” means here
+
+The platform team uses this repo to make sure cloud environments stay:
+
+1. **secure** — least-privilege access, no rogue admins
+2. **consistent** — same standards in test, staging, prod, and FedRAMP
+3. **auditable** — every change is a reviewed pull request
+4. **automated** — pipelines apply changes, not human clicks
+5. **harder to misconfigure** — policies block bad resources at create time
+
+> **FedRAMP** = Federal Risk and Authorization Management Program — a
+> U.S. government cloud security/compliance baseline. If a repo
+> mentions "FedRAMP Test/Prod", it usually means stricter controls and
+> a separate isolated tenant.
+
+---
+
+## The four governance areas in this mono-repo
+
+| Folder | Area | Cloud | What it controls |
+|---|---|---|---|
+| [\`azure-pim-solution/\`](./azure-pim-solution/) | PIM + RBAC | Azure | Who can elevate to admin, and through which roles |
+| [\`azure-policy-solution/\`](./azure-policy-solution/) | Policy as Code | Azure | Required tags, TLS, naming, diagnostics |
+| [\`aws-governance/\`](./aws-governance/) | IAM + permission sets | AWS | IAM roles, SSO permission sets, deny-policies |
+| [\`user-management/\`](./user-management/) | Offboarding automation | Cross-cloud | Removes stale users from tenants + SaaS |
+
+> **Mono-repo** = one repository containing several related solutions.
+> Each subfolder could be its own repo, but keeping them together makes
+> review, ownership, and cross-cutting changes easier.
+
+---
+
+## How a change actually flows
+
+\`\`\`
+┌────────────┐    ┌──────────┐    ┌─────────┐    ┌───────────┐    ┌──────────┐
+│  Edit a    │ -> │  Open PR │ -> │ Reviews │ -> │ Merge to  │ -> │ Pipeline │
+│  config    │    │          │    │ + CI    │    │   main    │    │ deploys  │
+└────────────┘    └──────────┘    └─────────┘    └───────────┘    └──────────┘
+       │                │              │              │                 │
+       │           PR template     CODEOWNERS    Branch ruleset    GitHub Actions
+       │           (.github/)      (.github/)    (GitHub UI)       (workflows/)
+       │
+   You edit .tf / .json files describing
+   the DESIRED STATE of the cloud.
+\`\`\`
+
+The repo never asks *"what is currently in Azure?"* — it asks
+*"what **should** be there?"* and lets automation reconcile reality.
+
+See [docs/CHANGE-FLOW.md](./docs/CHANGE-FLOW.md) for the full walkthrough.
+
+---
+
+## How to use this template
+
+1. Click **Use this template** on GitHub (after pushing it).
+2. Replace placeholder Azure tenant IDs, AWS account IDs, and team
+   handles with real ones.
+3. Wire the workflows to your cloud credentials (OIDC recommended; see
+   each \`workflows/*.yml\` for the federated identity stub).
+4. Read [\`docs/GLOSSARY.md\`](./docs/GLOSSARY.md) first if PIM, RBAC,
+   IAM, Terraform, and Azure Policy are new to you.
+
+---
+
+## Strong governance signals to look for
+
+If you’re reviewing a real repo like this in an interview or audit,
+these are the high-value signals:
+
+- **CODEOWNERS** restricts who can approve governance changes
+- **PR template** forces declaration of impact + environments
+- **PR validation workflow** standardizes change format
+- **Object ID validation** before deploy (no fake principals slip through)
+- **Terraform state** tracks managed resources and detects drift
+- **Scheduled runs** continuously reconcile cloud reality with repo
+- **Backstage \`catalog-info.yaml\`** registers governance as a real
+  internal platform service with an owner and lifecycle
+
+All of those are present in this template.
+
+---
+
+## One-line interview answer
+
+> A platform governance mono-repo that manages cloud access, policy
+> standards, and user lifecycle as code across Azure and AWS — with
+> mandatory reviews, PR validations, and automated pipelines that deploy
+> approved changes consistently across test, staging, prod, and FedRAMP.
+`,
+  "aws-governance/README.md": `# AWS governance
+
+> AWS uses different primitives than Azure but the *governance pattern*
+> is identical: define identity + permissions as code, gate changes
+> through PR review, deploy via Terraform pipeline.
+>
+> Notice how the folder layout mirrors \`azure-pim-solution/\`. That
+> consistency is deliberate — auditors and new engineers can reason
+> about both clouds with the same mental model.
+
+---
+
+## Key AWS concepts
+
+| AWS term | Plain English | Azure equivalent |
+|---|---|---|
+| **IAM User** | Long-lived human/app credential. Avoid these. | Azure AD user |
+| **IAM Role** | A set of permissions that *something* can assume temporarily. | Azure RBAC role assignment (closer to PIM-eligible) |
+| **IAM Policy** | The actual JSON list of \`Allow\`/\`Deny\` statements. | Azure role definition |
+| **Permission Set** (in AWS Identity Center / SSO) | A pre-baked role users get when they log in via SSO. | Entra group → role assignment |
+| **SCP** (Service Control Policy) | Org-wide deny rule applied to whole accounts. | Azure Policy at management group |
+| **OIDC trust policy** | Lets GitHub Actions (or another IdP) assume a role without secrets. | Azure federated credential |
+
+---
+
+## Folder layout
+
+\`\`\`
+aws-governance/
+├── iam/
+│   ├── platform-admin-role.tf       # role for platform team SSO users
+│   └── developer-permission-set.tf  # SSO permission set for app teams
+└── policies/
+    └── deny-root-actions.json       # SCP: nobody uses the root account
+\`\`\`
+
+---
+
+## How a change lands
+
+Same flow as Azure: PR → CODEOWNERS review → merge → \`aws-governance-deploy.yml\`
+runs Terraform per environment using OIDC-federated credentials.
+
+The \`role-to-assume\` in CI has a **trust policy** that restricts the
+role to *this exact repo on the main branch*. That's how you safely
+let CI hold cloud admin without giving developers the keys.
+`,
+  "aws-governance/iam/developer-permission-set.tf": `# Permission Set assigned to developers via AWS Identity Center (SSO).
+#
+# A "permission set" in AWS SSO = the bundle that becomes an IAM Role
+# in each member account when a user is granted it. So defining it once
+# here gives developers consistent access across every AWS account in
+# the organisation.
+
+resource "aws_ssoadmin_permission_set" "developer_readonly" {
+  name             = "DeveloperReadOnly"
+  description      = "Read-only access for developers. Includes CloudWatch Logs read so they can debug their apps."
+  instance_arn     = var.sso_instance_arn
+  session_duration = "PT4H"   # 4 hours — short sessions reduce token theft blast radius
+}
+
+# AWS-managed policy gives broad read-only.
+resource "aws_ssoadmin_managed_policy_attachment" "developer_readonly" {
+  instance_arn       = var.sso_instance_arn
+  managed_policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
+  permission_set_arn = aws_ssoadmin_permission_set.developer_readonly.arn
+}
+
+# Inline policy: extra grants we cannot get from a managed policy.
+# Keeping these tiny and named is much easier to review than one giant
+# 200-line custom policy.
+resource "aws_ssoadmin_permission_set_inline_policy" "developer_readonly_logs" {
+  instance_arn       = var.sso_instance_arn
+  permission_set_arn = aws_ssoadmin_permission_set.developer_readonly.arn
+  inline_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect = "Allow"
+      Action = [
+        "logs:GetLogEvents",
+        "logs:FilterLogEvents",
+        "logs:StartQuery",
+        "logs:StopQuery",
+        "logs:GetQueryResults"
+      ]
+      Resource = "*"
+    }]
+  })
+}
+
+variable "sso_instance_arn" { type = string }
+`,
+  "aws-governance/iam/platform-admin-role.tf": `# IAM Role used by the platform team via AWS SSO (Identity Center).
+#
+# The role's *trust policy* controls WHO can assume it.
+# The attached *managed policies* control WHAT they can do once assumed.
+# Splitting the two is what makes IAM least-privilege thinking work.
+
+resource "aws_iam_role" "platform_admin" {
+  name        = "platform-admin"
+  description = "Assumed by platform team members via AWS SSO. Tightly scoped — does NOT include billing or org-level write."
+
+  # Trust policy: only the SSO-managed identity provider can let users
+  # assume this role, and only from sessions tagged with the platform
+  # group. No long-lived keys, no other accounts.
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect = "Allow"
+      Principal = {
+        Federated = "arn:aws:iam::\${var.account_id}:saml-provider/AWSSSO"
+      }
+      Action = "sts:AssumeRoleWithSAML"
+      Condition = {
+        StringEquals = {
+          "SAML:aud" = "https://signin.aws.amazon.com/saml"
+        }
+      }
+    }]
+  })
+
+  # Permissions boundary = a hard ceiling. Even if someone attaches a
+  # broader policy by mistake, the boundary still wins. Senior signal.
+  permissions_boundary = aws_iam_policy.platform_admin_boundary.arn
+
+  tags = {
+    "owner"       = "platform-team"
+    "managed-by"  = "platform-governance-repo"
+    "environment" = var.environment
+  }
+}
+
+# The boundary explicitly denies dangerous actions that platform admins
+# should never need (org root, billing, deleting CloudTrail).
+resource "aws_iam_policy" "platform_admin_boundary" {
+  name        = "platform-admin-boundary"
+  description = "Permissions boundary for the platform-admin role."
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect   = "Allow"
+        Action   = "*"
+        Resource = "*"
+      },
+      {
+        Effect = "Deny"
+        Action = [
+          "organizations:*",
+          "account:*",
+          "aws-portal:*",
+          "cloudtrail:DeleteTrail",
+          "cloudtrail:StopLogging"
+        ]
+        Resource = "*"
+      }
+    ]
+  })
+}
+
+variable "account_id"  { type = string }
+variable "environment" { type = string }
+`,
+  "aws-governance/policies/deny-root-actions.json": `{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "DenyAllRootUserActions",
+      "Effect": "Deny",
+      "Action": "*",
+      "Resource": "*",
+      "Condition": {
+        "StringLike": {
+          "aws:PrincipalArn": "arn:aws:iam::*:root"
+        }
+      }
+    },
+    {
+      "Sid": "DenyDisablingSecurityServices",
+      "Effect": "Deny",
+      "Action": [
+        "guardduty:DeleteDetector",
+        "guardduty:StopMonitoringMembers",
+        "config:DeleteConfigurationRecorder",
+        "config:StopConfigurationRecorder",
+        "cloudtrail:StopLogging",
+        "cloudtrail:DeleteTrail"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+`,
+  "azure-pim-solution/README.md": `# Azure PIM + RBAC as code
+
+> **PIM** = Privileged Identity Management — Microsoft's *just-in-time*
+> elevation system. Instead of being a permanent admin, you "activate"
+> the role for a few hours after MFA + (optionally) approval.
+>
+> **RBAC** = Role-Based Access Control — permissions are granted via
+> roles (Reader, Contributor, custom roles), assigned at a scope
+> (management group, subscription, resource group, resource).
+
+This solution stores the *desired state* of who can do what in Azure,
+and a Terraform pipeline reconciles Azure to match.
+
+---
+
+## Folder layout
+
+\`\`\`
+azure-pim-solution/
+├── main.tf            # wires modules + providers
+├── variables.tf       # env-level inputs (subscription IDs, etc.)
+├── envs/              # per-environment tfvars + backend (gitignored secrets)
+├── roles/             # custom Azure role DEFINITIONS (JSON)
+├── users/             # human identity ASSIGNMENTS (one .tf per user)
+└── spns/              # Service Principal (non-human) ASSIGNMENTS
+\`\`\`
+
+### Why split \`users/\` and \`spns/\`?
+
+> **SPN** = Service Principal — a non-human identity used by apps,
+> pipelines, automation. They have very different review requirements
+> from human users (no MFA, no PIM activation), so keeping them in a
+> separate folder lets CODEOWNERS demand stricter approval on
+> \`spns/\` if needed.
+
+---
+
+## How a new role assignment lands in Azure
+
+1. Engineer adds a \`.tf\` file under \`users/\` or \`spns/\`.
+2. PR opens — \`pr_validations.yml\` checks the principal's object ID exists.
+3. CODEOWNERS forces platform-team + security review.
+4. Merge to \`main\` triggers \`azure-pim-deploy.yml\`:
+   \`test\` → \`staging\` → \`prod\`.
+5. Nightly cron does a \`terraform plan\` (no apply) to detect drift —
+   if someone clicked an assignment in the portal, the next deploy
+   will *remove* it because it's not in code.
+
+---
+
+## Key idea: drift correction
+
+Terraform state remembers what *this repo* manages. So if a panicked
+on-call grants someone Owner manually, the nightly drift plan flags
+it, and the next merge removes it. Governance becomes self-healing
+rather than one-shot.
+`,
+  "azure-pim-solution/main.tf": `# Root module for Azure PIM + RBAC.
+#
+# Tiny on purpose: each user/SPN file in users/ and spns/ is a self-
+# contained resource block, so reviewers see a complete diff per
+# principal in one PR file instead of hunting through a giant module.
+
+terraform {
+  required_version = ">= 1.6.0"
+
+  required_providers {
+    azurerm = {
+      source  = "hashicorp/azurerm"
+      version = "~> 3.110"
+    }
+    azuread = {
+      source  = "hashicorp/azuread"
+      version = "~> 2.50"
+    }
+  }
+
+  # Backend config is supplied per-env via -backend-config in CI.
+  # Keeps test/staging/prod state files isolated and gives blast radius.
+  backend "azurerm" {}
+}
+
+provider "azurerm" {
+  features {}
+  subscription_id = var.subscription_id
+}
+
+provider "azuread" {
+  tenant_id = var.tenant_id
+}
+
+# Custom role definitions live in roles/*.json. Loop over them so adding
+# a new custom role is just dropping a file in the folder.
+locals {
+  custom_roles = {
+    for f in fileset("\${path.module}/roles", "*.json") :
+    trimsuffix(f, ".json") => jsondecode(file("\${path.module}/roles/\${f}"))
+  }
+}
+
+resource "azurerm_role_definition" "custom" {
+  for_each    = local.custom_roles
+  name        = each.value.Name
+  scope       = "/subscriptions/\${var.subscription_id}"
+  description = each.value.Description
+  permissions {
+    actions          = each.value.Actions
+    not_actions      = each.value.NotActions
+    data_actions     = lookup(each.value, "DataActions", [])
+    not_data_actions = lookup(each.value, "NotDataActions", [])
+  }
+  assignable_scopes = each.value.AssignableScopes
+}
+`,
+  "azure-pim-solution/roles/platform-operator.json": `{
+  "Name": "Platform Operator",
+  "Description": "Day-to-day platform ops: read everything, restart resources, rotate keys. NOT permitted to grant access or delete resources — those require activating the Owner-level break-glass role through PIM.",
+  "Actions": [
+    "*/read",
+    "Microsoft.Compute/virtualMachines/restart/action",
+    "Microsoft.Web/sites/restart/action",
+    "Microsoft.KeyVault/vaults/keys/rotate/action",
+    "Microsoft.Insights/diagnosticSettings/*"
+  ],
+  "NotActions": [
+    "Microsoft.Authorization/*/Write",
+    "Microsoft.Authorization/*/Delete"
+  ],
+  "AssignableScopes": [
+    "/subscriptions/00000000-0000-0000-0000-000000000000"
+  ]
+}
+`,
+  "azure-pim-solution/spns/platform-deploy-spn.tf": `# SPN (Service Principal) assignment — non-human identity used by a
+# deployment pipeline. SPNs do NOT use PIM (no human to MFA/activate),
+# so they get a permanent assignment scoped as narrowly as possible.
+#
+# Senior signal: the *scope* here is a single resource group, not the
+# whole subscription. Every extra scope level is blast radius.
+
+data "azuread_service_principal" "platform_deploy" {
+  display_name = "platform-deploy-spn"
+}
+
+resource "azurerm_role_assignment" "platform_deploy_contributor" {
+  scope                = "/subscriptions/\${var.subscription_id}/resourceGroups/rg-platform-\${var.environment}"
+  role_definition_name = "Contributor"
+  principal_id         = data.azuread_service_principal.platform_deploy.object_id
+  description          = "Used by GitHub Actions to deploy platform infra. See PLAT-987."
+}
+`,
+  "azure-pim-solution/users/octocat.tf": `# PIM-eligible role assignment for a human user.
+#
+# \`azurerm_role_assignment\` would be a *permanent* (active) grant.
+# \`azurerm_pim_eligible_role_assignment\` makes the user ELIGIBLE — they
+# must "activate" the role via PIM (MFA + optional approval) for a
+# limited time window. This is the least-privilege default for humans.
+
+# Look up the user by UPN so we never hard-code object IDs in the file
+# the human reads. The data source fails the plan if the user does not
+# exist — that's the "object ID validation" governance signal.
+data "azuread_user" "octocat" {
+  user_principal_name = "octocat@acme.example"
+}
+
+resource "azurerm_pim_eligible_role_assignment" "octocat_platform_operator" {
+  scope              = "/subscriptions/\${var.subscription_id}"
+  role_definition_id = azurerm_role_definition.custom["platform-operator"].role_definition_resource_id
+  principal_id       = data.azuread_user.octocat.object_id
+
+  schedule {
+    start_date_time = "2026-01-01T00:00:00Z"
+    expiration {
+      # Hard cap on how long the *eligibility* lasts. After this,
+      # the user must be re-assigned via a fresh PR. Forces periodic
+      # access review — a SOC2 / ISO 27001 friendly pattern.
+      end_date_time = "2026-12-31T23:59:59Z"
+    }
+  }
+
+  justification = "Day-to-day platform ops; ticketed in PLAT-1234."
+}
+`,
+  "azure-pim-solution/variables.tf": `variable "subscription_id" {
+  type        = string
+  description = "Target Azure subscription for RBAC assignments."
+}
+
+variable "tenant_id" {
+  type        = string
+  description = "Azure AD / Entra tenant the principals live in."
+}
+
+variable "environment" {
+  type        = string
+  description = "test | staging | prod | fedramp-test | fedramp-prod"
+  validation {
+    condition     = contains(["test", "staging", "prod", "fedramp-test", "fedramp-prod"], var.environment)
+    error_message = "environment must be one of test, staging, prod, fedramp-test, fedramp-prod."
+  }
+}
+`,
+  "azure-policy-solution/README.md": `# Azure Policy solution
+
+> **Azure Policy** = Azure's built-in rule engine. Each policy is a
+> JSON object with two halves:
+>
+> - **\`if\`** — which resources does this rule care about?
+> - **\`then\`** — what should happen? (\`audit\`, \`deny\`, \`append\`, \`modify\`,
+>   \`deployIfNotExists\`)
+>
+> Policies enforce things like "deny storage accounts without TLS 1.2"
+> or "audit any resource missing a \`cost-center\` tag" — at create AND
+> update time, before the resource exists.
+
+---
+
+## Folder layout
+
+\`\`\`
+azure-policy-solution/
+├── policies/        # individual policy DEFINITIONS (the rules)
+├── initiatives/     # bundles of policies (a.k.a. policySets)
+└── assignments/     # Terraform that ASSIGNS initiatives to scopes
+\`\`\`
+
+### Why three folders?
+
+This is the **define → bundle → assign** model that scales:
+
+1. **Define** a small focused rule once (e.g. "min TLS 1.2").
+2. **Bundle** related rules into an initiative (e.g. "Platform Baseline").
+3. **Assign** the initiative to a management group / subscription, with
+   parameters per environment.
+
+Without this split you end up with copy-pasted policy JSON sprinkled
+across subscriptions and no one knows what the truth is.
+
+---
+
+## How a new policy lands
+
+1. PR adds a \`.json\` to \`policies/\` (and optionally adds it to an
+   initiative in \`initiatives/platform-baseline.json\`).
+2. \`pr_validations.yml\` checks the JSON has \`policyType\` and \`policyRule\`.
+3. CODEOWNERS forces platform + security review.
+4. Merge → \`azure-policy-deploy.yml\`:
+   - upserts every policy definition (\`az policy definition create\`)
+   - upserts every initiative (\`az policy set-definition create\`)
+   - runs Terraform in \`assignments/\` to bind initiatives to scopes
+5. The next time anyone creates / updates a resource, Azure evaluates
+   the policy. \`audit\` mode reports it; \`deny\` mode blocks it.
+
+---
+
+## \`audit\` first, \`deny\` later
+
+Rolling out \`deny\` straight to prod breaks people. The mature pattern:
+
+1. Ship in \`audit\` mode in test → see how many resources are non-compliant.
+2. Communicate, give teams a fix window.
+3. Flip the parameter to \`deny\` in test → staging → prod.
+
+The policies in this template expose \`effect\` as a parameter so the
+assignment in each environment can choose \`audit\` or \`deny\` without
+touching the policy definition.
+`,
+  "azure-policy-solution/assignments/production.tf": `# Assign the "platform-baseline" initiative to a subscription.
+#
+# This is where the *audit vs deny* decision is made per environment.
+# - test:    effect = "audit"  (so devs see warnings but aren't blocked)
+# - staging: effect = "audit"  (one last chance to fix)
+# - prod:    effect = "deny"   (real enforcement)
+
+terraform {
+  required_version = ">= 1.6.0"
+  required_providers {
+    azurerm = { source = "hashicorp/azurerm", version = "~> 3.110" }
+  }
+  backend "azurerm" {}
+}
+
+provider "azurerm" {
+  features {}
+  subscription_id = var.subscription_id
+}
+
+variable "subscription_id" { type = string }
+variable "environment"     { type = string }
+
+# Effect chosen per environment. tfvars files in envs/ override this.
+variable "baseline_effect" {
+  type        = string
+  description = "audit | deny | disabled"
+  default     = "audit"
+}
+
+resource "azurerm_subscription_policy_assignment" "platform_baseline" {
+  name                 = "platform-baseline-\${var.environment}"
+  display_name         = "Platform baseline (\${var.environment})"
+  subscription_id      = "/subscriptions/\${var.subscription_id}"
+  policy_definition_id = "/subscriptions/\${var.subscription_id}/providers/Microsoft.Authorization/policySetDefinitions/platform-baseline"
+
+  parameters = jsonencode({
+    effect = { value = var.baseline_effect }
+  })
+
+  # Identity required so deployIfNotExists / modify policies can act
+  # even though this assignment uses simpler audit/deny effects today —
+  # adding the identity now means future policies don't require a
+  # breaking-change re-assignment.
+  identity {
+    type = "SystemAssigned"
+  }
+  location = "eastus"
+}
+`,
+  "azure-policy-solution/initiatives/platform-baseline.json": `{
+  "name": "platform-baseline",
+  "properties": {
+    "displayName": "Platform baseline initiative",
+    "description": "Bundle of policies every subscription must comply with. Adding a new platform-wide rule = adding a line here, then re-assigning the initiative.",
+    "policyType": "Custom",
+    "metadata": {
+      "category": "Platform",
+      "version": "1.0.0"
+    },
+    "parameters": {
+      "effect": {
+        "type": "String",
+        "allowedValues": ["audit", "deny", "disabled"],
+        "defaultValue": "audit"
+      }
+    },
+    "policyDefinitions": [
+      {
+        "policyDefinitionReferenceId": "require-cost-center-tag",
+        "policyDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/require-cost-center-tag",
+        "parameters": { "effect": { "value": "[parameters('effect')]" } }
+      },
+      {
+        "policyDefinitionReferenceId": "storage-min-tls-1-2",
+        "policyDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/storage-min-tls-1-2",
+        "parameters": { "effect": { "value": "[parameters('effect')]" } }
+      },
+      {
+        "policyDefinitionReferenceId": "storage-naming-convention",
+        "policyDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/storage-naming-convention",
+        "parameters": { "effect": { "value": "[parameters('effect')]" } }
+      }
+    ]
+  }
+}
+`,
+  "azure-policy-solution/policies/min-tls-version.json": `{
+  "name": "storage-min-tls-1-2",
+  "properties": {
+    "displayName": "Storage accounts must use TLS 1.2 or higher",
+    "description": "Block (or audit) any storage account whose minimumTlsVersion is below TLS1_2. Default-deny in prod; audit in test.",
+    "policyType": "Custom",
+    "mode": "All",
+    "metadata": {
+      "category": "Storage",
+      "version": "1.0.0"
+    },
+    "parameters": {
+      "effect": {
+        "type": "String",
+        "metadata": { "displayName": "Effect" },
+        "allowedValues": ["audit", "deny", "disabled"],
+        "defaultValue": "audit"
+      }
+    },
+    "policyRule": {
+      "if": {
+        "allOf": [
+          { "field": "type", "equals": "Microsoft.Storage/storageAccounts" },
+          {
+            "anyOf": [
+              { "field": "Microsoft.Storage/storageAccounts/minimumTlsVersion", "exists": "false" },
+              { "field": "Microsoft.Storage/storageAccounts/minimumTlsVersion", "notEquals": "TLS1_2" }
+            ]
+          }
+        ]
+      },
+      "then": {
+        "effect": "[parameters('effect')]"
+      }
+    }
+  }
+}
+`,
+  "azure-policy-solution/policies/require-tags.json": `{
+  "name": "require-cost-center-tag",
+  "properties": {
+    "displayName": "Require cost-center tag on resources",
+    "description": "All resources MUST carry a 'cost-center' tag so finance can chargeback. Effect is parameterised so we can audit first, then deny.",
+    "policyType": "Custom",
+    "mode": "Indexed",
+    "metadata": {
+      "category": "Tags",
+      "version": "1.0.0"
+    },
+    "parameters": {
+      "effect": {
+        "type": "String",
+        "metadata": { "displayName": "Effect" },
+        "allowedValues": ["audit", "deny", "disabled"],
+        "defaultValue": "audit"
+      }
+    },
+    "policyRule": {
+      "if": {
+        "field": "tags['cost-center']",
+        "exists": "false"
+      },
+      "then": {
+        "effect": "[parameters('effect')]"
+      }
+    }
+  }
+}
+`,
+  "azure-policy-solution/policies/storage-naming-convention.json": `{
+  "name": "storage-naming-convention",
+  "properties": {
+    "displayName": "Storage account names must follow corp naming standard",
+    "description": "Enforce the corp naming standard: 'st<env><app><region>###'. Example: stprodpaymentseastus001. Helps cost reporting + ownership lookup.",
+    "policyType": "Custom",
+    "mode": "All",
+    "metadata": {
+      "category": "Naming",
+      "version": "1.0.0"
+    },
+    "parameters": {
+      "effect": {
+        "type": "String",
+        "metadata": { "displayName": "Effect" },
+        "allowedValues": ["audit", "deny", "disabled"],
+        "defaultValue": "audit"
+      }
+    },
+    "policyRule": {
+      "if": {
+        "allOf": [
+          { "field": "type", "equals": "Microsoft.Storage/storageAccounts" },
+          { "field": "name", "notMatch": "st[a-z]{4,}[a-z]{3,}[0-9]{3}" }
+        ]
+      },
+      "then": {
+        "effect": "[parameters('effect')]"
+      }
+    }
+  }
+}
+`,
+  "catalog-info.yaml": `# Backstage catalog metadata.
+#
+# Backstage is a developer portal (open-sourced by Spotify). This file
+# registers governance as a real "internal platform service" with an
+# owner, lifecycle, and discoverable docs — so other engineers can find it.
+#
+# Senior signal: governance is treated as a *product*, not a script dump.
+
+apiVersion: backstage.io/v1alpha1
+kind: System
+metadata:
+  name: platform-governance
+  description: Cross-cloud governance as code (Azure + AWS + user lifecycle)
+  annotations:
+    backstage.io/techdocs-ref: dir:.
+spec:
+  owner: group:platform-team
+  domain: platform
+
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: azure-pim-rbac
+  description: Azure PIM + RBAC assignments deployed via Terraform
+spec:
+  type: service
+  lifecycle: production
+  owner: group:platform-team
+  system: platform-governance
+
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: azure-policy-solution
+  description: Azure Policy definitions + initiative assignments
+spec:
+  type: service
+  lifecycle: production
+  owner: group:platform-team
+  system: platform-governance
+
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: aws-governance
+  description: AWS IAM roles, permission sets, and deny-policies
+spec:
+  type: service
+  lifecycle: production
+  owner: group:platform-team
+  system: platform-governance
+
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: user-offboarding
+  description: Scheduled cross-tenant user offboarding automation
+spec:
+  type: service
+  lifecycle: production
+  owner: group:platform-team
+  system: platform-governance
+`,
+  "docs/CHANGE-FLOW.md": `# Change flow: from edit to enforcement
+
+> Walks through what actually happens when an engineer edits a file in
+> this repo. Use this as your interview answer to the question
+> *"how does governance-as-code actually work day to day?"*.
+
+---
+
+## Scenario
+
+Alice (a platform engineer) needs to give Bob the \`Platform Operator\`
+custom role in the **production** Azure subscription, eligible for
+one year, activated via PIM.
+
+---
+
+## Step 1 — Edit a config file
+
+Alice creates \`azure-pim-solution/users/bob.tf\` (mirroring
+[\`octocat.tf\`](../azure-pim-solution/users/octocat.tf)) with Bob's UPN
+and an end date.
+
+She runs \`terraform fmt\` locally. No Azure changes happen yet — the
+repo is still just files.
+
+---
+
+## Step 2 — Open a pull request
+
+Alice pushes a branch and opens a PR. Several things happen automatically:
+
+| Trigger | Outcome |
+|---|---|
+| \`pull_request_template.md\` loads | Forces Alice to declare type / env / pre-merge checks |
+| \`pr_validations.yml\` runs | PR title check + \`terraform fmt -check\` + \`terraform validate\` + **object ID validation** (does Bob exist in the tenant?) |
+| \`CODEOWNERS\` matches \`azure-pim-solution/\` | Auto-requests \`@acme/platform-team\` and \`@acme/security\` |
+| Branch ruleset on \`main\` | Blocks merge until 1+ approval and all required checks pass |
+
+If Bob's object ID is wrong, the PR fails *here*, not at deploy time.
+That's the **shift-left** governance signal.
+
+---
+
+## Step 3 — Review
+
+Reviewers see:
+- the PR description (forced by the template)
+- a focused diff (one new file, one new principal)
+- green CI showing object IDs validated and Terraform plan output
+
+They approve. Alice merges.
+
+---
+
+## Step 4 — Pipeline deploys
+
+\`azure-pim-deploy.yml\` triggers on push to \`main\` and:
+
+1. Authenticates to Azure via **OIDC** — no long-lived secret in the repo.
+2. Runs \`terraform init\` against the **test** backend.
+3. Runs \`terraform plan\` and \`apply\` for **test**.
+4. If green, advances to **staging**, then **prod**. Each env is a
+   GitHub Environment with its own approver (separate from the PR
+   reviewer — segregation of duties).
+5. The \`concurrency\` group ensures no two deploys race on the same
+   state file.
+
+After this, Bob is *eligible* for \`Platform Operator\` in production.
+
+---
+
+## Step 5 — Bob activates
+
+Bob goes to the Azure portal → PIM → My Roles → activates \`Platform
+Operator\` for, say, 4 hours, with a justification ("PLAT-1234,
+investigating storage latency"). Azure logs the activation. After 4
+hours the access expires automatically.
+
+---
+
+## Step 6 — Drift detection
+
+That night, the scheduled run of \`azure-pim-deploy.yml\` does a plan-only
+pass. If someone clicked an extra assignment in the portal, the next
+real deploy will *remove* it because it's not in code.
+
+Governance becomes self-healing.
+
+---
+
+## Step 7 — Audit time
+
+Six months later, an auditor asks "who approved Bob's prod access?"
+Alice opens the PR link. The PR shows:
+- the diff (the actual config that was applied)
+- the reviewer (CODEOWNERS-enforced)
+- the CI logs (object ID validation result)
+- the merge commit
+- the deploy run (linked from the merge)
+
+That entire chain is the audit trail. No spreadsheets, no screenshots.
+
+---
+
+## Why this matters
+
+Compare to the *without-this-repo* version:
+1. Alice messages a senior engineer in Slack.
+2. Senior engineer clicks around in the portal.
+3. Maybe they forget. Maybe they grant Owner instead of Platform Operator.
+4. There's no record six months later beyond Slack scrollback.
+
+Governance-as-code converts that ad-hoc, lossy process into a
+reviewable, repeatable, auditable workflow.
+`,
+  "docs/GLOSSARY.md": `# Glossary
+
+> Quick definitions of every acronym in this template, written for
+> someone seeing them for the first time. Read this before the
+> sub-folder READMEs and they'll click much faster.
+
+---
+
+## Identity & access
+
+**RBAC — Role-Based Access Control**
+Permissions are bundled into *roles* (Reader, Contributor, custom),
+and you assign roles to identities at a *scope*. Both Azure and AWS
+use this model.
+
+**PIM — Privileged Identity Management** *(Azure)*
+Just-in-time elevation. You're *eligible* for a role; you have to
+*activate* it (with MFA / approval) for a limited window. Reduces
+standing admin access dramatically.
+
+**IAM — Identity and Access Management** *(AWS)*
+The umbrella term for AWS users, roles, policies, and SSO permission
+sets.
+
+**SPN — Service Principal** *(Azure)*
+A non-human identity (apps, pipelines). Cannot use PIM (no human to
+MFA), so it gets permanent narrowly-scoped grants.
+
+**SSO — Single Sign-On**
+Users log into one identity provider and that gives them access to
+many systems without re-authenticating. AWS Identity Center and Entra
+both implement this.
+
+**OIDC — OpenID Connect**
+A federation standard. Lets a workload (e.g. GitHub Actions) prove its
+identity to a cloud and assume a role *without* storing a long-lived
+secret. The biggest practical security win in modern CI/CD.
+
+**MFA — Multi-Factor Authentication**
+Something you know + something you have + (optionally) something you are.
+
+**Object ID**
+A unique GUID Azure assigns to each user/group/service principal. The
+*displayName* can collide; the object ID cannot.
+
+---
+
+## Policy & compliance
+
+**Policy as Code**
+Compliance rules expressed as version-controlled config files, not
+checklists in a Word doc.
+
+**Initiative** *(Azure Policy)*
+A bundle of policies. Easier to assign one initiative to a scope than
+20 individual policies.
+
+**SCP — Service Control Policy** *(AWS)*
+Org-wide deny rules attached to an account or organizational unit. SCPs
+*only restrict*; they cannot grant.
+
+**Permissions Boundary** *(AWS)*
+A hard ceiling on what a role can do, even if a more permissive policy
+is attached. "You can never do more than this, no matter what."
+
+**FedRAMP — Federal Risk and Authorization Management Program**
+US government cloud security/compliance baseline. FedRAMP
+environments usually live in isolated tenants with stricter controls.
+
+**Drift**
+When real cloud state no longer matches the code's desired state.
+Detected by \`terraform plan\`; corrected by \`terraform apply\`.
+
+---
+
+## Tooling
+
+**Terraform / OpenTofu**
+The dominant Infrastructure-as-Code tool. You declare *desired state*;
+Terraform calls cloud APIs to make reality match. State is recorded so
+it knows what to change next time.
+
+**ARM / Bicep**
+Microsoft-native IaC for Azure. Bicep is the friendlier syntax that
+compiles down to ARM JSON.
+
+**Backstage**
+Open-source developer portal originally from Spotify. \`catalog-info.yaml\`
+registers a service so engineers can discover ownership, docs, and
+lifecycle in one place.
+
+**CODEOWNERS**
+A GitHub-native file that auto-requests review from owners when matching
+paths change. Combined with branch protection it becomes a hard gate.
+
+---
+
+## Process
+
+**Change as Code**
+Even *how changes are made* is governed by config: PR templates,
+required reviewers, status checks. Repo controls itself.
+
+**Source of Truth**
+The one trusted location that defines the correct state. In a
+governance-as-code repo, that's the repo itself.
+
+**Blast Radius**
+How much can a single mistake or compromised credential affect? Lower
+is always better. Splitting roles, scoping narrowly, separating tenants
+all shrink blast radius.
+`,
+  "user-management/README.md": `# User management
+
+> Governance is **not** only about granting access. It's also about
+> *removing* access when someone leaves, changes roles, or shouldn't
+> have been there in the first place. Stale access is one of the most
+> common findings in real security audits.
+
+This solution is the *continuous offboarding* engine.
+
+---
+
+## How it works
+
+1. The HR-controlled tenant (call it the **source of truth**) has a
+   list of currently-employed identities.
+2. R+D and SaaS tenants (e.g. SendGrid) have their own user lists that
+   tend to drift — people get added, rarely removed.
+3. A nightly GitHub Actions cron (\`.github/workflows/user-offboarding.yml\`)
+   runs the script in \`scripts/offboard-users.ps1\`:
+   - pulls users from each non-source tenant
+   - diffs against the source of truth
+   - removes anyone present in the side tenant but missing in the source
+4. **Safety rail**: if the diff would delete more than \`MAX_DELETIONS\`
+   users in one run, the script aborts loudly. Forces a human to
+   investigate before mass deletion.
+5. **Dry-run mode**: manual dispatch defaults to \`dry_run=true\`, so
+   you can review what *would* be deleted before doing it for real.
+
+---
+
+## Why it's part of governance, not just IT ops
+
+- Provable, version-controlled deletion logic (auditors love this).
+- Tenants stay aligned without anyone having to remember.
+- Same review/CODEOWNERS gate as access *grants* — symmetry matters.
+`,
+  "user-management/config/tenants.json": `{
+  "sourceOfTruthTenant": {
+    "name": "corp",
+    "tenantId": "00000000-0000-0000-0000-000000000001",
+    "description": "HR-controlled. Authoritative list of current employees."
+  },
+  "managedTenants": [
+    {
+      "name": "rd-test",
+      "tenantId": "00000000-0000-0000-0000-000000000002",
+      "removeIfMissingFromSource": true
+    },
+    {
+      "name": "rd-prod",
+      "tenantId": "00000000-0000-0000-0000-000000000003",
+      "removeIfMissingFromSource": true
+    }
+  ],
+  "saasTargets": [
+    {
+      "name": "sendgrid",
+      "kind": "sendgrid",
+      "removeIfMissingFromSource": true
+    }
+  ]
+}
+`,
+  "user-management/scripts/offboard-users.ps1": `# Cross-tenant offboarding script.
+#
+# Reads config/tenants.json, diffs each managed tenant against the
+# source-of-truth tenant, and removes users who are missing from source.
+#
+# Designed to be safe by default:
+#   - DRY_RUN=true            -> log only, no deletes
+#   - MAX_DELETIONS guard rail -> aborts if diff is too large
+#   - Each tenant runs independently -> one tenant's failure doesn't skip others
+
+#Requires -Version 7.2
+[CmdletBinding()]
+param(
+  [string]$ConfigPath  = "$PSScriptRoot/../config/tenants.json",
+  [int]   $MaxDeletions = [int]($env:MAX_DELETIONS ?? 10),
+  [bool]  $DryRun       = [bool]::Parse(($env:DRY_RUN ?? "true"))
+)
+
+$ErrorActionPreference = "Stop"
+Set-StrictMode -Version Latest
+
+# Real implementations would import Microsoft.Graph and a SendGrid SDK.
+# We stub the calls so this file is readable as a learning artifact.
+function Get-TenantUsers([string]$TenantId) {
+  Write-Host "  [stub] Get-TenantUsers $TenantId"
+  return @()  # array of @{ upn = '...'; objectId = '...' }
+}
+
+function Remove-TenantUser([string]$TenantId, [string]$ObjectId) {
+  Write-Host "  [stub] Remove-TenantUser $TenantId $ObjectId"
+}
+
+function Remove-SendGridUser([string]$Email) {
+  Write-Host "  [stub] Remove-SendGridUser $Email"
+}
+
+# ── 1. Load config ────────────────────────────────────────────────────
+$config = Get-Content $ConfigPath -Raw | ConvertFrom-Json
+$source = Get-TenantUsers -TenantId $config.sourceOfTruthTenant.tenantId
+$sourceSet = @{}
+foreach ($u in $source) { $sourceSet[$u.upn.ToLower()] = $true }
+
+Write-Host "Source-of-truth tenant has $($source.Count) users."
+
+# ── 2. Diff each managed tenant ───────────────────────────────────────
+foreach ($tenant in $config.managedTenants) {
+  Write-Host "\`n=== Tenant: $($tenant.name) ($($tenant.tenantId)) ==="
+  if (-not $tenant.removeIfMissingFromSource) {
+    Write-Host "  Skipped (removeIfMissingFromSource=false)"
+    continue
+  }
+
+  $managed = Get-TenantUsers -TenantId $tenant.tenantId
+  $toRemove = @($managed | Where-Object { -not $sourceSet.ContainsKey($_.upn.ToLower()) })
+  Write-Host "  Would remove: $($toRemove.Count) user(s)."
+
+  if ($toRemove.Count -gt $MaxDeletions) {
+    throw "ABORT: $($toRemove.Count) deletions exceed MaxDeletions=$MaxDeletions for tenant $($tenant.name). Investigate before re-running."
+  }
+
+  foreach ($u in $toRemove) {
+    if ($DryRun) {
+      Write-Host "  [dry-run] would remove $($u.upn)"
+    } else {
+      Remove-TenantUser -TenantId $tenant.tenantId -ObjectId $u.objectId
+      Write-Host "  removed $($u.upn)"
+    }
+  }
+}
+
+# ── 3. SaaS targets (e.g. SendGrid) ───────────────────────────────────
+foreach ($saas in $config.saasTargets) {
+  if ($saas.kind -eq "sendgrid" -and -not $DryRun) {
+    # Real impl: list SendGrid users, diff against $sourceSet, call DELETE.
+    Write-Host "\`nSendGrid offboarding stub — implement Get/Delete via SendGrid API."
+  }
+}
+
+Write-Host "\`nDone. DryRun=$DryRun"
+`,
+};
+
+export const GOVERNANCE_GHA_LAB: GithubActionsLabWorkspace = {
+  version: 1,
+  label: "Platform Governance Template",
+  activeFile: ".github/CODEOWNERS",
+  defaultEvent: "pull_request",
+  defaultWorkflow: ".github/workflows/pr_validations.yml",
+  files: GOVERNANCE_FILES,
+  ghOrg: DEFAULT_GH_LAB_ORG,
+  rulesets: DEFAULT_GH_LAB_RULESETS,
+  pullRequest: DEFAULT_GH_LAB_PULL_REQUEST,
+};
+
 export const DEFAULT_GHA_LAB: GithubActionsLabWorkspace = {
   version: 1,
   label: "GitHub Lab Playground",
@@ -910,6 +2602,7 @@ function cloneGhLabPullRequest(
     reviews,
     ...(lastCheckRun ? { lastCheckRun } : {}),
     ...(typeof pr.title === "string" && pr.title ? { title: pr.title } : {}),
+    ...(typeof pr.body === "string" ? { body: pr.body } : {}),
   };
 }