pickman: Use named tuples for better code clarity

Create an AgentCommit namedtuple for passing data to the agent to save
confusing about ordering.

Document CommitInfo while we are here.

Co-developed-by: Claude <noreply@anthropic.com>
Signed-off-by: Simon Glass <simon.glass@canonical.com>

tools/pickman/agent.py

@@ -49,7 +49,8 @@ async def run(commits, source, branch_name, repo_path=None):
     """Run the Claude agent to cherry-pick commits
 
     Args:
-        commits (list): list of (hash, short_hash, subject) tuples
+        commits (list): list of AgentCommit namedtuples with fields:
+                       hash, chash, subject
         source (str): source branch name
         branch_name (str): name for the new branch to create
         repo_path (str): path to repository (defaults to current directory)
@@ -70,12 +71,12 @@ async def run(commits, source, branch_name, repo_path=None):
 
     # Build commit list for the prompt
     commit_list = '\n'.join(
-        f'  - {short_hash}: {subject}'
-        for _, short_hash, subject in commits
+        f'  - {commit.chash}: {commit.subject}'
+        for commit in commits
     )
 
     # Get full hash of last commit for signal file
-    last_commit_hash = commits[-1][0]
+    last_commit_hash = commits[-1].hash
 
     prompt = f"""Cherry-pick the following commits from {source} branch:
 
@@ -204,7 +205,8 @@ def cherry_pick_commits(commits, source, branch_name, repo_path=None):
     """Synchronous wrapper for running the cherry-pick agent
 
     Args:
-        commits (list): list of (hash, short_hash, subject) tuples
+        commits (list): list of AgentCommit namedtuples with fields:
+                       hash, chash, subject
         source (str): source branch name
         branch_name (str): name for the new branch to create
         repo_path (str): path to repository (defaults to current directory)

tools/pickman/control.py

@@ -72,9 +72,19 @@ CheckResult = namedtuple('CheckResult', [
 ])
 
 # Named tuple for commit with author
+# hash: Full SHA-1 commit hash (40 characters)
+# chash: Abbreviated commit hash (typically 7-8 characters) 
+# subject: First line of commit message (commit subject)
+# author: Commit author name and email in format "Name <email>"
 CommitInfo = namedtuple('CommitInfo',
                         ['hash', 'chash', 'subject', 'author'])
 
+# Named tuple for simplified commit data passed to agent
+# hash: Full SHA-1 commit hash (40 characters)
+# chash: Abbreviated commit hash (typically 7-8 characters)
+# subject: First line of commit message (commit subject)
+AgentCommit = namedtuple('AgentCommit', ['hash', 'chash', 'subject'])
+
 # Named tuple for prepare_apply result
 ApplyInfo = namedtuple('ApplyInfo',
                        ['commits', 'branch_name', 'original_branch',
@@ -1213,9 +1223,9 @@ def execute_apply(dbs, source, commits, branch_name, args):  # pylint: disable=t
                        status='pending')
     dbs.commit()
 
-    # Convert CommitInfo to tuple format expected by agent
-    commit_tuples = [(c.hash, c.chash, c.subject) for c in commits]
-    success, conv_log = agent.cherry_pick_commits(commit_tuples, source,
+    # Convert CommitInfo to AgentCommit format expected by agent
+    agent_commits = [AgentCommit(c.hash, c.chash, c.subject) for c in commits]
+    success, conv_log = agent.cherry_pick_commits(agent_commits, source,
                                                           branch_name)
 
     # Check for signal file from agent