Git Integration

All git operations of a run go through <archeflow-root>/lib/archeflow-git.sh. The script never prompts without a terminal (destructive operations need --yes), never force-pushes, and never rewrites the base branch's history.

Branches

<base> (the branch the run started from, e.g. main or master)
└── archeflow/<run_id>                 run branch: created by init, merged by merge
    └── archeflow/<run_id>-maker       Maker branch, in .archeflow/worktrees/<run_id>/
                                        (created by worktree, merged back and removed by integrate)

Commands (in the order a run uses them)

The merge commit subject is archeflow: merge run <run_id> (a neutral type: the run may be a fix, a feature or a refactor). archeflow-rollback.sh reverts only a HEAD commit with exactly that subject, or the subject older versions wrote, feat: archeflow run <run_id> complete.

Configuration (.archeflow/config.yaml)

git:
  enabled: true              # false: no branch, no worktree; the Maker edits the working tree
  branch_prefix: "archeflow/"   # letters, digits, . _ / - ; must not start with + or -
  merge_strategy: no-ff      # no-ff (default, revertable merge commit) | squash | rebase
  auto_merge: false          # true: merge without asking once all reviewers approve
  commit_style: conventional # conventional | simple
  auto_push: false           # push the run branch (explicit refspec, never forced)
  signing_key: null          # SSH key for signed commits
test_command: "npm test"     # top level; run after the merge by archeflow-rollback.sh

Keys are read from the git: block; a top-level key of the same name is accepted as a fallback. enabled and auto_merge are read by the agent following archeflow:run; the others by the script.

Merging into the base branch

The run merges only after every reviewer approved, and only with the user's yes unless git.auto_merge: true. The reviewers are language models reviewing code another model wrote; the confirmation keeps a person in the loop before anything reaches the base branch. After the merge, test_command (if set) runs through archeflow-rollback.sh <run_id>: exit 0 pass, exit 1 failed and the merge commit was reverted, exit 3 failed and nothing was reverted (HEAD was not this run's merge commit), exit 2 no test command.

Run state and artifacts

.archeflow/artifacts/, .archeflow/events/, .archeflow/runs/ and .archeflow/worktrees/ are run state, not source. A run commits nothing under .archeflow/, so a merge brings only the Maker's changes into the base branch, and the .archeflow/.gitignore written by /archeflow:init keeps run state out of your own commits. The audit trail is the event log (.archeflow/events/<run_id>.jsonl), not git history.

Safety rules

• Never force-push; never rewrite the base branch.
• A failed run keeps its branch for inspection.
• Merge conflicts are reported, never force-resolved.
• The Maker works only in its worktree; the orchestrator's checkout stays on the run branch.