feat(hooks): implement conditional execution for make and journal hooks

apiad · apiad · commit 6e50e5ac8e56 · 2026-03-11T17:24:40.000-04:00
diff --git a/.gemini/.gitignore b/.gemini/.gitignore
@@ -0,0 +1,2 @@
+last_make_run
+last_journal_update
diff --git a/.gemini/hooks/journal.py b/.gemini/hooks/journal.py
@@ -1,54 +1,125 @@
 #!/usr/bin/env python3
 """
-Hook to enforce project journaling for all significant changes.
+Hook to enforce project journaling conditionally for all significant changes.
 
 This hook is triggered 'AfterAgent' and checks if the daily journal entry has been updated
-whenever there are uncommitted changes in the repository.
+whenever there are NEW uncommitted changes since the last recorded journal update.
 """
 import sys
 import os
+import subprocess
+import time
 from datetime import datetime
 
 # Add the hooks directory to path for importing utils
 sys.path.append(os.path.dirname(os.path.abspath(__file__)))
 import utils
 
+# Path to the state file relative to this script
+STATE_FILE = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+    "last_journal_update"
+)
+
+def get_last_update_timestamp():
+    """Reads the last recorded journal update timestamp from the state file."""
+    if not os.path.exists(STATE_FILE):
+        return 0
+    try:
+        with open(STATE_FILE, "r") as f:
+            return float(f.read().strip())
+    except (ValueError, OSError):
+        return 0
+
+def update_last_update_timestamp():
+    """Updates the state file with the current timestamp."""
+    try:
+        with open(STATE_FILE, "w") as f:
+            f.write(str(time.time()))
+    except OSError:
+        pass
+
+def get_changed_files():
+    """
+    Returns a list of files that are either modified or untracked in git.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain=v1", "-uall"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        lines = result.stdout.splitlines()
+        return [line[3:].strip() for line in lines if line.strip()]
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return []
+
 def main():
     """
     Main entry point for the journal enforcement hook.
     
-    Checks git status for uncommitted changes and identifies if the current daily journal
-    has been updated accordingly. Returns 'deny' if it's missing.
+    Identifies new uncommitted changes and identifies if the daily journal
+    needs to be updated. Returns 'deny' if it's missing for new work.
     """
     try:
-        modified_files = utils.get_modified_files()
+        changed_files = get_changed_files()
         
         today = datetime.now().strftime("%Y-%m-%d")
         journal_file = f"journal/{today}.md"
+        
+        last_update = get_last_update_timestamp()
 
-        # Check if there are changes other than the daily journal
-        significant_changes = [
-            f for f in modified_files
-            if f != journal_file
-        ]
-
-        # Check if the daily journal was updated
-        journal_updated = journal_file in modified_files
-
-        if significant_changes and not journal_updated:
-            utils.send_hook_decision(
-                "deny",
-                reason=(
-                    f"Please add a one-line entry to {journal_file} "
-                    "describing the changes you just made. Do not stop until this file is updated."
-                )
-            )
-        else:
+        # 1. Identify files modified after last_update (excluding the journal)
+        new_significant_changes = []
+        latest_change_time = 0
+        
+        for f in changed_files:
+            if f == journal_file:
+                continue
+            
+            f_mtime = 0
+            if os.path.exists(f):
+                f_mtime = os.path.getmtime(f)
+            else:
+                # File deleted. We treat deletions as new work "now".
+                f_mtime = time.time()
+                
+            if f_mtime > last_update:
+                new_significant_changes.append(f)
+                latest_change_time = max(latest_change_time, f_mtime)
+
+        if not new_significant_changes:
+            # No new work since last journal update.
+            # However, if the journal itself was updated in the turn,
+            # we should update the timestamp so we don't re-process old changes.
+            if journal_file in changed_files:
+                update_last_update_timestamp()
             utils.send_hook_decision("allow")
+            return
+
+        # 2. We have new significant changes. Check if the journal was updated AFTER them.
+        if journal_file in changed_files:
+            journal_mtime = os.path.getmtime(journal_file)
+            if journal_mtime > latest_change_time:
+                # Journal was updated after the latest significant change.
+                update_last_update_timestamp()
+                utils.send_hook_decision("allow")
+                return
+
+        # 3. Deny because new work exists but journal hasn't caught up.
+        utils.send_hook_decision(
+            "deny",
+            reason=(
+                f"New changes detected: {', '.join(new_significant_changes[:3])}{'...' if len(new_significant_changes) > 3 else ''}.\n"
+                f"Please add or update a one-line entry to {journal_file} "
+                "describing the work you just did. Do not stop until this file is updated."
+            )
+        )
 
-    except Exception:
+    except Exception as e:
         # Failsafe: always allow if something goes wrong
-        utils.send_hook_decision("allow")
+        utils.send_hook_decision("allow", reason=f"Hook error: {str(e)}")
 
 if __name__ == "__main__":
     main()
diff --git a/.gemini/hooks/make.py b/.gemini/hooks/make.py
@@ -1,28 +1,107 @@
 #!/usr/bin/env python3
 """
-Hook to run 'make' validation before critical agent actions.
+Hook to run 'make' validation conditionally before critical agent actions.
 
 This hook is triggered 'AfterAgent' and ensures that the codebase passes
-all linting and testing checks defined in the makefile.
+all linting and testing checks defined in the makefile. It skips execution
+if no changes have been detected since the last successful run.
 """
 import sys
 import os
 import subprocess
+import time
 
 # Add the hooks directory to path for importing utils
 sys.path.append(os.path.dirname(os.path.abspath(__file__)))
 import utils
 
+# Path to the state file relative to this script
+# Stored in .gemini/last_make_run (one level up from .gemini/hooks/)
+STATE_FILE = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+    "last_make_run"
+)
+
+def get_last_run_timestamp():
+    """Reads the last successful run timestamp from the state file."""
+    if not os.path.exists(STATE_FILE):
+        return 0
+    try:
+        with open(STATE_FILE, "r") as f:
+            return float(f.read().strip())
+    except (ValueError, OSError):
+        return 0
+
+def update_last_run_timestamp():
+    """Updates the state file with the current timestamp."""
+    try:
+        with open(STATE_FILE, "w") as f:
+            f.write(str(time.time()))
+    except OSError:
+        pass
+
+def get_changed_files():
+    """
+    Returns a list of files that are either modified or untracked in git.
+    """
+    try:
+        # Get both modified and untracked files
+        # --porcelain=v1 ensures a stable machine-readable output
+        # -u (all) shows untracked files
+        result = subprocess.run(
+            ["git", "status", "--porcelain=v1", "-uall"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        lines = result.stdout.splitlines()
+        # Each line is: "XY PATH" where XY are status codes
+        # We want the path part (from index 3 onwards)
+        return [line[3:].strip() for line in lines if line.strip()]
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return []
+
+def should_run_make():
+    """
+    Determines if 'make' should be executed based on file modification times.
+    """
+    last_run = get_last_run_timestamp()
+    if last_run == 0:
+        return True, "Initial run or missing timestamp."
+
+    changed_paths = get_changed_files()
+    if not changed_paths:
+        return False, "No uncommitted or untracked changes detected."
+
+    for path in changed_paths:
+        # Check if file exists (might have been deleted)
+        if os.path.exists(path):
+            if os.path.getmtime(path) > last_run:
+                return True, f"File modified: {path}"
+        else:
+            # File was deleted. We treat deletions as changes.
+            # Since the file is gone, its parent directory's mtime should have updated.
+            # Or we can just assume any deletion warrants a re-run.
+            return True, f"File deleted: {path}"
+
+    return False, "No files modified since last successful validation."
+
 def main():
     """
     Main entry point for the make validation hook.
     
-    Executes 'uv run make' and returns a 'deny' decision if the process fails.
+    Executes 'make' conditionally and returns a decision.
     """
     try:
-        # Run make command using uv run to ensure dependencies are available
+        run_needed, reason = should_run_make()
+        
+        if not run_needed:
+            utils.send_hook_decision("allow", reason=f"Skipping 'make' ({reason})")
+            return
+
+        # Run make command directly
         result = subprocess.run(
-            ["uv", "run", "make"],
+            ["make"],
             capture_output=True,
             text=True,
             check=False
@@ -31,21 +110,22 @@ def main():
         if result.returncode != 0:
             # make failed
             error_message = result.stdout + "\n" + result.stderr
-            reason = (
+            fail_reason = (
                 f"Validation failed (make returned {result.returncode}).\n"
                 "Please fix the broken tests or linting issues.\n"
                 "Output of 'make':\n"
                 "```\n" + error_message.strip() + "\n```\n"
                 "Fix these issues and ensure 'make' passes before continuing."
             )
-            utils.send_hook_decision("deny", reason=reason)
+            utils.send_hook_decision("deny", reason=fail_reason)
         else:
             # make passed
+            update_last_run_timestamp()
             utils.send_hook_decision("allow")
 
-    except Exception:
-        # Failsafe: always allow if the hook itself fails
-        utils.send_hook_decision("allow")
+    except Exception as e:
+        # Failsafe: always allow if the hook itself fails, but log the error in reason
+        utils.send_hook_decision("allow", reason=f"Hook error: {str(e)}")
 
 if __name__ == "__main__":
     main()
diff --git a/plans/conditional-journal-enforcement.md b/plans/conditional-journal-enforcement.md
@@ -0,0 +1,61 @@
+# Execution Plan: Conditional Journal Hook Enforcement
+
+This plan outlines the modifications needed to implement conditional enforcement for the `.gemini/hooks/journal.py` hook. The goal is to only require a journal update if new changes have been detected in the workspace since the last recorded journal update.
+
+## Objective
+Modify the `journal` hook logic to use file modification times (`mtime`) and `git` status to determine if a journal update is strictly necessary.
+
+## Architectural Impact
+- **Efficiency:** Reduces friction by only requiring journal entries when new work has actually been performed.
+- **State Management:** Introduces a lightweight persistence mechanism in `.gemini/last_journal_update`.
+
+## File Operations
+
+### 1. Modify `.gemini/.gitignore`
+- **Action:** Add `last_journal_update` to the existing `.gemini/.gitignore`.
+- **Content:**
+  ```text
+  last_make_run
+  last_journal_update
+  ```
+
+### 2. Modify `.gemini/hooks/journal.py`
+- **Action:** Update the existing hook script to include change detection and timestamp logic.
+- **Key Logic Changes:**
+    - Define `STATE_FILE` path (e.g., `.gemini/last_journal_update`).
+    - Use `git status --porcelain=v1` to identify all modified and untracked files.
+    - Implement `get_last_journal_update()` and `update_last_journal_update()` for state persistence.
+    - If the current daily journal is in the list of modified files, update the `STATE_FILE` with the current time and return `allow`.
+    - If any other modified or untracked file has an `mtime > last_journal_update`, return `deny` with a request to update the journal.
+    - Return `allow` if no newer changes are found.
+
+### 3. Update `TASKS.md`
+- **Action:** Add a new entry to the `Archive` or `Active Tasks` section.
+- **Task Description:** `Implement conditional journal hook enforcement based on file modification times.`
+
+## Step-by-Step Execution
+
+### Step 1: Update State Ignoring
+1. Open `.gemini/.gitignore`.
+2. Append `last_journal_update` to it.
+
+### Step 2: Implement the Enhanced Hook
+1. Open `.gemini/hooks/journal.py`.
+2. Replace the current logic with the new implementation:
+    - Add `import time`.
+    - Define `STATE_FILE`.
+    - Implement `should_require_journal_update()` to perform the comparison.
+    - Refactor `main()` to use the new logic and update the timestamp when the journal is modified.
+
+### Step 3: Verify and Document
+1. Update `TASKS.md` to reflect the completed work.
+2. Ensure PEP 257 docstrings are maintained/added for clarity.
+
+## Testing Strategy
+
+### Automated/Manual Validation Scenarios
+1.  **Fresh Workspace:** Remove `.gemini/last_journal_update`. Modify a file. Verify it requires a journal entry.
+2.  **Journal Updated:** Update the journal. Verify the hook now returns `allow` and creates/updates the state file.
+3.  **No New Changes:** Run the hook again immediately. Verify it returns `allow`.
+4.  **New Modification:** Update another source file. Verify it requires a journal entry again (since its `mtime > last_journal_update`).
+5.  **Deleted File:** Delete a file. Verify it requires a journal entry (detected via parent directory `mtime`).
diff --git a/plans/conditional-make-hook.md b/plans/conditional-make-hook.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+last_make_run`
	`2`	`+last_journal_update`