From 960aba5faa2ac66e96dcb6a13367dbef58c0c150 Mon Sep 17 00:00:00 2001
From: Christian Nennemann <christian@nennemann.de>
Date: Sat, 4 Apr 2026 07:33:08 +0200
Subject: [PATCH] feat: clarify worktree merge flow with explicit git commands
 in run skill

---
 skills/run/SKILL.md | 57 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 51 insertions(+), 6 deletions(-)

diff --git a/skills/run/SKILL.md b/skills/run/SKILL.md
index ec51001..651c7dd 100644
--- a/skills/run/SKILL.md
+++ b/skills/run/SKILL.md
@@ -301,12 +301,57 @@ If all reviewers approved (and completion criteria met, if defined):
      '{"cycle":<N>,"max_cycles":<M>,"exit_condition":"all_approved","met":true,"next_action":"complete"}' "$SEQ_CHECK_TO_ACT"
    ```
 
-2. Run pre-merge hooks (check `.archeflow/hooks.yaml`)
-3. Merge Maker's worktree branch: `git merge --no-ff <branch>`
-4. Run post-merge hooks + test suite
-   - Tests pass → continue
-   - Tests fail → auto-revert, cycle back with "integration test failure" feedback
-5. Clean up worktree
+2. **Pre-merge hook check:**
+   ```bash
+   # Read hooks config if it exists
+   if [[ -f ".archeflow/hooks.yaml" ]]; then
+     PRE_MERGE_HOOKS=$(grep -A5 "pre-merge:" .archeflow/hooks.yaml || true)
+     if [[ -n "$PRE_MERGE_HOOKS" ]]; then
+       echo "Running pre-merge hooks..."
+       # Execute hooks; abort merge if fail_action: abort
+       # Hook execution is project-specific — see .archeflow/hooks.yaml
+     fi
+   fi
+   ```
+
+3. **Merge the Maker's worktree branch:**
+   ```bash
+   ./lib/archeflow-git.sh merge "$RUN_ID" --no-ff
+   ```
+
+4. **Post-merge test validation:**
+   ```bash
+   # Read test_command from config
+   TEST_CMD=$(grep -E "^test_command:" .archeflow/config.yaml | sed 's/^test_command:\s*//' | tr -d '"' || true)
+
+   if [[ -n "$TEST_CMD" ]]; then
+     echo "Running post-merge tests: $TEST_CMD"
+     if ! bash -c "$TEST_CMD"; then
+       echo "Post-merge tests FAILED — reverting merge..."
+       git revert --no-edit HEAD
+
+       # Emit decision event for the revert
+       ./lib/archeflow-event.sh "$RUN_ID" decision act "" \
+         '{"what":"post_merge_test","chosen":"revert","rationale":"test suite failed after merge"}' "$SEQ_CHECK_TO_ACT"
+
+       # If cycles remain, cycle back with integration test failure feedback
+       if [[ "$CYCLE" -lt "$MAX_CYCLES" ]]; then
+         echo "Cycling back with integration test failure feedback..."
+         # Build act-feedback.md with "integration test failure on main" as top finding
+         # Continue to step 4d (Issues Found)
+       else
+         echo "Max cycles reached. Reporting failure to user."
+         # Continue to step 4e (Max Cycles Reached)
+       fi
+     fi
+   fi
+   ```
+
+5. **Clean up worktree:**
+   ```bash
+   ./lib/archeflow-git.sh cleanup "$RUN_ID"
+   ```
+
 6. Proceed to Completion (step 5)
 
 #### 4d. Branch: Issues Found (cycles remaining)