[Feature Request] Add YAML folder and project factory stage with Day-2 GitOps policy change management #400

Feature Description

Add a declarative YAML-driven folder, project, and policy-exception factory stage (fast/stages-aw/2-project-factory, aligned with upstream Cloud Foundation Fabric FAST) paired with an end-to-end Day-2 GitOps CI/CD change-management workflow so operators can provision custom folders and projects or adapt scoped organization policy, firewall, and VPC-SC exceptions through self-contained pull requests without modifying core Stage 0/1 Terraform HCL.

Use Case

Stellar Engine optimizes for initial Day-0/Day-1 greenfield provisioning (0-bootstrap through 3-security) but provides no low-friction Day-2 change-management pathway when mission requirements, organizational structures, or compliance policies evolve:

1. Rigid Folder and Project Topology: fast/stages-aw/1-resman hardcodes folders into fixed Terraform branches (branch-envs.tf, branch-tenants.tf, branch-teams.tf, branch-data-platform.tf, branch-gke.tf, branch-gcve.tf, branch-networking.tf, branch-security.tf, branch-sandbox.tf), and lightweight tenants (var.tenants in branch-tenants.tf) enforce a fixed two-project layout (iac-core-0 and main-0). Although fast/stages-aw/1-resman/branch-project-factory.tf and cicd-project-factory.tf create dev-resman-pf-0 and prod-resman-pf-0 automation service accounts behind var.fast_features.project_factory, fast/stages-aw/ omits the actual 2-project-factory stage that consumes them. Adding a single folder or non-standard workload project today requires editing Stage 1 HCL, running a privileged prod-resman-0 plan/apply against the entire resource hierarchy state, and manually re-threading outputs into Stage 2 Shared VPC attachments and Stage 3 VPC-SC boundaries.
2. Inflexible Policy Adaptation and Waiver Tracking: 0-bootstrap applies organization-wide policy YAML sets (data/org-policies/ and data/custom-org-policies/), while #294 added factories_config.org_policies overrides only for lightweight tenant projects in 1-resman. Operators lack a declarative folder-scoped and project-scoped exception mechanism with structured audit metadata (approver, ticket/POA&M reference, justification, NIST control impact, and expiration date) to safely accommodate customer or mission policy exceptions without editing Stage 0 baseline files.
3. Missing Day-2 GitOps Change Control Pipeline: CI/CD templates in 0-bootstrap/templates/ and 1-resman/templates/ lack automated pull-request plan diffing, compliance-guardrail impact summaries (highlighting diffs touching orgpolicy, vpc-sc, KMS, IAM, or firewall policies for ISSO/AO review), Secure Source Manager + Cloud Build workflows (#198), and CODEOWNERS separation between routine Day-2 folder/project provisioning and privileged Stage 0/1/3 security boundary changes. As a result, routine tasks such as creating a new program folder or granting a scoped policy override turn into multi-week manual change cycles.

Proposed Solution

1. Add fast/stages-aw/2-project-factory (Declarative Folder Hierarchy and Project Factory): Port and adapt upstream Cloud Foundation Fabric FAST 2-project-factory (backed by the existing modules/project-factory module and the branch-pf-* service accounts in 1-resman/branch-project-factory.tf) to manage arbitrary nested folders (data/hierarchy/*.yaml) and workload projects (data/projects/*.yaml) underneath the Assured Workloads compliant folder hierarchy with zero HCL changes. Each YAML definition should declaratively handle folder/project creation, billing linkage and budgets, API activation, CMEK service-agent key grants, Shared VPC host/subnet IAM attachment, group IAM bindings, Secure Tag bindings, and outputs consumed by VPC-SC.
2. Scoped Policy Exception Factory with Governance Schema (fast/assets/schemas/): Support declarative folder-level and project-level organization policy overrides (data/org-policies/), firewall policy rule packs, and VPC-SC ingress/egress exception files validated against JSON schemas that support structured governance fields (change_id, approved_by, justification, controls, expires_at), with CI checks alerting on expired waivers or undocumented relaxations of Assured Workloads guardrails.
3. Day-2 GitOps CI/CD Workflows and Blast-Radius Isolation: Provide ready-to-run pull-request plan (using *-0r read-only service accounts) and post-approval apply (using *-0 service accounts) pipelines for GitHub Actions, GitLab CI, and Secure Source Manager + Cloud Build (#198), including automated PR plan comments, JSON/YAML schema validation, CODEOWNERS approval gates separating platform operators (2-project-factory/data/**) from security/compliance approvers (0-bootstrap/**, 3-security/**, and policy override paths), and integration with out-of-band drift alerting (#46).
4. Day-2 Operations and Change Management Guide (docs/): Add a dedicated Day-2 change-management guide walking through common operational workflows (creating a new folder branch, onboarding a project, applying a time-bounded folder/project org policy exception, and onboarding a new SaaS/PaaS API into VPC-SC and Shared VPC) in a single pull request, mapping PR review records directly to NIST CM-3 / FedRAMP continuous monitoring evidence.

Compliance & Deployment Context

• Target Deployment Type(s):
  • US Region Restricted (e.g., Access Policy constraint)
  • FedRAMP Moderate
  • FedRAMP High
  • DoD IL4
  • DoD IL5
  • All / General
• Relevant NIST 800-53r5 Controls: CM-2 (Baseline Configuration), CM-3 (Configuration Change Control), CM-4 (Impact Analyses), CM-6 (Configuration Settings), AC-6 (Least Privilege), AU-2 (Event Logging).

Reusability Check

Stellar Engine prioritizes reusability.

• I have checked if this functionality can be achieved by extending an existing module or blueprint.
• I have verified that this does not duplicate existing functionality.

modules/project-factory and modules/folder already exist in google/stellar-engine (with full upstream CFF sync tracked in #308), and fast/stages-aw/1-resman/branch-project-factory.tf already provisions the automation service accounts and GCS state buckets intended for a project-factory stage. Extending #294 and #381 into a dedicated YAML-driven 2-project-factory stage and GitOps workflow fills the missing operational layer without duplicating #46, #198, #306, or #388.

Alternatives Considered

• Continuing to expand var.tenants and add bespoke branch-*.tf files inside fast/stages-aw/1-resman couples every Day-2 folder or project request to privileged Stage 1 Terraform state and custom HCL modifications.
• Allowing operators to create folders or adjust organization policies manually in the Google Cloud Console introduces untracked configuration drift and breaks ATO continuous-monitoring evidence chains.

Additional Context

• Affects fast/stages-aw/1-resman, a new fast/stages-aw/2-project-factory stage, fast/assets/schemas/, fast/assets/templates/, and docs/.
• Relates to #46 (Out-of-Band Drift Alerting), #198 (Secure Source Manager CI/CD migration), #294 (tenant project org policy overrides), #306 (stellar CLI), #388 (multi-tenant single-org support), and #399 (Zero Trust access and tag-based microsegmentation).