How Commit Validation in `swarm_handoff.sh` Ensures Unique Commit Abbreviations

The swarm_handoff.bb script validates commit abbreviations by generating a 10-character short SHA and verifying it resolves to exactly one unambiguous commit using Git's native rev-parse and merge-base --is-ancestor commands.

The swarmhandoff.sh wrapper script in the unclebob/swarm-forge repository delegates to a Babashka script that enforces strict commit abbreviation uniqueness before accepting any hand-off draft. This prevents ambiguous short SHAs from corrupting Swarm Forge's task routing workflow.

Generating a Deterministic Short SHA

The validation pipeline begins in swarmforge/scripts/swarm_handoff.bb with the worktree-head function. This generates a consistent 10-character abbreviation of the current HEAD commit:

(defn worktree-head []
  (let [result (command (git-cwd) "git" "rev-parse" "--short=10" "HEAD")]
    (when-not (zero? (:exit result))
      (exit! 1 "Cannot read HEAD commit."))
    (str/trim (:out result))))

This 10-character length provides sufficient entropy to avoid collisions in typical repository sizes while remaining human-readable in hand-off drafts.

Verifying Unambiguous Commit Resolution

The core uniqueness check occurs in the commit-on-sender-branch? function (lines 103-105). Rather than parsing output, the script leverages Git's exit codes to detect ambiguity:

(defn commit-on-sender-branch? [sha]
  (zero? (:exit (command (git-cwd) "git" "merge-base" "--is-ancestor" sha "HEAD"))))

Git's merge-base --is-ancestor command returns non-zero status if:

• The abbreviation matches multiple commits
• The commit does not exist in the repository
• The abbreviation is malformed

When any of these conditions occur, swarm_handoff.bb aborts via exit! with a non-zero status, rejecting the hand-off draft before it enters the queue.

Validating Descendant Relationships

For hand-offs that specify a task_base_commit, the script performs an additional uniqueness check at lines 107-109. It verifies the new commit descends from the task's base using the same merge-base --is-ancestor pattern:

(defn commit-descends-from? [sha base]
  (zero? (:exit (command (git-cwd) "git" "merge-base" "--is-ancestor" base sha))))

This double verification guarantees that:

1. The abbreviation points to exactly one commit object
2. That commit occupies the correct position in the branch history

Failure Modes and Script Behavior

The validation strictness produces clear error conditions:

# Example: Successful validation

$ ./swarmhandoff.sh draft.handoff

# Hand-off accepted – the abbreviation resolves to a single commit.

# Example: Failure due to ambiguous abbreviation

$ ./swarmhandoff.sh draft.handoff
CURRENT COMPLETION FAILED after handoff queued.

# The script exited because git rev-parse --verify <abbr> was ambiguous.

Source Files for Commit Validation

File	Purpose
swarmforge/scripts/swarm_handoff.bb	Main validation logic (worktree-head, commit-on-sender-branch?, commit-descends-from? functions)
swarmforge/scripts/swarmhandoff.sh	Thin shell wrapper that invokes swarm_handoff.bb
swarmforge/scripts/commit-msg-hook.sh	Git hook applying identical rules during local commits

Summary

• 10-character abbreviations are generated via git rev-parse --short=10 for optimal collision resistance
• git merge-base --is-ancestor provides exit-code-based verification of unique, unambiguous commit resolution
• Descendant validation ensures commit abbreviations reference commits in the correct historical position
• Non-zero exit propagation immediately rejects invalid hand-offs before queue entry

Frequently Asked Questions

What happens if two commits share the same 10-character abbreviation?

The commit-on-sender-branch? function detects this via Git's merge-base --is-ancestor returning non-zero or failing outright. According to the unclebob/swarm-forge source code, the script calls exit! with status 1, rejecting the hand-off draft with a failure message.

Why use merge-base --is-ancestor instead of rev-parse --verify?

While rev-parse --verify checks for valid object names, merge-base --is-ancestor simultaneously validates both that the abbreviation resolves unambiguously and that the commit exists on the current branch lineage. This single-command efficiency matches the script's minimal dependency philosophy.

Does the validation work with shallow clones or partial checkouts?

Yes. The command helper in swarm_handoff.bb executes Git operations against the actual working directory via (git-cwd). As implemented in unclebob/swarm-forge, the validation respects whatever commit objects Git can resolve in the current environment, though very shallow clones increase collision probability for any fixed abbreviation length.

Where is this validation reused outside hand-off scripts?

The swarmforge/scripts/commit-msg-hook.sh Git hook enforces identical commit-abbreviation rules during local development, ensuring consistency between individual commits and Swarm Forge hand-offs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}