Project Governance & Linear Platform

1. Sovereign Workspace & Linear Project Portfolio

The GERCIA ecosystem utilizes Linear (https://linear.app/gercia) as its central engineering governance, agile orchestration, and issue-tracking platform. Both human developers and AI pair-programming agents (Antigravity) interface directly with Linear to coordinate tasks, sprint cycles, and technical deliverables.

flowchart TD
    WORKSPACE["GERCIA Linear Workspace<br>(https://linear.app/gercia)"]

    subgraph TEAMS ["Linear Engineering Teams"]
        T_ENG["GERCIA Engineering (Key: ENG)<br>SaaS Engine, Healthcare Verticals, .NET 10 Hosts, Angular SPA, Mobile KMP, Edge"]
        T_OPS["GERCIA Operations (Key: OPS)<br>Customer Success, Onboarding, Legal, Billing"]
        T_MKT["GERCIA Marketing (Key: MKT)<br>Public Portal, Brand Assets, Design System"]
    end

    subgraph AI_ORCHESTRATION ["Native Model Context Protocol (MCP)"]
        AGENT["AI Assistant (Antigravity)<br>Linear MCP Client"]
        MCP["https://mcp.linear.app/mcp<br>(Authenticated via LINEAR_API_KEY)"]
    end

    WORKSPACE --> T_ENG & T_OPS & T_MKT
    AGENT <--> MCP
    MCP <--> WORKSPACE

Team Portfolio Overview

Team Name	Key	Scope	Core Responsibilities
GERCIA Engineering	`ENG`	SaaS Platform Engine, Healthcare Verticals, Hosts, Clients	Core domain modules (`Foundation/`, `Health/`, `Veterinary/`, `Operations/`), backend server (`Gercia.Server`), frontend SPA (`@gercia/app`), mobile client (`GERCIA Care`), and edge agent (`Gercia.Edge`).
GERCIA Operations	`OPS`	Platform Management & Compliance	Enterprise onboarding, billing reconciliation, Cloudflare Zero Trust user access, and sanitary compliance audits (CFM, ANVISA).
GERCIA Marketing	`MKT`	Institutional Portal & Brand	Public institutional portal (`apps/site` → `gercia.com.br`), sovereign veterinary portal (`apps/site-vet` → `gercia.vet.br`), documentation portals (`docs/public`), brand identity vectors, and typography tokens.

2. Agile Sprint Cycles & State Machine

Linear operates on synchronized 2-week Sprint Cycles starting on Mondays at 09:00 BRT:

stateDiagram-v2
    [*] --> Triage: New Issue Ingestion
    Triage --> Backlog: Groomed & Prioritized
    Backlog --> Todo: Assigned to Active Cycle
    Todo --> InProgress: Development Started / Branch Created
    InProgress --> InReview: PR / MR Created & Linked
    InReview --> Done: Merged to staging / main & Verified
    InProgress --> Canceled: Scope Decommissioned
    Backlog --> Canceled: Deprecated
    Done --> [*]

Workflow State Definitions

State Name	State Type	Description & Entry Invariants
Triage	`Triage`	Unprocessed incoming issue. Must be reviewed, assigned a team, and groomed within 24 hours.
Backlog	`Backlog`	Well-defined ticket awaiting prioritization for a future sprint cycle.
Todo	`Unstarted`	Prioritized and scheduled in the current active sprint cycle. Ready for immediate pickup.
In Progress	`Started`	Actively being developed by an engineer or AI pair-programmer. Git branch created.
In Review	`Started`	Code completed; pull request / merge request opened for peer review and CI/CD validation.
Done	`Completed`	Code merged, CI/CD pipeline succeeded, and verified in staging or production.
Canceled	`Canceled`	Deprecated, superseded by another architectural decision, or duplicate.

3. Ticket-Driven Engineering Standards

To enforce traceability across git history, CI/CD pipelines, and database migrations, the monorepo mandates strict ticket-driven naming standards:

A. Database Migrations Naming Rule

All EF Core migrations generated via .\dotnet\scripts\add-migration.ps1 must equal the sanitized Linear ticket identifier without arbitrary prose suffixes:

# Produces class 'public partial class ENG123 : Migration'
.\dotnet\scripts\add-migration.ps1 -Ticket ENG-123 -Context Core

B. Git Branch Naming Convention

Branches must include the ticket key and a concise hyphenated summary:

feat/ENG-123-angular-signals-refactor
fix/OPS-45-session-cookie-timeout
chore/ENG-89-update-dependencies

C. Commit Message Format

Commit messages must start with the uppercase ticket identifier followed by a colon and description in American English (en-US):

ENG-123: migrate prescription form to Angular typed reactive form
OPS-45: adjust session expiration policy in OpenIddict STS

4. AI Agent Integration via Native Linear MCP Server

AI pair-programming agents (such as Antigravity) interface with Linear using the official Model Context Protocol (MCP) server, eliminating brittle command-line scripts or curl calls.

Configuration Standard (`.agents/mcp_config.json`)

The Linear MCP server is declared in the monorepo configuration:

{
  "linear": {
    "url": "https://mcp.linear.app/mcp",
    "headers": {
      "Authorization": "Bearer ${LINEAR_API_KEY}"
    }
  }
}

The developer environment syncs this configuration automatically into the global environment during ./start-dev.ps1.

Native Linear MCP Capabilities

Agents leverage native tools for full lifecycle project governance:

list_issues / get_issue: Query backlog, active cycle tasks, and technical acceptance criteria.
save_issue: Create new bugs, tasks, or sub-issues, and update issue states (In Progress, In Review, Done).
save_comment: Document architectural progress, test summaries, and link pull requests directly on the ticket.
list_cycles: Inspect sprint cycle boundaries and delivery dates.

5. Ticket Quality & Language Standards

Language Policy: All Linear issues (titles, descriptions, acceptance criteria, comments) must be written exclusively in American English (en-US). Brazilian regulatory, sanitary, and legal terms (ANVISA RDC 67/2007, Portaria 344/98, CFM Res. 1.821, ICP-Brasil, PIX) are preserved verbatim as proper nouns.

Acceptance Criteria Standard: Every feature or bug fix must define objective, testable acceptance criteria using GitHub-flavored checklist syntax:

### Acceptance Criteria
- [ ] Compounding order status transitions to `Ready` upon final balance confirmation.
- [ ] Audit log record is emitted to `core.audit_history` with actor identity and timestamp.
- [ ] Unit tests pass with 100% assertion coverage.