From dc71d5793dad3075b7e96e9359f98f0a1780ef74 Mon Sep 17 00:00:00 2001
From: Dave Arnold <user@example.com>
Date: Wed, 20 May 2026 13:15:11 -0400
Subject: [PATCH] docs: add CodeBuild Projects Reference section to
 HOW-IT-WORKS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a dedicated section clearly describing what each CodeBuild project does,
how it is triggered, what env vars it receives, and what it does/does not do —
so stakeholders have a single place to understand the two-build model.
---
 docs/HOW-IT-WORKS.md | 98 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)

diff --git a/docs/HOW-IT-WORKS.md b/docs/HOW-IT-WORKS.md
index 4be7d99..bc42ba3 100644
--- a/docs/HOW-IT-WORKS.md
+++ b/docs/HOW-IT-WORKS.md
@@ -101,6 +101,104 @@ See [ADR-001](decisions/001-webhook-auto-apply.md) for the full decision record.
 
 ---
 
+## CodeBuild Projects Reference
+
+There are exactly **two** CodeBuild projects. They are both in csvd-dev and are
+never invoked directly by end users.
+
+---
+
+### `tf-run-proposer`
+
+**Triggered by:** The Proposer SC product (user fills SC form → CFN Custom
+Resource → Lambda starts this build and polls it).
+
+**What it does:**
+
+1. Clones the target account repo from GHE
+2. Checks out (or creates) a proposal branch (default: `propose/sc-automation`)
+3. Renders Jinja2 (`.j2`) template files from `TEMPLATE_REPO` using `TEMPLATE_VARS`
+4. Writes any `EXTRA_FILES` directly into the repo tree
+5. `git commit && git push --force-with-lease`
+6. Opens a pull request (`proposal branch` → `main`) via `gh pr create`; skips
+   if a PR already exists for that branch (idempotent)
+7. Emits `PR_URL=` in POST_BUILD so the Lambda can return it to CloudFormation
+
+**Does NOT run Terraform.** No infrastructure is touched during this build.
+The only changes are committed files in a GHE branch.
+
+**Key env vars (injected per-build):**
+
+| Variable | Source |
+|---|---|
+| `ACCOUNT_REPO` | SC form → CFN → Lambda |
+| `LAYER` | SC form → CFN → Lambda |
+| `REGION_DIR` | SC form → CFN → Lambda |
+| `GIT_BRANCH` | SC form → CFN → Lambda |
+| `TEMPLATE_REPO` | SC form → CFN → Lambda |
+| `TEMPLATE_VARS` | SC form → CFN → Lambda |
+| `EXTRA_FILES` | SC form → CFN → Lambda |
+| `GITHUB_TOKEN` | Lambda reads from Secrets Manager `ghe-runner/github-token` |
+
+**Build definition:** `buildspec-proposer.yml`
+
+---
+
+### `tf-run-executor`
+
+**Triggered by:** The webhook Lambda — automatically on every push to `main` in
+a watched account repo. Never triggered by a user or SC product.
+
+**What it does:**
+
+1. Reads target parameters from the per-build env vars (set by the webhook Lambda
+   from `.sc-automation.yml`)
+2. Clones the account repo at `main` (the post-merge state)
+3. If `TARGET_ACCOUNT_ID` is set: calls `aws sts assume-role` to obtain
+   temporary credentials in the target account
+4. `cd ${LAYER}/${REGION_DIR}`
+5. Runs `tf-run apply` (or `tf-run plan` if `DRY_RUN=true`), optionally starting
+   from a specific `TAG` step
+6. In POST_BUILD: calls the GHE commit status API to write ✅ `success` or
+   ❌ `failure` on the merge commit — visible directly on the PR timeline
+
+**This is the only build that runs Terraform and changes real infrastructure.**
+
+**Key env vars (injected per-build):**
+
+| Variable | Source |
+|---|---|
+| `ACCOUNT_REPO` | Webhook Lambda reads from `.sc-automation.yml` |
+| `LAYER` | Webhook Lambda reads from `.sc-automation.yml` |
+| `REGION_DIR` | Webhook Lambda reads from `.sc-automation.yml` |
+| `TARGET_ACCOUNT_ID` | Webhook Lambda reads from `.sc-automation.yml` |
+| `VAULT_AWS_ROLE` | Webhook Lambda reads from `.sc-automation.yml` |
+| `DRY_RUN` | Webhook Lambda reads from `.sc-automation.yml` |
+| `TF_RUN_START_TAG` | Webhook Lambda reads from `.sc-automation.yml` |
+| `COMMIT_SHA` | Webhook Lambda reads from the GHE push payload |
+| `GITHUB_TOKEN` | Lambda reads from Secrets Manager `ghe-runner/github-token` |
+
+**Build definition:** `buildspec-executor.yml`
+
+---
+
+### Relationship between the two projects
+
+```
+User (SC form)
+    └─> tf-run-proposer   ← renders files, opens PR, touches nothing in AWS
+                               ↓
+               Human reviews diff and merges PR
+                               ↓
+    GHE push webhook ─> tf-run-executor   ← runs Terraform, changes infrastructure
+```
+
+They share the same account repo and the same GHE PAT, but have completely
+separate IAM roles, buildspecs, and trigger paths. The proposer build never has
+Terraform installed; the executor build never opens GitHub PRs.
+
+---
+
 ## Step-by-Step: Propose Flow
 
 ### 1. User fills the SC form