---
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>
  <example>User: "Show me the git history for this run"</example>
---

# Git Integration — Per-Phase Commit Strategy

Every ArcheFlow run creates a dedicated branch. Each phase transition and agent completion produces a commit. At run completion, the branch is merged back to the base branch. On failure, the branch stays intact for inspection or rollback.

## Prerequisites

- `archeflow:orchestration` — workflow rules and safety constraints
- `archeflow:process-log` — event schema (git events are emitted alongside process events)
- `archeflow:artifact-routing` — artifact paths that get committed

## Helper Script

All git operations go through the helper script:

```bash
./lib/archeflow-git.sh <command> <run_id> [args...]
```

See `lib/archeflow-git.sh` for full usage. The skill describes *when* to call the script; the script handles *how*.

---

## Branch Strategy

```
main (or current base branch)
└── archeflow/<run_id>                    # Created at run.start
    ├── commit: "archeflow(plan): explorer research"
    ├── commit: "archeflow(plan): creator outline"
    ├── commit: "archeflow(plan→do): phase transition"
    ├── commit: "archeflow(do): maker draft"
    ├── commit: "archeflow(do→check): phase transition"
    ├── commit: "archeflow(check): guardian review"
    ├── commit: "archeflow(check): sage review"
    ├── commit: "archeflow(check→act): phase transition"
    ├── commit: "archeflow(act): apply 6 fixes"
    ├── commit: "archeflow(act): cycle 1 complete"
    └── commit: "archeflow(run): complete — <summary>"
```

Branch naming: `archeflow/<run_id>` (e.g., `archeflow/2026-04-03-jwt-auth`).

---

## Commit Points

| Trigger | What to commit | Message format |
|---------|---------------|----------------|
| After `agent.complete` | Agent artifacts + any created/modified files | `archeflow(<phase>): <archetype> <summary>` |
| After `phase.transition` | All artifacts from completed phase | `archeflow(<from>→<to>): phase transition` |
| After each `fix.applied` | The fixed file | `archeflow(fix): <source> — <finding summary>` |
| After `cycle.boundary` | Everything staged | `archeflow(act): cycle <N> <status>` |
| After `run.complete` | Final state + process report | `archeflow(run): complete — <summary>` |

---

## Commit Protocol

1. **Stage only relevant files.** Never `git add -A`. Stage:
   - `.archeflow/artifacts/<run_id>/` — artifacts produced by the current agent/phase
   - `.archeflow/events/<run_id>.jsonl` — updated event log
   - Any project files created or modified by the current agent (from `do-maker-files.txt` or explicit file list)
2. **Exclude ephemeral files.** Never commit:
   - `.archeflow/progress.md` (live progress display, ephemeral)
   - `.archeflow/explorer-cache/` (local cache, not run-specific)
   - `.archeflow/session-log.md` (separate concern)
3. **Use conventional commit format:** `archeflow(<scope>): <message>`
4. **Signing:** If `git.signing_key` is configured, pass `-c user.signingkey=<key>` to `git commit`.

### Integration with the Run Skill

The `archeflow:run` skill calls git operations at these points:

```
run.start          → ./lib/archeflow-git.sh init <run_id>
agent.complete     → ./lib/archeflow-git.sh commit <run_id> <phase> "<archetype> <summary>" [files...]
phase.transition   → ./lib/archeflow-git.sh phase-commit <run_id> <phase>
fix.applied        → ./lib/archeflow-git.sh commit <run_id> fix "<source> — <finding>"
cycle.boundary     → ./lib/archeflow-git.sh commit <run_id> act "cycle <N> <status>"
run.complete (ok)  → ./lib/archeflow-git.sh merge <run_id> [--squash|--no-ff]
run.complete (fail) → branch preserved, not merged
```

---

## Run Lifecycle

### 1. Initialization (`run.start`)

```bash
./lib/archeflow-git.sh init <run_id>
```

This will:
1. Verify a clean working tree (or stash uncommitted changes)
2. Create branch `archeflow/<run_id>` from current HEAD
3. Switch to the new branch

### 2. During Execution (phase commits)

After each agent completes or phase transitions, the run skill calls:

```bash
# After an agent completes:
./lib/archeflow-git.sh commit <run_id> plan "explorer research" \
  .archeflow/artifacts/<run_id>/plan-explorer.md

# After a phase transition:
./lib/archeflow-git.sh phase-commit <run_id> plan
```

The `commit` command stages artifact directories and event logs automatically. Additional files can be passed as trailing arguments.

The `phase-commit` command stages all artifacts matching the phase prefix and commits with a transition message.

### 3. Completion (merge)

```bash
# Success — squash merge (default):
./lib/archeflow-git.sh merge <run_id> --squash

# Success — preserve history:
./lib/archeflow-git.sh merge <run_id> --no-ff

# Failure or user abort:
# Do nothing. Branch stays for inspection.
echo "Branch archeflow/<run_id> preserved for inspection."
```

The merge command:
1. Verifies all changes on the branch are committed
2. Switches to the base branch (main or wherever the run started)
3. Merges with the chosen strategy
4. If squash: creates a single commit with `feat: <task summary>`
5. Does NOT delete the branch (user may want to inspect)

### 4. Cleanup (optional, after inspection)

```bash
./lib/archeflow-git.sh cleanup <run_id>
```

Deletes the branch after the user has confirmed the merge is correct.

---

## Rollback

Roll back to the end of any completed phase:

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

This will:
1. Find the last commit for the target phase by searching commit messages
2. Show the user what commits will be lost (everything after the target)
3. Perform `git reset --hard <commit>` on the branch
4. Trim the events JSONL to remove events that occurred after the rollback point

**Supported rollback targets:** `plan`, `do`, `check`, `act`, or any cycle number (`cycle-1`, `cycle-2`).

**Safety:** Rollback only works on the run's branch, never on main. The script verifies you are on `archeflow/<run_id>` before proceeding.

---

## Status

View the git state of a run:

```bash
./lib/archeflow-git.sh status <run_id>
```

Output:
```
Branch: archeflow/2026-04-03-jwt-auth
Base: main (3 commits ahead)

Commits:
  abc1234 archeflow(plan): explorer research
  def5678 archeflow(plan): creator outline
  ghi9012 archeflow(plan→do): phase transition
  jkl3456 archeflow(do): maker implementation

Current phase: do
Files changed (total): 8
Uncommitted changes: none
```

---

## Configuration

In `.archeflow/config.yaml` or a team preset:

```yaml
git:
  enabled: true                # Default: true. Set false to disable all git operations.
  branch_prefix: "archeflow/"  # Default. The run_id is appended.
  commit_style: conventional   # conventional (archeflow(<scope>): msg) | simple (<phase>: msg)
  merge_strategy: squash       # squash | no-ff | rebase
  auto_push: false             # Push branch to remote after each commit
  signing_key: null            # SSH key path for signed commits (e.g., ~/.ssh/id_ed25519.pub)
```

The helper script reads this config if it exists. All values have sensible defaults.

---

## Post-Merge Rollback

After merging, the run skill validates the merge by running the project's test suite. If tests fail, the merge is automatically reverted.

### Script

```bash
./lib/archeflow-rollback.sh <run_id> [--test-cmd <cmd>]
```

**Behavior:**
1. Reads `test_command` from `.archeflow/config.yaml` (or uses `--test-cmd` override)
2. Runs the test suite with a 5-minute timeout
3. If tests pass: exits 0 (merge is good)
4. If tests fail: runs `git revert --no-edit HEAD`, emits a `decision` event, exits 1
5. Verifies HEAD is an ArcheFlow merge commit before reverting (warning if not, proceeds anyway)

**Integration with run skill:** Called in section 4c (All Approved) after `archeflow-git.sh merge`. If it returns non-zero, the orchestrator cycles back with "integration test failure" feedback or reports to the user if max cycles are reached.

**Configuration:** Set `test_command` in `.archeflow/config.yaml`:
```yaml
test_command: "npm test"       # or "pytest", "cargo test", etc.
```

---

## Safety Rules

These rules are inherited from `archeflow:orchestration` and reinforced here:

1. **Never force-push.** No `--force`, no `--force-with-lease`. If a push fails, diagnose and fix.
2. **Never modify main history.** Merges are forward-only. No rebasing main.
3. **Branch stays intact on failure.** If a run fails or is aborted, the branch is preserved for inspection. Never auto-delete failed branches.
4. **All commits are individually revertable.** Each commit represents a discrete unit of work.
5. **Worktree mode compatibility.** If the Maker runs in a worktree, git-integration commits go to the worktree's branch. The merge happens at the run level, not the worktree level. The Maker's worktree branch is a sub-branch of `archeflow/<run_id>`.
6. **Clean merge or abort.** If a merge produces conflicts, do not force-resolve. Report the conflict, leave the branch intact, and let the user decide.
7. **No signing by default.** Signing is opt-in via config. If configured, all commits on the branch are signed.

---

## Design Principles

1. **Git is the audit trail.** Every phase transition is a commit. `git log` tells the full story of a run.
2. **Rollback is cheap.** Reset to any phase boundary, re-run from there. No need to start over.
3. **Merge strategy is a project decision.** Squash for clean history, no-ff for detailed history. Both are valid.
4. **Events + git = full observability.** Process events capture *what happened* (decisions, verdicts, timing). Git captures *what changed* (files, diffs). Together they provide complete run archaeology.
5. **Fail-safe by default.** Every safety rule defaults to the conservative option. The user must explicitly opt in to destructive operations.