269 lines
10 KiB
Markdown
269 lines
10 KiB
Markdown
---
|
|
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.
|