Source Control, Git Branching & Repository Governance

1. Source Control Architecture & Repository Topology

The GERCIA Platform operates a single sovereign monorepo hosted on GitLab SaaS at https://gitlab.com/gercia/gercia-platform.git. It encapsulates all software verticals, universal foundational engines, infrastructure pipelines, and documentation portals within an unbroken, synchronized version history.

flowchart TD
    DEV["Developer / AI Pair-Programmer (Workstation)"] --> HOOK["Lefthook Pre-Commit Hook<br>(CSharpier Code Formatting)"]
    HOOK --> BRANCH["Feature Branch (feat/ENG-123-*)"]
    BRANCH --> MR["Merge Request / Pull Request (Target: staging)"]
    
    subgraph CI_STAGING ["Staging Continuous Delivery"]
        MR --> STG["Branch: staging"]
        STG --> GCB_STG["Google Cloud Build (Staging)<br>Compile, Test, Docker Build & Staging Rollout"]
    end

    subgraph CI_PRODUCTION ["Production Continuous Delivery"]
        STG --> MAIN["Branch: main (Protected)"]
        MAIN --> GCB_PRD["Google Cloud Build (Production)<br>Zero-Rebuild Promotion & Cloud Run Deployment"]
    end

2. Git Branching Strategy & Release Lifecycle

The platform enforces a structured trunk-based Git workflow optimized for high-frequency healthcare delivery:

Standard Branch Roles

Branch Name	Protection Status	Deployment Environment	Purpose
`main`	Protected (No direct push)	Production (`api.gercia.com.br`, `app.gercia.com.br`)	Production-ready state. Releases are triggered strictly by component-scoped CalVer tags (`<component>/YYYY.MM.DD.N`).
`staging`	Protected (No direct push)	Staging / Homologation (`api-stg`, `app-stg`)	Integration branch where feature branches merge. Triggers continuous delivery to staging environments.
`feat/<TICKET>-<slug>`	Temporary / Developer	Local Workstation	New capabilities and feature implementations (e.g., `feat/ENG-123-angular-signals`).
`fix/<TICKET>-<slug>`	Temporary / Developer	Local Workstation	Bug fixes and patches (e.g., `fix/OPS-45-session-expiry`).
`chore/<TICKET>-<slug>`	Temporary / Developer	Local Workstation	Tooling, dependency updates, and documentation synchronization.

Component-Scoped Production Release Tagging (CalVer)

Production deployments are strictly driven by namespaced Calendar Versioning (CalVer) tags matching pattern <component>/YYYY.MM.DD.N. This decouples vertical releases while maintaining monorepo synchronization:

Component Prefix	Target Pipeline	Target Infrastructure	Example Tag
`app/`	`cloudbuild.app.yaml`	Cloudflare Pages (`gercia-app`)	`app/2026.10.13.1`
`server/`	`cloudbuild.dotnet.yaml`	Artifact Registry & Cloud Run (`Gercia.Server`)	`server/2026.10.13.1`
`site/`	`cloudbuild.site.yaml`	Cloudflare Pages (`gercia` / `gercia.com.br`)	`site/2026.10.13.1`
`vet/`	`cloudbuild.site-vet.yaml`	Cloudflare Pages (`gercia-site-vet` / `gercia.vet.br`)	`vet/2026.10.13.1`
`docs/`	`cloudbuild.docs.yaml`	Cloudflare Pages (`eng` & `docs`)	`docs/2026.10.13.1`
`status/`	`cloudbuild.status.yaml`	Cloudflare Pages (`gercia-status`)	`status/2026.10.13.1`

Step 0: Automated Ancestry Gate

To prevent deploying unmerged commits or out-of-order tags, all production pipelines execute an automated Ancestry Gate at Step 0:

git fetch origin main
if ! git merge-base --is-ancestor "$COMMIT_SHA" origin/main; then
  # Send alert to 🛡️ devsecops and fail build in < 2s
  exit 1
fi

If a release tag is applied to a commit that has not yet been merged into origin/main, Cloud Build aborts the build within 2 seconds and dispatches an immediate notification to the 🛡️ devsecops Google Chat space.

3. Pre-Commit Automation (Lefthook & CSharpier)

To guarantee 100% deterministic code styling without CI/CD lint failures, pre-commit formatting is enforced locally via Lefthook (lefthook.yml):

pre-commit:
  parallel: true
  commands:
    csharpier:
      glob: "*.cs"
      run: csharpier format {staged_files}
      stage_fixed: true

Zero-Touch Formatting: When git commit is executed, Lefthook intercepts all staged .cs files, applies CSharpier formatting, and automatically restages the modified files (stage_fixed: true).
Fast Execution: Written in Go, Lefthook executes in less than 50 milliseconds.

4. AI Pair-Programming Rules (Antigravity Governance)

Every AI coding assistant (Antigravity) operating in the workspace must strictly comply with the monorepo governance rules defined in .agents/AGENTS.md:

NO AUTOMATED COMMITS:
- The AI agent is strictly forbidden from executing commands like git commit or git push.
- The agent prepares file modifications, verifies compilation, and instructs the human developer to execute the commit manually.
ZERO COMMENTS IN C# CODE:
- Adding explanatory comments (// or /* */) in generated or edited C# code is strictly prohibited. The code must be clean, modular, and self-documenting.
LINEAR TICKET-DRIVEN COMMITS:
- Commit messages must reference the active Linear ticket key and describe the change in American English (en-US):
```
ENG-123: synchronize Angular SPA navigation with Cloudflare Pages
```