> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```yaml theme={null}
# ❌ 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```gitignore theme={null}
.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:

```bash theme={null}
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