Git Structure Rules

Purpose: Standard git hygiene for the multi-tenant tree. Read BEFORE git init, gh repo create, or any commit decision.

1. Repo placement matrix

Repo type	Canonical home	GitHub org/owner	Visibility default
ALAI product (Bilko, Drop, Tok)	`~/business/ALAI-Holding-AS/products/<product>/`	`johnatbasicas/<product>`	private until launch
ALAI internal CLI / SDK / library	`~/projects/<repo-name>/`	`johnatbasicas/<repo>`	public if open-source
ALAI infra workspace	`~/aisystem/`	n/a	n/a
ALAI Tech DOO (RS subsidiary)	`~/business/ALAI-Tech-DOO/`	`alai-tech-doo/<repo>`	private
Client-owned repo	`~/clients-external/<client>/`	client's GitHub org	client's choice
Personal scholarly project	`~/personal/scholarly/<topic>/`	`johnatbasicas/<topic>`	public (transparency)
System orchestration	`~/system/`	`johnatbasicas/alai-system`	private

2. Required files per repo type

File	When required
`README.md`	Always
`CLAUDE.md`	Every repo where agents will be dispatched
`BUILD-BLUEPRINT.md`	Repos that build/deploy (per ZAKON PI2)
`DEPLOY-MAP.md`	Repos with live deploys (CF Pages, Cloud Run, App Runner, etc.)
`.gitignore`	Always — see Section 4
`.github/workflows/deploy*.yml`	Repos with CI/CD
`LICENSE`	Public repos (default MIT for ALAI products)

3. Commit conventions — Conventional Commits (mandatory)

<type>(<scope>): <subject> (MC #<id>)

<body — what changed and why>

Co-Authored-By: <persona-name> <[email protected]>

4. .gitignore standards

Universal (every repo)

# OS
.DS_Store
Thumbs.db

# Editor / IDE
.vscode/
.idea/
*.swp
.aider*
.claude-scratch/

# Secrets — NEVER COMMIT
.env
.env.*
!.env.example
*.pem
*.key
id_rsa*
*.p12
.bw-session

# Logs
*.log
logs/

# Build outputs
dist/
build/
out/
target/
.next/
.nuxt/
.output/
.turbo/

Node-specific

node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

Terraform / IaC (CRITICAL after Parisa finding)

*.tfstate
*.tfstate.*
*.tfplan
.terraform/
.terraform.lock.hcl
crash.log

5. Anti-patterns — explicitly forbidden

Anti-pattern	Why it's bad	Correct alternative
`git add .` without reviewing diff	Commits unwanted files (.env, tfstate, secrets, IDE configs)	`git add -p` or explicit paths
Committing `.env` "for now"	Secrets in git history forever	Bitwarden / .env.example pattern
Force-push to shared/master	Destroys teammates' work	PRs only; force-push only on private feat branches
Cross-tenant repos	Tenant contamination, IP confusion	Split into 2 repos, separate orgs ideally
Tags pushed before work is verified live	Tag points to broken state	Tag AFTER `curl 200` + Playwright pass

6. References

ADR-023: ~/system/architecture/decisions/ADR-023-anvil-tenant-restructure-2026-05-07.md
Tree blueprint: ~/system/specs/anvil-tree-blueprint-2026-05-07.md
Canonical registry: ~/system/specs/canonical-registry.md
ZAKON PI2 (deploy verification): ~/system/rules/zakon-pi2-deploy-verification.md
Conventional Commits spec: https://www.conventionalcommits.org/en/v1.0.0/