passepartout/skills/org-skill-diagnostics.org

#+TITLE: Skill: Diagnostics (org-skill-diagnostics.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:diagnostic:health:
#+STARTUP: content

* Overview
The *Diagnostics Skill* provides the OpenCortex Agent with the capability to perform self-examinations and environment validation. 

By moving this logic from the harness to a skill, we enable the Agent's **Reflection Loop** to autonomously run health checks when a tool fails, transforming the Agent into a self-healing system.

* Phase A: Demand (Thinking)
** The Self-Healing Invariant
In a standard Lisp Machine, the system should be able to reason about its own environment. The `:run-diagnostics` capability ensures the Agent can verify its own dependency chain and XDG directory structure.

** XDG Compliance
The skill strictly validates the POSIX standard paths resolved during bootstrap, ensuring no silent configuration drift occurs.

* Phase B: Protocol (Success Criteria)

** Test Suite Context
#+begin_src lisp :tangle (expand-file-name "diagnostics-tests.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/tests"))
(defpackage :opencortex-diagnostics-tests
  (:use :cl :fiveam :opencortex)
  (:export #:diagnostics-suite))
#+end_src

#+begin_src lisp :tangle (expand-file-name "diagnostics-tests.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/tests"))
(in-package :opencortex-diagnostics-tests)
#+end_src

#+begin_src lisp :tangle (expand-file-name "diagnostics-tests.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/tests"))
(def-suite diagnostics-suite :description "Verification of the Diagnostics skill")
#+end_src

#+begin_src lisp :tangle (expand-file-name "diagnostics-tests.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/tests"))
(in-suite diagnostics-suite)
#+end_src

** Dependency Tests
#+begin_src lisp :tangle (expand-file-name "diagnostics-tests.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/tests"))
(test test-dependency-check-fail
  "Verify that missing binaries are correctly identified as failures."
  (let ((opencortex::*doctor-required-binaries* '("non-existent-binary-123")))
    (is (null (opencortex:doctor-check-dependencies)))))
#+end_src

* Phase C: Implementation (Build)

** Package Context
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/skills"))
(in-package :opencortex)
#+end_src

** Skill Metadata
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/skills"))
(defparameter *skill-diagnostics*
  '(:name "diagnostics"
    :description "Performs system health checks and environment validation."
    :capabilities (:run-diagnostics)
    :type :deterministic)
  "Skill metadata for the Diagnostics component.")
#+end_src

** Global Configuration
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/skills"))
(defvar *doctor-required-binaries* '("sbcl" "emacs" "git" "socat" "nc")
  "List of external binaries required for full system operation.")
#+end_src

** Dependency Verification
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/skills"))
(defun doctor-check-dependencies ()
  "Verifies that required external binaries are available in the PATH via a shell probe."
  (let ((all-ok t))
    (harness-log "DOCTOR: Checking system dependencies...")
    (dolist (dep *doctor-required-binaries*)
      (let ((path (ignore-errors 
                    (uiop:run-program (list "which" dep) 
                                      :output :string :ignore-error-status t))))
        (if (and path (> (length path) 0))
            (harness-log "  [OK] Found ~a" dep)
            (progn
              (harness-log "  [FAIL] Missing binary: ~a" dep)
              (setf all-ok nil)))))
    all-ok))
#+end_src

** Environment & XDG Validation
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/skills"))
(defun doctor-check-env ()
  "Validates XDG directories and environment configuration against the POSIX standard."
  (harness-log "DOCTOR: Checking XDG environment...")
  (let ((all-ok t)
        (config-dir (uiop:getenv "OC_CONFIG_DIR"))
        (data-dir (uiop:getenv "OC_DATA_DIR"))
        (state-dir (uiop:getenv "OC_STATE_DIR"))
        (memex-dir (uiop:getenv "MEMEX_DIR")))
    
    (flet ((check-dir (name path critical)
             (if (and path (> (length path) 0))
                 (if (uiop:directory-exists-p path)
                     (harness-log "  [OK] ~a: ~a" name path)
                     (progn
                       (harness-log "  [FAIL] ~a directory missing: ~a" name path)
                       (when critical (setf all-ok nil))))
                 (progn
                   (harness-log "  [FAIL] ~a variable not set." name)
                   (when critical (setf all-ok nil))))))

      (check-dir "Config (OC_CONFIG_DIR)" config-dir t)
      (check-dir "Data (OC_DATA_DIR)" data-dir t)
      (check-dir "State (OC_STATE_DIR)" state-dir t)
      (check-dir "Memex (MEMEX_DIR)" memex-dir t))
    all-ok))
#+end_src

** LLM Connectivity
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/skills"))
(defun doctor-check-llm ()
  "Tests connectivity to primary LLM providers. Non-critical fallback allowed."
  (harness-log "DOCTOR: Checking LLM connectivity...")
  (let ((openrouter-key (uiop:getenv "OPENROUTER_API_KEY")))
    (if (and openrouter-key (> (length openrouter-key) 0))
        (progn
          (harness-log "  [OK] OpenRouter API Key detected.")
          t)
        (progn
          (harness-log "  [WARN] No OpenRouter API Key. Falling back to local inference only.")
          t))))
#+end_src

** Orchestration
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/skills"))
(defun doctor-run-all ()
  "Executes the full diagnostic suite and returns T if system is healthy."
  (harness-log "==================================================")
  (harness-log " OPENCORTEX DOCTOR: Commencing Health Check")
  (harness-log "==================================================")
  (let ((dep-ok (doctor-check-dependencies))
        (env-ok (doctor-check-env))
        (llm-ok (doctor-check-llm)))
    (harness-log "==================================================")
    (if (and dep-ok env-ok)
        (progn
          (harness-log " ✓ SYSTEM HEALTHY: Ready for ignition.")
          t)
        (progn
          (harness-log " ✗ SYSTEM UNHEALTHY: Fix the errors above.")
          nil))))
#+end_src

** CLI Entry Point
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (getenv "INSTALL_DIR") ".") "/skills"))
(defun doctor-main ()
  "Entry point for the 'doctor' CLI command."
  (if (doctor-run-all)
      (uiop:quit 0)
      (uiop:quit 1)))
#+end_src