---
name: git-integration
description: |
  Git-per-phase commit strategy for ArcheFlow runs. Creates a branch per run, commits after
  every phase transition and agent completion, and merges (squash or no-ff) on success.
  Enables rollback to any phase boundary and full audit trail via git history.
  <example>Automatically loaded by archeflow:run when git.enabled is true</example>
  <example>User: "archeflow rollback --to plan"</example>
---

# Git Integration -- Per-Phase Commit Strategy

Every run creates branch `archeflow/<run_id>`. Each phase transition and agent completion produces a commit. On success, merge back. On failure, branch stays for inspection.

## Branch Strategy

```
main
+-- archeflow/<run_id>
    +-- archeflow(plan): explorer research
    +-- archeflow(plan): creator outline
    +-- archeflow(plan->do): phase transition
    +-- archeflow(do): maker draft
    +-- archeflow(check): guardian review
    +-- archeflow(act): cycle 1 complete
    +-- archeflow(run): complete
```

## Commit Points

| Trigger | Message format |
|---------|----------------|
| `agent.complete` | `archeflow(<phase>): <archetype> <summary>` |
| `phase.transition` | `archeflow(<from>-><to>): phase transition` |
| `fix.applied` | `archeflow(fix): <source> -- <finding>` |
| `cycle.boundary` | `archeflow(act): cycle <N> <status>` |
| `run.complete` | `archeflow(run): complete -- <summary>` |

## Commit Protocol

- Stage only relevant files: `.archeflow/artifacts/<run_id>/`, event log, project files from maker
- Never `git add -A`
- Exclude: `progress.md`, `explorer-cache/`, `session-log.md`
- Use conventional commit format
- Signing opt-in via `git.signing_key` config

## All operations go through `./lib/archeflow-git.sh`:

| Run event | Command |
|-----------|---------|
| `run.start` | `init <run_id>` (create+switch branch) |
| `agent.complete` | `commit <run_id> <phase> "<msg>" [files]` |
| `phase.transition` | `phase-commit <run_id> <phase>` |
| `run.complete` (ok) | `merge <run_id> [--squash|--no-ff]` |
| `run.complete` (fail) | branch preserved |

## Merge

1. Verify all changes committed
2. Switch to base branch
3. Merge with configured strategy (squash default)
4. Branch NOT auto-deleted (user may inspect)

## Rollback

`./lib/archeflow-git.sh rollback <run_id> --to <target>`

Targets: `plan`, `do`, `check`, `act`, `cycle-N`. Only works on `archeflow/<run_id>` branch. Resets to last commit for target phase and trims event JSONL.

## Post-Merge Validation

After merge, runs project test suite (from `test_command` in config) with 5-min timeout. If tests fail: `git revert --no-edit HEAD`.

## Configuration

```yaml
git:
  enabled: true
  branch_prefix: "archeflow/"
  merge_strategy: squash   # squash | no-ff | rebase
  auto_push: false
  signing_key: null
```

## Safety Rules

- Never force-push
- Never modify main history
- Branch stays intact on failure
- Clean merge or abort (no force-resolve on conflicts)
- Worktree-compatible (Maker's worktree branch is sub-branch of run branch)