passepartout/skills/org-skill-diagnostics.org

Skill: Diagnostics (org-skill-diagnostics.org)

• Overview
• Phase A: Demand (Thinking)
  • The Self-Healing Invariant
  • XDG Compliance
• Phase B: Protocol (Success Criteria)
  • Test Suite Context
  • Dependency Tests
• Phase C: Implementation (Build)
  • Package Context
  • Skill Metadata
  • Global Configuration
  • Dependency Verification
  • Environment & XDG Validation
  • LLM Connectivity
  • Orchestration
  • CLI Entry Point

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

(defpackage :opencortex-diagnostics-tests
  (:use :cl :fiveam :opencortex)
  (:export #:diagnostics-suite))

(in-package :opencortex-diagnostics-tests)

(def-suite diagnostics-suite :description "Verification of the Diagnostics skill")

(in-suite diagnostics-suite)

Dependency 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)))))

Phase C: Implementation (Build)

Package Context

(in-package :opencortex)

Skill Metadata

(defparameter *skill-diagnostics*
  '(:name "diagnostics"
    :description "Performs system health checks and environment validation."
    :capabilities (:run-diagnostics)
    :type :deterministic)
  "Skill metadata for the Diagnostics component.")

Global Configuration

(defvar *doctor-required-binaries* '("sbcl" "emacs" "git" "socat" "nc")
  "List of external binaries required for full system operation.")

Dependency Verification

(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))

Environment & XDG Validation

(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 (getenv "OC_CONFIG_DIR"))
        (data-dir (getenv "OC_DATA_DIR"))
        (state-dir (getenv "OC_STATE_DIR"))
        (memex-dir (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))

LLM Connectivity

(defun doctor-check-llm ()
  "Tests connectivity to primary LLM providers. Non-critical fallback allowed."
  (harness-log "DOCTOR: Checking LLM connectivity...")
  (let ((openrouter-key (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))))

Orchestration

(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))))

CLI Entry Point

(defun doctor-main ()
  "Entry point for the 'doctor' CLI command."
  (if (doctor-run-all)
      (uiop:quit 0)
      (uiop:quit 1)))