@namastexlabs/speak/.genie/code/agents/git/commit-advisory.md

Open source voice dictation for everyone

**Last Updated:** !`date -u +"%Y-%m-%d %H:%M:%S UTC"`

---
name: git/commit-advisory
genie:
  executor: claude
  background: false
---

# Git Commit Advisory Workflow

**Purpose:** Pre-push validation that every commit is traced to work items (wishes/GitHub issues) and aligned with Genie framework

**Input:** Git commits from last push to HEAD
**Output:** Advisory report with errors (blocking) and warnings

---

## Discovery Phase

### Gather Context

1. **Get commits to be pushed:**
   - `git log @{u}..HEAD --format="%H %s"` (if tracking remote)
   - Fallback: `git log -5 --format="%H %s"` (last 5 commits)

2. **Extract wish references:**
   - Search commit messages for patterns: `wish:`, `fixes #`, `closes #`, `.genie/wishes/`
   - Check active wishes in `.genie/wishes/*/` folders
   - Extract wish slugs from file paths

3. **Detect branch:**
   - `git rev-parse --abbrev-ref HEAD` → Get current branch
   - Flag if main/master branch

4. **Check for GitHub issues:**
   - If commit contains `fixes #123` or `closes #456`, extract issue numbers
   - Validate issues exist (use gh cli if available)

5. **Analyze file changes:**
   - `git diff @{u}..HEAD --name-only` (files changed)
   - Compare against wish scope (from wish document)

---

## Implementation Phase

### Validation Rules

**Rule 1: Branch Safety (WARNING)**
```
IF current_branch == "main" OR "master":
  WARN: "Pushing to {branch} directly"
  SUGGEST: "Create feature branch (feat/wish-slug) for tracked work"
  SEVERITY: warning (can override with --force-main)
```

**Rule 2: Commit Traceability (BLOCKING)**
```
FOR each commit:
  IF no wish reference found (wish:, fixes #, closes #):
    ERROR: "Commit '{msg}' not linked to wish or issue"
    ACTION: "Add wish reference or GitHub issue link to commit message"
    SEVERITY: error (blocks push)
```

**Rule 3: Bug Commits Must Have Issues (BLOCKING)**
```
FOR each commit:
  IF commit contains "fix:" OR "bug:":
    REQUIRE GitHub issue number (fixes #NNN)
    IF missing:
      ERROR: "Bug fix commit must reference GitHub issue"
      SEVERITY: error (blocks push)
```

**Rule 4: Wish Alignment (WARNING)**
```
FOR each identified wish:
  GET files touched by wish from .genie/wishes/{slug}/{slug}-wish.md
  GET files changed in commits
  IF file overlap < 30% of wish files:
    WARN: "Commits don't appear to align with wish scope"
    SUGGEST: "Double-check wish is current/active"
    SEVERITY: warning (user can override)
```

**Rule 5: Multiple Wishes (WARNING)**
```
IF commits reference multiple wishes:
  WARN: "Commits reference multiple wishes: {list}"
  SUGGEST: "Keep work focused to single wish per push"
  SEVERITY: warning
```

---

## Verification Phase

### Advisory Output Format

```markdown
# Pre-Push Commit Advisory

**Branch:** {current_branch}
**Commits:** {count} new commits
**Wishes Referenced:** {list or "none"}
**GitHub Issues:** {list or "none"}

## Validation Results

### ✅ Passed
- Commits traced to wishes/issues
- Files aligned with wish scope
- (list any passes)

### ⚠️ Warnings ({count})
1. {warning}: {details}
2. {warning}: {details}

### ❌ Blocking Issues ({count})
1. {error}: {details}
   Fix: {suggested action}
2. {error}: {details}

## Next Steps

IF blocking issues:
  → Fix commit messages or create wish/issue
  → Retry `git push`

IF only warnings:
  → Option A: Fix issues, retry push
  → Option B: Override warning with `git push --force-advisory`
  → Option C: Cancel push, revisit later

---

**Generated by:** Genie commit-advisory workflow
**Timestamp:** {ISO timestamp}
```

---

## Reference: Wish Document Format

Workflows read wish docs to validate file alignment:

```markdown
# Wish Document (.genie/wishes/{slug}/{slug}-wish.md)

## Scope
- Files affected: [list]
- Implementation groups: [groups A/B/C]
```

Extract from sections: `## Scope`, `Files:`, `Modified:`, `Touched:`

---

## CLI Integration

Called by pre-push hook:
```bash
node .genie/cli/dist/genie-cli.js run "agents/git/commit-advisory"
```

Exit codes:
- `0` = Pass (all validations OK)
- `1` = Warnings only (user can override)
- `2` = Blocking errors (push blocked)

---

## Configuration Overrides

Users can override with environment variables:

```bash
# Allow main branch push (advanced users only)
GENIE_ALLOW_MAIN_PUSH=1 git push

# Skip wish traceability check for small commits
GENIE_SKIP_WISH_CHECK=1 git push

# Force push despite warnings
git push --force-advisory
```

---

## Implementation Notes

**Why Haiku:**
- Fast analysis (commit messages, file lists, wish documents)
- No complex reasoning needed (pattern matching + validation)
- Cost efficient for frequent pre-push checks
- Sufficient for traceability validation

**Error Handling:**
- If wish file missing: WARN instead of ERROR
- If gh cli unavailable: Skip issue verification (warn)
- If git log fails: Let error bubble (pre-push already blocked)

**Performance:**
- Analyze last N commits (default: 10)
- Cache wish list on first run
- Total runtime: 2-5 seconds per push