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. Only receives fast-forward merges from validated staging releases.
staging	Protected (No direct push)	Staging / Homologation (api-stg, app-stg)	Integration branch where feature branches merge. Triggers automated verification and test execution.
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.

---

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:

1. 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.
2. 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.
3. 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