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

notes/org-skill-workspace-manager.org

@@ -24,61 +24,63 @@ Define automated housekeeping behaviors for PARA/Zettelkasten maintenance.
 *** TODO Archiving Suggestion Loop
 *** TODO Perception Coverage (Buffer & Heartbeat)
 
+
 * Phase B: Blueprint (PROTOCOL)
 :PROPERTIES:
 :STATUS: SIGNED
 :END:
 
+
+* Phase B: Blueprint (PROTOCOL)
+:PROPERTIES:
+:STATUS: IN PROGRESS
+:END:
+
 ** 1. Architectural Intent
-Interfaces for workspace auditing and archiving suggestions.
+The Workspace Manager Agent will operate as a background process, triggered by file saves and a periodic heartbeat. It uses a combination of regular expressions and structural pattern matching to identify tasks suitable for archiving and to ensure the overall coherence of the Memex workspace structure. The agent prioritizes non-intrusive suggestions, allowing the user to retain ultimate control over the organization of their notes.
 
 ** 2. Semantic Interfaces
-#+begin_src lisp
-(defun trigger-skill-workspace-manager (context)
-  "Triggers on :buffer-update or :heartbeat.")
 
-(defun archive-completed-tasks ()
-  "Queries store for DONE tasks and returns their IDs.")
+*** Function: `workspace-manager-agent`
+    :PROPERTIES:
+    :CUSTOM_ID: workspace-manager-agent-signature
+    :END:
+    - *Signature:* `(workspace-manager-agent &key (buffer nil) (heartbeat nil))`
+    - *Purpose:*  Main entry point.  Called on buffer save or heartbeat.
+    - *Arguments:*
+      - `buffer` (optional): The buffer being saved (when triggered by a save).
+      - `heartbeat` (optional): A flag indicating a heartbeat trigger.
+    - *Returns:* A list of suggestions (see `suggestion` signature).
 
-(defun neuro-skill-workspace-manager (context)
-  "Neural synthesis of archiving suggestions.")
-#+end_src
+*** Function: `find-archivable-tasks`
+    :PROPERTIES:
+    :CUSTOM_ID: find-archivable-tasks-signature
+    :END:
+    - *Signature:* `(find-archivable-tasks buffer)`
+    - *Purpose:*  Locates tasks marked `DONE` within the specified buffer.
+    - *Arguments:*
+      - `buffer`: The buffer to scan.
+    - *Returns:* A list of task IDs (org-mode custom IDs).
 
-* Phase D: Build (Implementation)
+*** Function: `suggest-archive-task`
+    :PROPERTIES:
+    :CUSTOM_ID: suggest-archive-task-signature
+    :END:
+    - *Signature:* `(suggest-archive-task task-id)`
+    - *Purpose:* Creates a suggestion to archive the specified task.
+    - *Arguments:*
+      - `task-id`:  The CUSTOM_ID of the task to archive.
+    - *Returns:* A `suggestion` plist.
 
-** Dual Perception
-#+begin_src lisp :tangle projects/org-skill-workspace-manager/src/workspace-logic.lisp
-(defun trigger-skill-workspace-manager (context)
-  (let* ((payload (getf context :payload))
-         (sensor (getf payload :sensor)))
-    (or (eq sensor :buffer-update)
-        (eq sensor :heartbeat))))
-#+end_src
-
-** Stale Task Identification
-#+begin_src lisp :tangle projects/org-skill-workspace-manager/src/workspace-logic.lisp
-(defun archive-completed-tasks ()
-  "Identify DONE tasks and suggest archiving."
-  (let ((done-tasks (org-agent:context-query-store :todo-state "DONE" :type :HEADLINE)))
-    (when done-tasks
-      (mapcar #'org-agent:org-object-id done-tasks))))
-#+end_src
-
-** Neuro-Cognitive Drafting
-#+begin_src lisp :tangle projects/org-skill-workspace-manager/src/workspace-logic.lisp
-(defun neuro-skill-workspace-manager (context)
-  (let ((ready-to-archive (archive-completed-tasks))
-        (archive-dir (or (uiop:getenv "ARCHIVES_DIR") "archives/")))
-    (if ready-to-archive
-        (format nil "I found these completed tasks: ~a. Should I move them to ~a?" ready-to-archive archive-dir)
-        nil)))
-#+end_src
-
-* Registration
-#+begin_src lisp
-(defskill :skill-workspace-manager
-  :priority 40
-  :trigger #'trigger-skill-workspace-manager
-  :neuro #'neuro-skill-workspace-manager
-  :symbolic (lambda (action context) action))
-#+end_src
+*** Function: `suggestion`
+    :PROPERTIES:
+    :CUSTOM_ID: suggestion-signature
+    :END:
+    - *Signature:* `(&key type target message action)`
+    - *Purpose:*  Represents a suggestion made by the agent.
+    - *Arguments:*
+      - `type`: The type of suggestion (e.g., `:archive`).
+      - `target`: The ID or path of the element the suggestion applies to.
+      - `message`: A human-readable message describing the suggestion.
+      - `action`: A lisp form to execute to enact the suggestion.
+    - *Returns:* An association list (plist) conforming to the interface. Example: `(:type :archive :target "task-123" :message "Archive completed task?" :action `(org-archive-subtree "task-123"))`