:PROPERTIES:
:ID:       085668da-6505-438e-b92a-736943cd4d0a
:END:
#+TITLE: SKILL: Cron Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :cron:temporal:heartbeat:psf:

* Overview
The *Cron Agent* serves as the system's temporal conscience. It provides autonomous, time-aware capabilities by hooking into the background heartbeat, enabling proactive executive assistance.

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

** 1. Purpose
Define automated behaviors for deadline monitoring and temporal alerting.

** 2. User Needs
- *Punctuality:* Monitor deadlines and alerts across the Memex.
- *Efficiency:* Symbolic filtering (System 2) to minimize LLM calls.
- *Multi-Channel Awareness:* Routing alerts to Emacs or external delivery.

** 3. Success Criteria
*** TODO Heartbeat Trigger Verification
*** TODO Timestamp Parsing Accuracy
*** TODO Overdue Task Detection


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


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

** 1. Architectural Intent
The Cron Agent operates as a reactive component driven by the Memex heartbeat.  It translates temporal events (scheduled times, deadlines, overdue conditions) into actions.  It prioritizes efficiency by using System 2 (symbolic) processing for initial filtering and triggering, reserving System 3 (LLM-assisted) operations for complex reasoning scenarios.  This agent adopts a modular design to enable easy integration with various notification channels.

** 2. Semantic Interfaces (Lisp Signatures)

*** `cron/register-task`
     Registers a new task with the Cron Agent.

     :Lisp:
     `(cron/register-task task-id schedule task-function &key (notification-channel :emacs) (deadline nil))`

     :Args:
       - `task-id`: A unique symbol identifying the task.
       - `schedule`: A cron-style string representing the task's schedule (e.g., "0 0 * * *" for daily at midnight).
       - `task-function`: A function (lambda) to execute when the schedule is met and the conditions are satisfied.  This function must take a plist containing the task-id and scheduled-time.
       - `notification-channel`: Keyword specifying the destination for alerts (:emacs, :slack, :email).  Defaults to `:emacs`.
       - `deadline`: An optional ISO-8601 timestamp string representing the deadline.  If a deadline is specified, the `task-function` will also receive information about whether the task is overdue.

     :Returns:
       The `task-id` on successful registration, or `nil` if registration fails.

     :Side Effects:
       Adds the task to the internal cron table.

*** `cron/remove-task`
     Removes a previously registered task.

     :Lisp:
     `(cron/remove-task task-id)`

     :Args:
       - `task-id`: The unique symbol identifying the task to be removed.

     :Returns:
       `T` if the task was successfully removed, `nil` otherwise.

     :Side Effects:
       Removes the task from the internal cron table.

*** `cron/check-schedule`
     (Internal) Called by the heartbeat to check if any tasks are due.

     :Lisp:
     `(cron/check-schedule current-time)`

     :Args:
       - `current-time`: A timestamp representing the current time.

     :Returns:
       `nil` (No return value).

     :Side Effects:
       Executes any tasks that are due based on their schedule and deadline.

*** `cron/notify`
     Sends a notification through the specified channel.

     :Lisp:
     `(cron/notify message channel)`

     :Args:
       - `message`: The message to be sent.
       - `channel`:  The notification channel (:emacs, :slack, :email).

     :Returns:
       `T` if the notification was sent successfully, `nil` otherwise.

     :Side Effects:
       Sends a notification.  The implementation details of sending notifications through various channels are handled internally.