Git Workflow

Branch strategy, deployment triggers, and protected branch rules for the ThreatWeaver repository.

Branch Structure

Branch	Purpose	Deploys To	Rules
local	All active development	Nothing (local only)	Default working branch
dev	Production deployment trigger	Vercel (frontend) + Render (backend)	Never push without explicit confirmation
main	Backup and release	Nothing	Protected by pre-push hook; never push directly

Branch Rules

local

• All development happens here
• Create feature branches off local if needed, but most work happens directly on local
• Run tests and build checks before merging to dev

dev

• Pushing to dev triggers immediate deployment to production (Render + Vercel)
• Never push without explicit confirmation from the team lead
• Never force-push to dev
• Pre-deploy checklist: build succeeds, tests pass, migrations tested locally

main

• Protected by a pre-push hook that rejects all direct pushes
• Used only for tagged releases and backups
• Merges into main happen only during planned releases

Commit Conventions

All commits must follow Conventional Commits:

type(scope): description [#issue]

Types

Prefix	Usage
feat:	New feature or capability
fix:	Bug fix
docs:	Documentation only
refactor:	Code restructuring (no behavior change)
test:	Adding or modifying tests
perf:	Performance improvement
security:	Security fix or hardening
infra:	Infrastructure or CI/CD changes
chore:	Tooling, deps, or maintenance

Message Rules

• Title: Max 72 characters, imperative mood ("add feature" not "added feature")
• Body: Required for non-trivial commits; explain what, why, and impact
• Issue reference: Include tracker number when fixing a tracked issue: fix(dashboard): resolve risk score [#12]
• One change per commit: Do not mix unrelated changes

Typical Workflow

Day-to-Day Development

# 1. Ensure you're on local branch
git checkout local

# 2. Pull latest changes (check for external agent changes)
git pull origin local

# 3. Make changes, test, commit
npm test
git add -p                    # stage specific changes
git commit -m "fix(appsec): resolve SSRF false positive on /video endpoint"

# 4. Push to local (safe, no deployment)
git push origin local

Deploying to Production

# 1. Verify everything works locally
cd backend && rm -rf dist && npm run build && npm start
cd frontend && npm run build

# 2. Run tests
cd backend && npm test
cd frontend && npm test

# 3. Get explicit confirmation from team lead

# 4. Merge local into dev
git checkout dev
git merge local
git push origin dev          # triggers deployment

# 5. Return to local branch
git checkout local

Pre-Push Hooks

The repository has a pre-push hook that:

• Blocks all pushes to main -- no exceptions, even with --force
• Serves as a safety net against accidental production pushes

Multi-Agent Awareness

This repository is worked on by both human developers and AI agents (Claude Code, Google Antigravity). Before starting work:

# Always check for external changes
git status
git log --oneline -10

Both agents reference the same issue tracker at docs/audits/ISSUE_TRACKER.md.

What NOT to Do

• Never push to main under any circumstances
• Never push to dev without explicit confirmation
• Never force-push to any shared branch
• Never run git reset --hard without understanding consequences
• Never commit secrets, API keys, or credentials
• Never commit files larger than 5MB (CSVs, ZIPs, logs)
• Never skip pre-push hooks with --no-verify