:PROPERTIES:
:ID:       9dd80d2f-ec60-4263-92d9-a50b87270dda
:CREATED:  [2026-03-30 Mon 21:16]
:EDITED:   [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Chaos Gauntlet (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :chaos:testing:reliability:psf:
#+DEPENDS_ON: skill-shell-actuator skill-tdd-runner

* Overview
The *Chaos Gauntlet* is an adversarial testing skill designed to ensure the system's resilience. It simulates environmental failures, malformed LLM responses, and network disruptions, forcing the harness and its skills to handle "Byzantine" conditions gracefully.

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

** 1. Purpose
Verify the system's stability and error-handling capabilities under stress.

** 2. User Needs
- *Failure Simulation:* Ability to inject artificial delays or errors into the Harness Communication bus.
- *Byzantine Response Testing:* Test how Deterministic Engine handles nonsensical or malicious Probabilistic Engine proposals.
- *Network Resilience:* Simulate Gitea or LLM provider timeouts.
- *Recovery Verification:* Ensure the harness can recover from a "skip-event" restart.

* Phase D: Build (Implementation)
:PROPERTIES:
:STATUS: SIGNED
:END:

** Chaos Injection Logic
#+begin_src lisp :tangle ../src/chaos-logic.lisp
(in-package :opencortex)

(defun chaos-inject-error (sensor-type)
  "Injects a synthetic error into a specific sensor pipeline."
  (unless *chaos-enabled-p*
    (harness-log "CHAOS ERROR - Injection blocked. Production gate is ACTIVE.")
    (return-from chaos-inject-error nil))
  (harness-log "CHAOS - Injecting synthetic error into ~a sensor..." sensor-type)
  (inject-stimulus 
   `(:type :EVENT :payload (:sensor ,sensor-type :error "SYNTHETIC_CHAOS_ERROR"))))

(defun chaos-stress-test (action context)
  "Executes a randomized stress test by injecting failures into the system."
  (declare (ignore context))
  (unless *chaos-enabled-p*
    (harness-log "CHAOS ERROR - Stress test blocked. Production gate is ACTIVE.")
    (return-from chaos-stress-test "FAILURE - Production gate active."))
  (let* ((payload (getf action :payload))
         (mode (or (getf payload :mode) :random))
         (intensity (or (getf payload :intensity) 3)))
    (harness-log "CHAOS - Commencing stress test (Mode: ~a, Intensity: ~a)" mode intensity)
    (snapshot-object-store)
    (case mode
      (:random (dotimes (i intensity)
                 (let ((failure-type (nth (random 3) '(:test-failure :shell-timeout :llm-error))))
                   (inject-stimulus 
                    `(:type :EVENT :payload (:sensor :chaos-injection :type ,failure-type))))))
      (:shell (inject-stimulus 
               `(:type :EVENT :payload (:sensor :shell-response :cmd "git push" :exit-code 128 :stderr "fatal: network unreachable")))))
    (snapshot-object-store)
    (format nil "SUCCESS - Chaos stress test initiated.")))

(defun chaos-enable ()
  "Disables the production gate and allows chaos injection."
  (setf *chaos-enabled-p* t)
  (harness-log "CHAOS - Production gate DISABLED. Chaos injection is now ALLOWED.")
  t)

(defun chaos-disable ()
  "Enables the production gate and blocks chaos injection."
  (setf *chaos-enabled-p* nil)
  (harness-log "CHAOS - Production gate ENABLED. Chaos injection is now BLOCKED.")
  t)
#+end_src


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

** 1. Architectural Intent
The *Chaos Gauntlet* skill is designed to be non-invasive, running primarily in a background mode.  It should not interfere with normal system operation unless explicitly triggered. It is protected by a **Production Gate** (`*chaos-enabled-p*`) to prevent accidental disruptions during real work.

- *Controlled Chaos:* Failures must be injected in a precise and controllable manner.
- *Merkle Integrity:* Every stress test triggers a Merkle snapshot before and after to allow for full-system rollback.
- *Observability:*  The system's response to failures must be easily observable through logging.

** 2. Semantic Interfaces

*** A.  Gate Control

#+begin_src lisp
(defun chaos-enable ()
  "Disables the production gate and allows chaos injection.")

(defun chaos-disable ()
  "Enables the production gate and blocks chaos injection.")
#+end_src

*** B.  Triggering Chaos

    *`chaos-trigger` Sensor:*
      Events of type `:EVENT` with a `:payload` containing `(:sensor :chaos-trigger)` trigger the skill. The payload can contain a `:mode` key to specify the type of chaos to inject (e.g., `:random`, `:shell`), and an `:intensity` to control the number of failures injected.

    *Signature:*

 `#+begin_src lisp
   ;; Triggers the chaos skill.
   (defun trigger-chaos (mode intensity)
     "Triggers the chaos gauntlet with a specified mode and intensity."
     (opencortex:inject-stimulus
      `(:type :EVENT :payload (:sensor :chaos-trigger :mode ,mode :intensity ,intensity))))
 #+end_src

 *** B.  Injecting Synthetic Errors

    *`chaos-inject-error` Function:*
      Injects a synthetic error event into a specified sensor pipeline.  Different sensor types will react differently to synthetic errors.

    *Signature:*

 `#+begin_src lisp
   ;; Injects a synthetic error into a specific sensor pipeline.
   (defun chaos-inject-error (sensor-type error-message)
     "Injects a specific synthetic error into a specific sensor."
     (opencortex:inject-stimulus
      `(:type :EVENT :payload (:sensor ,sensor-type :error ,error-message))))
 #+end_src

 *** C.  Simulating Network Disruptions

     The `chaos-stress-test` function, when `mode` is `:shell`, simulates network disruptions by returning a specific error code from a shell command (e.g., `git push`).

     *Signature:* (covered by existing implementation in Phase D).

 *** D.  Kernel Restart Simulation

  Deliberately trigger `skip-event` to test recovery protocols.
   *Signature:*

 `#+begin_src lisp
  ;; simulates a skip event (a full opencortex reboot)
  (defun chaos-force-skip-event ())
 #+end_src
 

* Registration
#+begin_src lisp
(defskill :skill-chaos
  :priority 10 ; Lower priority, used for background testing
  :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :chaos-trigger))
  :neuro (lambda (context) 
           (let ((p (getf context :payload)))
             (format nil "A chaos trigger was received (~a). Should I run a stress test?" (getf p :mode))))
  :symbolic #'chaos-stress-test)
#+end_src