Project Git Model

Project architecture contract synced from the project module source documents.

Purpose

This document defines the what + why of git as a core project structure.

It explains:

why git is part of the project model rather than a secondary integration
how git should be layered inside a project-centered platform
why Cloudflare's git connection is not sufficient by itself

It exists because "git-backed" can sound correct while still remaining underspecified. This document makes that phrase concrete.

Block Position

Inside the toProject board, this page is the primary definition page of the Version Spine block.

It primarily owns these topics:

Why Git Is Core
Spec Domain
Execution Domain
Knowledge Domain
Review Boundary
Project-Level Git Surface

This page should be read after:

It explains how versioned change supports the project architecture, not how provider tooling works in isolation.

Core Position

Git is the hard execution spine of the project.

It is the boundary for:

versioning
branching
review
recovery
promotion
auditability

Because of this, project must be modeled as a git-backed execution container.

The important point is that git is not just attached to the project after the fact. It shapes what the project is allowed to mean operationally.

Why Git Is Core

Without git as a first-class structure:

intent changes are weakly versioned
execution changes are hard to audit
review has no hard edge
branching and recovery become ambiguous
deployments become disconnected from project meaning

Git is what turns agentic execution from a stream of actions into a system with durable boundaries.

That is why git belongs in architecture language, not just implementation notes.

Git Layers

The platform should not treat all git concerns as the same thing.

There are at least three different layers:

This separation is necessary because earlier thinking risked collapsing provider behavior, deploy behavior, and project semantics into one vague "git integration."

1. Provider Layer

This is the layer exposed by Git providers such as GitHub or GitLab.

It includes:

repositories
branches
pull requests
review state
merge state
webhooks / provider signals

This layer answers:

where does the versioned source live
how does collaboration happen around it

This is the layer GitHub or GitLab is naturally strongest at.

2. Deploy Layer

This is the layer where runtime platforms connect to git for build and deploy purposes.

Cloudflare's repository connection belongs here.

It includes:

repository connection
branch-to-environment mapping
build triggers
deployment triggers
preview / production promotion

This layer answers:

how does versioned source reach runtime environments

This is the layer Cloudflare naturally occupies when it connects to a repository for build and deploy.

3. Project Orchestration Layer

This is the layer that the project module must own conceptually.

It includes:

repository bindings
domain meaning
execution rules around versioned work
mapping between project semantics and git surfaces

This layer answers:

what role does each repository play in this project
how does project intent connect to execution and knowledge
what is the version spine of the project as a product object

This is the layer the project module must own conceptually, because neither provider nor deploy platform can define project meaning on their own.

Cloudflare Git Connection Is Not The Whole Git Architecture

Cloudflare can connect a Worker or application to a git repository and use it for build and deploy flows.

That is useful, but it only solves one layer:

deploy binding

It does not define:

project object semantics
spec versioning
knowledge versioning
project-level review boundaries
the distinction between intent, execution, and knowledge

Therefore:

Cloudflare git connection is necessary
but it is not sufficient

The project must remain the center of git meaning.

Cloudflare is a runtime/deploy edge, not the owner of project semantics.

That distinction protects us from designing the whole platform around a deploy product's view of git.

Project-Level Git Registry

At the project level, git should eventually be represented through an explicit registry of bindings.

Conceptually, a project should know:

which repositories it is bound to
which role each repository plays
which repository is primary for execution
which repository is primary for knowledge
which repository or branch is connected to deployment targets

This registry is not yet fully implemented, but it is the correct model direction.

The reason to define it now is architectural sequencing. If we wait until implementation pressure is high, git bindings will arrive as ad hoc fields rather than a coherent project layer.

Canonical Git Domains

Project should be able to bind to three versioned domains.

1. Spec Domain

This covers the definition of the project itself.

Examples:

summary / intent
outcomes
workstream structure
acceptance logic
planning metadata

Question answered:

what are we trying to do

This domain exists because project intent also changes over time and needs reviewable history.

2. Execution Domain

This covers the implementation surface agents actually modify.

Examples:

branches
commits
pull requests
review state
merge state
worktrees

Question answered:

what is actually being changed

This is the most familiar git domain, but it is not the only one that matters.

3. Knowledge Domain

This covers supporting knowledge and artifacts.

Examples:

docs
linked files
assets
decision context

Question answered:

what supporting context exists around the project

This domain is what prevents documentation and execution context from being treated as disposable side material.

Git Spine Concepts

At the project level, git should eventually be represented through concepts such as:

repository bindings
domain type per repository
worktree entry / exit
branch state
commit progression
review state
merge / promotion state
deploy target binding

Deploy Binding To Cloudflare

Cloudflare belongs to the runtime/deploy layer.

Its role in the git model is:

attach runtime surfaces to versioned source
define which branches or revisions flow to which environments
make preview and production progression explicit

This means Cloudflare should be modeled as consuming git state, not defining project git semantics.

That one sentence is the architectural safeguard here.

The correct relationship is:

Project -> Git domains -> provider surfaces -> Cloudflare deploy binding

Not:

Cloudflare -> defines git architecture for the project

Git Events As Activity Evidence

Git is not only a storage boundary. It is also an evidence source.

Project activity should eventually be able to absorb git-derived events such as:

branch created
worktree entered
commit pushed
review requested
review approved
PR merged
deploy triggered
deploy promoted

This is how git stops being an invisible implementation detail and becomes part of the project evidence trail.

It also explains why activity and git architecture cannot be designed independently.

Deliberate Position

The exact number of repositories may vary.

What matters is not repo count by itself.

What matters is that the architecture explicitly separates:

intent
execution
knowledge

Boundary

This page does not define:

the root object semantics of project
runtime permission posture
current UI implementation state

Those belong to:

Reading Relationship

Use this page when the main question is:

how does project change become versioned
where does review happen
how should spec, execution, and knowledge stay separated

Then return to:

execution synthesis: PROJECT_EXECUTION_ARCHITECTURE.md
UI alignment: PROJECT_UI_MAPPING.md

Return to the board home for block/topic position:

PROJECT_CORE_STRUCTURE.md

and treats each as versioned.

Relationship To The Rest Of The Architecture

This document defines the git model conceptually.