passepartout/skills/org-skill-peripheral-vision.org

:PROPERTIES:
:ID:       org-skill-peripheral-vision
:CREATED:  [2026-04-12 Sun 14:15]
:END:
#+TITLE: SKILL: Peripheral Vision (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :context:foveal:peripheral:pruning:autonomy:

* Overview
The *Peripheral Vision* skill implements the Foveal-Peripheral Hybrid model for context pruning. It ensures that the LLM receives a semantically relevant and manageable view of the Memory, preventing context window overflow.

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

** 1. Purpose
Refine the global awareness provided to the LLM by pruning irrelevant branches of the Org DAG while maintaining high-fidelity focus on the current task.

** 2. User Needs
- *Semantic Pruning:* Use vector similarity to include only related nodes.
- *Structural Integrity:* Always include top-level projects and recent tasks.
- *Foveal Focus:* Provide full-body content for the currently active node.

** 3. Success Criteria
- [ ] Correctly calculate semantic relevance using the Embedding skill.
- [ ] Recursively render the Org DAG with depth-based and similarity-based pruning.
- [ ] Successfully generate the `GLOBAL MEMEX AWARENESS` block for the probabilistic-gate.

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

** 1. Architectural Intent
Move context pruning and rendering logic out of `context.lisp` to allow for more sophisticated, pluggable pruning strategies.

** 2. Semantic Interfaces

#+begin_src lisp :tangle ../library/gen/org-skill-peripheral-vision.lisp
(defun context-render-to-org (obj &key depth foveal-id semantic-threshold foveal-vector)
  "Recursively renders an org-object with foveal-peripheral pruning.")

(defun context-assemble-global-awareness (&optional signal)
  "Assembles the full context block for a neural request.")
#+end_src

* Phase D: Build (Implementation)

** Foveal-Peripheral Pruning
#+begin_src lisp :tangle ../library/gen/org-skill-peripheral-vision.lisp

(defun context-render-to-org (obj &key (depth 1) (foveal-id nil) (semantic-threshold 0.75) (foveal-vector nil))
  "Recursively renders an org-object and its children to an Org string using a Foveal-Peripheral Hybrid model."
  (let* ((id (org-object-id obj))
         (is-foveal (equal id foveal-id))
         (title (or (getf (org-object-attributes obj) :TITLE) "Untitled"))
         (content (org-object-content obj))
         (children (org-object-children obj))
         (stars (make-string depth :initial-element #\*))
         (obj-vector (org-object-vector obj))
         (similarity (if (and foveal-vector obj-vector (not is-foveal))
                         (cosine-similarity foveal-vector obj-vector)
                         0.0))
         (is-semantically-relevant (>= similarity semantic-threshold))
         ;; We always render depth 1 and 2 (Projects and main tasks).
         ;; We always render the foveal node and its immediate children.
         ;; We render deeper nodes ONLY if they are semantically relevant.
         (should-render (or (<= depth 2) is-foveal is-semantically-relevant))
         (output ""))
    
    (when should-render
      (setf output (format nil "~a ~a~%:PROPERTIES:~%:ID: ~a~%" stars title id))
      (when (and is-semantically-relevant (> similarity 0))
        (setf output (concatenate 'string output (format nil ":SEMANTIC_SCORE: ~,2f~%" similarity))))
      (setf output (concatenate 'string output (format nil ":END:~%")))
      
      ;; Only include full body content if this is the Foveal focus or highly relevant
      (when (and content (or is-foveal is-semantically-relevant))
        (setf output (concatenate 'string output content (string #\Newline))))
      
      ;; Recursively render children
      (dolist (child-id children)
        (let ((child-obj (lookup-object child-id)))
          (when child-obj
            ;; If the current node is Foveal, its children should be rendered (depth effectively resets)
            (let ((next-foveal (if is-foveal child-id foveal-id)))
              (setf output (concatenate 'string output 
                                        (context-render-to-org child-obj 
                                                               :depth (1+ depth) 
                                                               :foveal-id next-foveal
                                                               :semantic-threshold semantic-threshold
                                                               :foveal-vector foveal-vector))))))))
    output))

(defun context-assemble-global-awareness (&optional signal)
  "Produces a high-level skeletal outline of the current Memory for the LLM."
  (let* ((payload (when signal (getf signal :payload)))
         (foveal-id (when payload (getf payload :target-id)))
         (foveal-vector (when foveal-id (org-object-vector (lookup-object foveal-id))))
         (projects (context-get-active-projects))
         (output "GLOBAL MEMEX AWARENESS (Peripheral Vision):
"))
    (if projects
        (dolist (project projects)
          (setf output (concatenate 'string output
                                    (context-render-to-org project 
                                                           :foveal-id foveal-id 
                                                           :foveal-vector foveal-vector))))
        (setf output (concatenate 'string output "No active projects found.~%")))
    output))
#+end_src

* Registration
#+begin_src lisp :tangle ../library/gen/org-skill-peripheral-vision.lisp
(defskill :skill-peripheral-vision
  :priority 90
  :dependencies ("org-skill-embedding")
  :trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:perceive :context-refresh)))
  :probabilistic nil
  :deterministic (lambda (action ctx)
              (declare (ignore action ctx))
              ;; This skill primarily provides the context-assemble-global-awareness function
              ;; used by the probabilistic-gate, rather than handling specific actions.
              nil))
#+end_src