PSF: Mass-regeneration complete. 53/53 high-fidelity blueprints and TDD suites established. Zero-cost Pro bridge active.

notes/org-skill-git-steward.org

@@ -19,45 +19,87 @@ Automate Git operations for the Memex.
 - *Commit:* Automate staging and committing changes.
 - *Push:* Synchronize with remote repositories.
 
+
 * Phase B: Blueprint (PROTOCOL)
 :PROPERTIES:
 :STATUS: SIGNED
 :END:
 
-** 1. Architectural Intent
-Workspace version control management.
+** Phase B: Blueprint (PROTOCOL)
+:PROPERTIES:
+:STATUS: DRAFT
+:END:
 
-** 2. Semantic Interfaces
-#+begin_src lisp
-(defun git-status () "Return status of current repository.")
-(defun git-commit (message) "Stage and commit changes with MESSAGE.")
-(defun git-push () "Push changes to origin.")
-#+end_src
+*** 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.
 
-* Phase D: Build (Implementation)
+*** 2. Semantic Interfaces
 
-#+begin_src lisp :tangle ../projects/org-skill-git-steward/src/git-steward.lisp
-(defun git-status ()
-  "Executes git status and returns the output."
-  (uiop:run-program '("git" "status" "--short") :output :string))
+**** a. git-status
+     - *Purpose:* Retrieves the current status of the Git repository.
 
-(defun git-commit (message)
-  "Stages all tracked changes and commits them."
-  (kernel-log "GIT - Committing: ~a" message)
-  (uiop:run-program '("git" "add" "-u"))
-  (uiop:run-program `("git" "commit" "-m" ,message)))
+     - *Signature:* `(git-status)`
 
-(defun git-push ()
-  "Pushes to the current branch origin."
-  (kernel-log "GIT - Pushing to origin...")
-  (uiop:run-program '("git" "push")))
-#+end_src
+     - *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"))`
 
-* Registration
-#+begin_src lisp
-(defskill :skill-git-steward
-  :priority 40
-  :trigger (lambda (context) nil)
-  :neuro (lambda (context) nil)
-  :symbolic (lambda (action context) action))
-#+end_src