FEAT: Add optional skills moved from core repository

org-skill-chaos.org

@@ -0,0 +1,161 @@
+: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 Protocol 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 :org-agent)
+
+(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."
+     (org-agent: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."
+     (org-agent: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 org-agent 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