#+TITLE: SKILL: Git Steward (Universal Literate Note)
#+ID: skill-git-steward
#+STARTUP: content
#+FILETAGS: :git:vcs:system:psf:

* Overview
The *Git Steward* maintains the integrity of the workspace by automating version control operations.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Automate Git operations for the Memex.

** 2. User Needs
- *Status:* Retrieve the current state of the repository.
- *Commit:* Automate staging and committing changes.
- *Push:* Synchronize with remote repositories.


* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:

** Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:

*** 1. Architectural Intent
The *Git Steward* will act as a central service for managing Git operations within the Memex environment. It will expose a well-defined interface for other components to interact with, abstracting away the complexities of Git execution.  It prioritizes ease of use, reliability, and integration with existing Memex systems. This protocol defines the functions that will be available, their inputs, and expected outputs. Functions are defined using Lisp signatures to ensure precise and unambiguous specification.

*** 2. Semantic Interfaces

**** a. git-status
     - *Purpose:* Retrieves the current status of the Git repository.

     - *Signature:* `(git-status)`

     - *Input:* None

     - *Output:* A plist containing the following keys:
       - `:branch` - The current branch name (string).
       - `:modified-files` - A list of modified files (list of strings).
       - `:untracked-files` - A list of untracked files (list of strings).
       - `:staged-files` - A list of files currently staged (list of strings).
       - `:ahead` - Number of commits ahead of remote (integer, or `nil` if not tracking a remote).
       - `:behind` - Number of commits behind remote (integer, or `nil` if not tracking a remote).

     - *Example:* `(:branch "main" :modified-files ("file1.txt" "file2.org") :untracked-files ("new_file.txt") :staged-files ("file1.txt") :ahead 2 :behind 1)`

**** b. git-commit
     - *Purpose:* Stages and commits changes to the Git repository.

     - *Signature:* `(git-commit :message string :files list-of-strings)`

     - *Input:*
       - `:message` - The commit message (string).
       - `:files` - A list of specific files to stage and commit (list of strings).  If nil, all modified and added files are staged.

     - *Output:* A boolean value. `T` for success, `nil` for failure.  On failure, an error message will be logged.

     - *Example:* `(git-commit :message "Updated documentation" :files nil)`

**** c. git-push
     - *Purpose:* Pushes commits to a remote repository.

     - *Signature:* `(git-push :remote string :branch string)`

     - *Input:*
       - `:remote` - The name of the remote repository (string).
       - `:branch` - The name of the branch to push (string).

     - *Output:* A boolean value. `T` for success, `nil` for failure. On failure, an error message will be logged.

     - *Example:* `(git-push :remote "origin" :branch "main")`

**** d. git-pull
     - *Purpose:* Pulls commits from a remote repository.

     - *Signature:* `(git-pull :remote string :branch string)`

     - *Input:*
       - `:remote` - The name of the remote repository (string).
       - `:branch` - The name of the branch to pull (string).

     - *Output:* A boolean value. `T` for success, `nil` for failure. On failure, an error message will be logged.

     - *Example:* `(git-pull :remote "origin" :branch "main")`

**** e. git-add
     - *Purpose:* Adds new files to the staging area

     - *Signature:* `(git-add :files list-of-strings)`

     - *Input:*
       - `:files` - A list of files to add to staging.

     - *Output:* A boolean value. `T` for success, `nil` for failure.

     - *Example:* `(git-add :files '("new_file.txt" "another_file.org"))`