Git Workflow

Multi-layer validation system for ensuring code quality before merge

Overview

Synkra AIOX implements a Defense in Depth validation strategy with three progressive layers that catch issues early and ensure code quality before merge.

Why Three Layers?

1. Fast feedback - Catch issues immediately during development
2. Local validation - No cloud dependency for basic checks
3. Authoritative validation - Final gate before merge
4. Story consistency - Ensure development aligns with stories

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Developer Workflow                       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Pre-commit Hook (Local - <5s)                     │
│ ✓ ESLint (code quality)                                     │
│ ✓ TypeScript (type checking)                                │
│ ✓ Cache enabled                                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: Pre-push Hook (Local - <2s)                       │
│ ✓ Story checkbox validation                                 │
│ ✓ Status consistency                                         │
│ ✓ Required sections                                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 3: GitHub Actions CI (Cloud - 2-5min)                │
│ ✓ All lint/type checks                                      │
│ ✓ Full test suite                                           │
│ ✓ Code coverage (≥80%)                                      │
│ ✓ Story validation                                          │
│ ✓ Branch protection                                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                       ┌──────────────┐
                       │ Merge Ready  │
                       └──────────────┘

Layer 1: Pre-commit (Local - Fast)

Performance Target: Less than 5 seconds
Trigger: git commit
Location: .husky/pre-commit

What It Validates

• ESLint code quality
• TypeScript type checking
• Syntax errors
• Import issues

How It Works

# Triggered automatically on commit
git add .
git commit -m "feat: add feature"

# Runs:
# 1. ESLint with caching (.eslintcache)
# 2. TypeScript incremental compilation (.tsbuildinfo)

Benefits

• ⚡ Fast feedback (less than 5s)
• 💾 Cached for speed
• 🔒 Prevents broken code commits
• 🚫 No invalid syntax in history

Manual Validation

# Run lint check
npm run lint

# Run type check
npm run typecheck

# Auto-fix lint issues
npm run lint -- --fix

# Skip hook (NOT recommended)
git commit --no-verify

Layer 2: Pre-push (Local - Story Validation)

Performance Target: Less than 2 seconds
Trigger: git push
Location: .husky/pre-push

What It Validates

• Story checkbox completion vs status
• Required story sections present
• Status consistency
• Dev agent records

Validation Rules

1. Status Consistency

# ❌ Invalid: completed but tasks incomplete
status: "completed"
tasks:
  - "[x] Task 1"
  - "[ ] Task 2"  # Error!

# ✅ Valid: all tasks completed
status: "completed"
tasks:
  - "[x] Task 1"
  - "[x] Task 2"

2. Required Sections

• id
• title
• description
• acceptance_criteria
• status

3. Status Flow

ready → in progress → Ready for Review → completed

Manual Validation

# Validate all stories
node .aiox-core/utils/aiox-validator.js pre-push
node .aiox-core/utils/aiox-validator.js stories

# Validate single story
node .aiox-core/utils/aiox-validator.js story docs/stories/1.1-story.yaml

# Skip hook (NOT recommended)
git push --no-verify

Example Output

══════════════════════════════════════════════════════════════
  Story Validation: 2.2-git-workflow-implementation.yaml
══════════════════════════════════════════════════════════════

Story: 2.2 - Git Workflow with Multi-Layer Validation
Status: in progress

Progress: 12/15 tasks (80.0%)

✓ Story validation passed with warnings

Warning:
  • Consider updating status to 'Ready for Review'

Layer 3: CI/CD Pipeline

Performance: 2-5 minutes
Trigger: Push to any branch, PR creation
Platform: GitHub Actions
Location: .github/workflows/ci.yml

Jobs

1. ESLint (lint job)

   • Runs on clean environment
   • No cache dependency

2. TypeScript (typecheck job)

   • Full type checking
   • No incremental compilation

3. Tests (test job)

   • Full test suite
   • Coverage reporting
   • 80% threshold enforced

4. Story Validation (story-validation job)

   • All stories validated
   • Status consistency checked

5. Validation Summary (validation-summary job)

   • Aggregates all results
   • Blocks merge if any fail

CI Triggers

Push Events:

• master branch
• develop branch
• feature/** branches
• bugfix/** branches

Pull Request Events:

• Against master
• Against develop

Viewing CI Results

# View PR checks
gh pr checks

# View workflow runs
gh run list

# View specific run
gh run view <run-id>

# Re-run failed jobs
gh run rerun <run-id>

Daily Workflow

Starting a New Feature

# 1. Update master
git checkout master
git pull origin master

# 2. Create feature branch
git checkout -b feature/my-feature

# 3. Make changes
# ... edit files ...

# 4. Commit (triggers pre-commit)
git add .
git commit -m "feat: add my feature [Story X.X]"

# 5. Push (triggers pre-push)
git push origin feature/my-feature

# 6. Create PR
gh pr create --title "feat: Add my feature" --body "Description"

Updating a Story

# 1. Open story file
code docs/stories/X.X-story.yaml

# 2. Mark tasks complete
# Change: - "[ ] Task"
# To:     - "[x] Task"

# 3. Update status if needed
# Change: status: "in progress"
# To:     status: "Ready for Review"

# 4. Commit story updates
git add docs/stories/X.X-story.yaml
git commit -m "docs: update story X.X progress"

# 5. Push (validates story)
git push

Fixing Validation Failures

ESLint Errors:

# Auto-fix issues
npm run lint -- --fix

# Check remaining issues
npm run lint

# Commit fixes
git add .
git commit -m "style: fix lint issues"

TypeScript Errors:

# See all errors
npm run typecheck

# Fix errors in code
# ... edit files ...

# Verify fix
npm run typecheck

# Commit fixes
git add .
git commit -m "fix: resolve type errors"

Story Validation Errors:

# Check stories
node .aiox-core/utils/aiox-validator.js stories

# Fix story file
code docs/stories/X.X-story.yaml

# Verify fix
node .aiox-core/utils/aiox-validator.js story docs/stories/X.X-story.yaml

# Commit fix
git add docs/stories/
git commit -m "docs: fix story validation"

Test Failures:

# Run tests
npm test

# Run specific test
npm test -- path/to/test.js

# Run with coverage
npm run test:coverage

# Commit fixes
git add .
git commit -m "test: fix failing tests"

Merging a Pull Request

# 1. Ensure CI passes
gh pr checks

# 2. Get approval (wait for team review)

# 3. Merge (squash)
gh pr merge --squash --delete-branch

# 4. Update local master
git checkout master
git pull origin master

Troubleshooting

Hook Not Running

Symptoms: Commit succeeds without validation

Solutions:

# 1. Check Husky installation
npm run prepare

# 2. Verify hook files exist
ls -la .husky/pre-commit
ls -la .husky/pre-push

# 3. Check file permissions (Unix)
chmod +x .husky/pre-commit
chmod +x .husky/pre-push

Slow Pre-commit Hook

Symptoms: Pre-commit takes >10 seconds

Solutions:

# 1. Clear caches
rm .eslintcache .tsbuildinfo
git commit  # Rebuilds cache

# 2. Check file changes
git status
# Commit fewer files at once

# 3. Update dependencies
npm update

CI Fails but Local Passes

Symptoms: CI fails but all local validations pass

Solutions:

# 1. Clear local caches
rm -rf node_modules .eslintcache .tsbuildinfo coverage/
npm ci
npm test

# 2. Use same Node version as CI (18)
nvm use 18
npm test

# 3. Check for uncommitted changes
git status

Performance Tips

Cache Management

Keep caches:

• .eslintcache - ESLint results
• .tsbuildinfo - TypeScript build info
• coverage/ - Test coverage data

Commit to .gitignore:

.eslintcache
.tsbuildinfo
coverage/

Incremental Development

1. Small commits - Fewer files = faster validation
2. Test during development - Don’t wait for pre-commit
3. Fix issues immediately - Don’t accumulate problems

Best Practices

Git Commit Messages

Follow conventional commits:

feat: add new feature [Story X.X]
fix: resolve bug in component [Story X.X]
docs: update story X.X progress
style: fix lint issues
refactor: improve code structure
test: add unit tests for feature

Branch Strategy

• master - Production-ready code
• develop - Integration branch
• feature/* - New features
• bugfix/* - Bug fixes
• hotfix/* - Emergency fixes

Story Integration

• Always reference story ID in commits
• Update story checkboxes as you work
• Change status to “Ready for Review” when done
• Document blockers in story notes