#+TITLE: SKILL: PSF Loop Automator (Universal Literate Note)
#+ID: skill-loop-automator
#+STARTUP: content
#+FILETAGS: :psf:automation:meta-cognitive:orchestration:

* Overview
The **PSF Loop Automator** is the meta-cognitive orchestrator of the Personal Software Foundry. It monitors the state of all Master Notes and autonomously triggers the transition between PSF phases (e.g., waking the Architect when a PRD is frozen), ensuring the Consensus Loop maintains high momentum without manual intervention.

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

** 1. Purpose
Define automated state transitions and role-triggering for the PSF Consensus Loop.

** 2. User Needs
- **State Surveillance:** Monitor `notes/org-skill-*.org` for `#+STATUS:` changes.
- **Proactive Role Triggering:**
  - If `PRD` is `FROZEN` -> Trigger **Architect** (Phase B).
  - If `PROTOCOL` is `SIGNED` -> Trigger **Technical Analyst** (Phase C).
  - If `TDD Suite` is `RED` -> Trigger **Coder** (Phase D).
- **GTD Synchronization:** Automatically update the `:PSF-STATE:` property in `gtd.org` during transitions.

** 3. Success Criteria
*** TODO Successful detection of #+STATUS: FROZEN in a Master Note
*** TODO Autonomous stimulus injection for the Architect skill
*** TODO Verified update of :PSF-STATE: in gtd.org

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

** 1. Architectural Intent
Interfaces for cross-note state perception and kernel-level stimulus injection. Source of truth is the Master Note collection and the global skill graph.

** 2. Semantic Interfaces
#+begin_src lisp
(defun loop-automator-perceive-phase (note-path)
  "Determines the current PSF phase of a Master Note based on status and sections.")

(defun loop-automator-orchestrate ()
  "Scans all notes and dispatches necessary stimuli to the kernel.")
#+end_src

* Phase D: Build (Implementation)

** State Perception
#+begin_src lisp :tangle projects/org-skill-loop-automator/src/automator-logic.lisp
(defun loop-automator-perceive-phase (note-path)
  (let ((content (uiop:read-file-string note-path)))
    (cond
     ((and (search ":STATUS: FROZEN" content) 
           (not (search "* Phase B: Blueprint (PROTOCOL)" content)))
      :trigger-architect)
     ((and (search ":STATUS: SIGNED" content)
           (not (search "* Phase D: Build" content)))
      :trigger-analyst)
     (t :stable))))
#+end_src

** Orchestration Loop
#+begin_src lisp :tangle projects/org-skill-loop-automator/src/automator-logic.lisp
(defun loop-automator-sync-gtd (note-path new-state)
  "Updates the :PSF-STATE: property in gtd.org for the project linked to NOTE-PATH."
  (let* ((filename (pathname-name note-path))
         (project-id (format nil "proj-~a" (subseq filename 10))) ; e.g. proj-memex
         (gtd-file (or (uiop:getenv "GTD_FILE") "gtd.org")))
    (kernel-log "GTD SYNC - Updating ~a to state ~a" project-id new-state)
    ;; Dispatches an actuator request to Emacs to perform the surgical property update
    (org-agent:inject-stimulus 
     `(:type :REQUEST :target :emacs 
       :payload (:action :refactor-subtree 
                 :target-id ,project-id 
                 :properties (("PSF-STATE" . ,new-state)))))))

(defun loop-automator-orchestrate ()
  (let ((notes-dir (or (uiop:getenv "MEMEX_NOTES") "notes/")))
    (dolist (file (uiop:directory-files notes-dir "org-skill-*.org"))
      (let ((intent (loop-automator-perceive-phase file)))
        (case intent
          (:trigger-architect 
           (loop-automator-sync-gtd file "B: BLUEPRINT")
           (org-agent:inject-stimulus `(:type :EVENT :payload (:sensor :foundry-event :action :blueprint :note ,file))))
          (:trigger-analyst
           (loop-automator-sync-gtd file "C: SUCCESS")
           (org-agent:inject-stimulus `(:type :EVENT :payload (:sensor :foundry-event :action :tdd :note ,file)))))))))
#+end_src

* Registration
#+begin_src lisp
(defskill :skill-loop-automator
  :priority 95 ; High priority meta-cognition
  :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :heartbeat))
  :neuro (lambda (context) nil)
  :symbolic (lambda (action context) (loop-automator-orchestrate)))
#+end_src