DOCS: Systematic overhaul of Literate source (Granularity & Technical Reasoning)

skills/org-skill-gardener.org

@@ -1,60 +1,43 @@
-:PROPERTIES:
-:ID:       gardener-skill
-:CREATED:  [2026-04-13 Mon 18:50]
-:END:
 #+TITLE: SKILL: Autonomous Gardener (Memex Maintenance)
-#+STARTUP: content
+#+AUTHOR: Amr
 #+FILETAGS: :gardener:maintenance:memex:autonomy:
+#+STARTUP: content
 
 * Overview
 The *Autonomous Gardener* is the metabolic immune system of the Memex. It autonomously audits the knowledge graph for structural decay—broken links, orphaned nodes, and missing metadata—ensuring that the system remains coherent and navigatable over long horizons.
 
-* Phase A: Demand (PRD)
-:PROPERTIES:
-:STATUS: SIGNED
-:END:
+** Architectural Intent: Graph Integrity
+In a self-evolving Memex, structural decay is inevitable. Links break as notes are renamed, and nodes become orphaned as projects are abandoned. The Gardener ensures that the "Vibe" of the Memex remains healthy by:
+1. **Auditing:** Identifying broken `id:` links.
+2. **Analysis:** Flagging nodes with zero inbound or outbound connections (Orphans).
+3. **Reporting:** Logging structural issues for user review or future autonomous repair.
 
-** 1. Purpose
-Maintain the structural integrity and "Vibe" of the Memex through autonomous auditing and self-repair proposals.
+* Implementation
 
-** 2. Success Criteria
-- [ ] *Link Audit:* Detect `id:` links that point to non-existent objects.
-- [ ] *Orphan Detection:* Identify headlines that have zero inbound or outbound connections.
-- [ ] *Reporting:* Log structural issues or propose "Flight Plans" for manual repair.
-
-* Phase B: Blueprint (PROTOCOL)
-:PROPERTIES:
-:STATUS: SIGNED
-:END:
-
-** 1. Architectural Intent
-The Gardener runs on a low-priority heartbeat. It performs a "Deep Audit" of the entire `*memory*` graph. Unlike the Scribe, which creates new data, the Gardener focuses on the *relationships* between existing data.
-
-** 2. Semantic Interfaces
-- Trigger: `(:sensor :heartbeat)`
-- Action (Repair): `(:type :REQUEST :target :emacs :action :update-node :id "..." :attributes (...))`
-
-* Phase D: Build (Implementation)
-
-** Package Context
+** Package Initialization
 #+begin_src lisp
-(in-package :opencortex)
+(in-package :cl-user)
+(defpackage :opencortex.skills.org-skill-gardener
+  (:use :cl :opencortex))
+(in-package :opencortex.skills.org-skill-gardener)
 #+end_src
 
 ** State: Maintenance Cycle
-We track the last audit time to ensure the Gardener doesn't over-consume resources.
+To minimize system overhead, the Gardener only performs a full audit pass periodically.
 
 #+begin_src lisp
 (defvar *gardener-last-audit* 0
   "The universal-time of the last full Memex audit.")
 #+end_src
 
-** Audit: Broken Links
-Scans the content of all objects for `id:` links and verifies the targets exist.
+* The Audit Engine
+
+** Link Verification (gardener-find-broken-links)
+This function performs deep packet inspection of the Memory graph. It utilizes regular expressions to find Org-mode ID links and verifies their targets against the live object registry.
 
 #+begin_src lisp
 (defun gardener-find-broken-links ()
-  "Returns a list of broken ID links found in the Memex."
+  "Scans all objects in memory for broken internal ID links."
   (let ((broken nil))
     (maphash (lambda (id obj)
                (let ((content (org-object-content obj)))
@@ -66,12 +49,12 @@ Scans the content of all objects for `id:` links and verifies the targets exist.
     broken))
 #+end_src
 
-** Audit: Orphaned Nodes
-Identifies nodes that are not linked to and do not link to anything else.
+** Orphan Detection (gardener-find-orphans)
+Structural isolation limits the effectiveness of semantic reasoning. This function maps the entire graph topology to identify nodes that have effectively "fallen off" the Memex.
 
 #+begin_src lisp
 (defun gardener-find-orphans ()
-  "Returns a list of IDs for headlines that are structurally isolated."
+  "Identifies nodes with zero connectivity in the knowledge graph."
   (let ((inbound (make-hash-table :test 'equal))
         (outbound (make-hash-table :test 'equal))
         (orphans nil))
@@ -92,12 +75,14 @@ Identifies nodes that are not linked to and do not link to anything else.
     orphans))
 #+end_src
 
-** Skill Logic: The Audit Pass
-The Gardener's deterministic gate performs the actual analysis and logs the results. In future versions, it will generate probabilistic repair proposals.
+* Metabolic Integration
+
+** Main Audit Gate (gardener-deterministic-gate)
+The primary execution hook. It performs the audit and translates technical findings into human-readable logs for the harness.
 
 #+begin_src lisp
 (defun gardener-deterministic-gate (action context)
-  "Main gate for the Gardener skill. Audits graph integrity."
+  "Main gate for the Gardener skill. Audits graph integrity and logs reports."
   (declare (ignore action context))
   (let ((broken (gardener-find-broken-links))
         (orphans (gardener-find-orphans)))
@@ -113,8 +98,8 @@ The Gardener's deterministic gate performs the actual analysis and logs the resu
         (harness-log "  [ORPHAN] Node ~a is isolated." orphan)))
     
     (setf *gardener-last-audit* (get-universal-time))
-    ;; Return a log to stop the loop
-    (list :type :LOG :payload (list :text "Gardener audit complete."))))
+    ;; Stop the pipeline by returning a Log event.
+    (list :type :LOG :payload (list :text "Gardener audit pass complete."))))
 #+end_src
 
 ** Skill Registration
@@ -125,7 +110,7 @@ The Gardener's deterministic gate performs the actual analysis and logs the resu
              (let* ((payload (getf ctx :payload))
                     (sensor (getf payload :sensor)))
                (and (eq sensor :heartbeat)
-                    ;; Only audit once per day
+                    ;; Optimization: Only audit once every 24 hours
                     (> (- (get-universal-time) *gardener-last-audit*) 86400))))
   :probabilistic nil
   :deterministic #'gardener-deterministic-gate)