docs: fix stale GHA architecture references; align executor docs with…

… buildspec reality

.github/copilot-instructions.md

@@ -8,21 +8,34 @@ system at Census. The architecture is:
 ```
 SC Console (user fills product form)
     └─> CFN Stack (Custom::* resource)
-            └─> Lambda (centralized in csvd-dev, 229685449397, us-gov-west-1)
+            └─> Lambda tf-run-executor-trigger (csvd-dev, 229685449397, us-gov-west-1)
                     ├─> Validates inputs (Pydantic v2 models)
                     ├─> Fetches GHE token from Secrets Manager
-                    ├─> POSTs repository_dispatch to target repo on GHE
-                    └─> Polls GHA workflow run → returns repo URL + PR URL to CFN
-
-GitHub Enterprise (github.e.it.census.gov)
-    └─> GHA workflow (repository_dispatch event)
-            ├─> Clones the target account repo
-            ├─> Renders HCL/YAML files from templates
-            └─> Commits + opens PR (repo-init → main)
+                    ├─> Starts CodeBuild: tf-run-proposer
+                    └─> Polls CodeBuild → returns PR URL + repo URL to CFN
+
+CodeBuild: tf-run-proposer (csvd-dev)
+    └─> Clones target account repo
+    └─> Renders HCL/YAML files from template repo (Jinja2)
+    └─> Commits rendered files → opens PR (propose/sc-automation → main)
+
+          ↕  Human reviews diff and merges PR  ↕
+
+GHE push webhook → Lambda tf-run-webhook-handler
+    └─> Reads .sc-automation.yml from default branch
+    └─> Starts CodeBuild: tf-run-executor (fire-and-forget)
+
+CodeBuild: tf-run-executor (csvd-dev)
+    └─> Clones account repo at main (post-merge state)
+    └─> Optionally assumes cross-account IAM role (sc-automation-codebuild-role)
+    └─> Runs tf-run apply in LAYER/REGION_DIR
+    └─> Commits post-apply changes (lock file, remote_state symlinks) to main [skip ci]
+    └─> Writes ✅/❌ commit status to GHE
 ```
 
-This replaces the current CodeBuild + terraform-eks-deployment path with a
-GHA-native approach that keeps workflow logic inside the target repos.
+This replaces the current CodeBuild + terraform-eks-deployment path.
+Workflow logic lives in `buildspec-proposer.yml` and `buildspec-executor.yml`
+in this repo; product-type-specific logic lives in `handler.py` in each template repo.
 
 ---
 
@@ -154,7 +167,7 @@ scripts in `/apps/terraform/bin/`. Key behavior:
 - `aws_account_id` and `aws_region` are auto-resolved via `!Sub` in CFN;
   do NOT add them as user-facing SC form parameters
 - Lambda ServiceToken: `arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:{name}`
-- Lambda timeout must be ≥ CodeBuild/GHA poll window (currently 900s)
+- Lambda timeout must be ≥ CodeBuild poll window (currently 900s)
 
 ---
 
@@ -165,8 +178,7 @@ scripts in `/apps/terraform/bin/`. Key behavior:
 - ❌ Do not write temp files to `/tmp` — use `~/tmp`
 - ❌ Do not use `terraform` directly — use `tf` alias (`tf plan`, `tf apply`)
 - ❌ Do not run AWS CLI/boto3 without `export AWS_DEFAULT_REGION=us-gov-west-1`
-- ❌ Do not add `vpc_id` — field is `vpc_name`
-- ❌ Do not use `HappyPathway/terraform-github-repo` public module
-- ✅ DO use `CSVD/terraform-github-repo` (https://github.e.it.census.gov/CSVD/terraform-github-repo)
 - ✅ DO use `gh` CLI for PR management
 - ✅ DO use `GH_HOST=github.e.it.census.gov` for all GHE commands
+- ✅ Cross-account role name is `sc-automation-codebuild-role` — must exist in every target
+  account and trust the CodeBuild IAM role from csvd-dev before the first executor run

docs/HOW-IT-WORKS.md

@@ -172,12 +172,16 @@ a watched account repo. Never triggered by a user or SC product.
 | `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` |
 
+> **ADR-002 (Proposed):** A future revision will add `VAULT_AWS_ROLE` so the executor
+> obtains short-lived credentials from the Vault AWS Secrets Engine instead of
+> assuming `sc-automation-codebuild-role` directly. Until ADR-002 is accepted and
+> implemented, `buildspec-executor.yml` uses the static `aws sts assume-role` model.
+
 **Build definition:** `buildspec-executor.yml`
 
 ---

docs/repo-vars-and-secrets.md

@@ -239,7 +239,8 @@ aws secretsmanager create-secret \
 
 - **Secret rotation:** Implement automatic rotation for long-lived credentials
 - **Environment-scoped secrets:** Dev/test/prod variants of secrets per repo
-- **Organization-level variables:** Push shared variables once to org level instead
-  of per-repo, reducing GHE API call volume
+- **Organization-level SSM parameters:** Consolidate shared variables (e.g. `TERRAFORM_VERSION`)
+  into a single SSM path read once at Lambda invocation rather than duplicated across
+  every `by-type/` subtree, reducing SSM API call volume
 - **Validation rules:** Reject variable names that conflict with CodeBuild reserved
   names (e.g. `CODEBUILD_*`, `AWS_*` built-ins)