docs: rename OACP to Harness Protocol and revamp protocol.org with verbose literate text

2026-04-12 18:54:00 -04:00
parent 5c7a925e4d
commit 117f3143d3
16 changed files with 111 additions and 82 deletions
--- a/skills/org-skill-protocol-validator.org
+++ b/skills/org-skill-protocol-validator.org
@@ -0,0 +1,91 @@
+:PROPERTIES:
+:ID:       org-skill-harness-protocol-validator
+:CREATED:  [2026-04-12 Sun 14:35]
+:END:
+#+TITLE: SKILL: Harness Protocol Schema Validator (Universal Literate Note)
+#+STARTUP: content
+#+FILETAGS: :protocol:harness-protocol:security:validation:psf:
+
+* Overview
+The *Harness Protocol Schema Validator* skill provides deep structural validation for all messages entering the org-agent kernel. It ensures that every property list adheres to a strict schema, preventing malformed data from causing harness-level errors.
+
+* Phase A: Demand (PRD)
+:PROPERTIES:
+:STATUS: SIGNED
+:END:
+
+** 1. Purpose
+Enforce a formal grammar for the Org-Agent Control Protocol (Harness Protocol).
+
+** 2. User Needs
+- *Type Safety:* Ensure mandatory keys (e.g., `:type`, `:payload`) are present.
+- *Range Validation:* Check that enum values (e.g., `:REQUEST`, `:EVENT`) are valid.
+- *Structural Integrity:* Validate nested payloads based on the message type.
+
+** 3. Success Criteria
+- [ ] Block any message that does not contain a valid `:type`.
+- [ ] Block `:REQUEST` messages that lack a `:target`.
+- [ ] Block `:EVENT` messages that lack a `:payload` with an `:action` or `:sensor`.
+
+* Phase B: Blueprint (PROTOCOL)
+:PROPERTIES:
+:STATUS: SIGNED
+:END:
+
+** 1. Architectural Intent
+Decouple protocol parsing (framing/unframing) from semantic validation.
+
+** 2. Semantic Interfaces
+
+#+begin_src lisp
+(defun validate-harness-protocol-schema (msg)
+  "Returns T if the message is valid, NIL (and signals error) otherwise.")
+#+end_src
+
+* Phase D: Build (Implementation)
+
+** Schema Enforcement
+#+begin_src lisp :tangle ../src/protocol-validator.lisp
+(in-package :org-agent)
+
+(defun validate-harness-protocol-schema (msg)
+  "Strict structural validation for incoming Harness Protocol messages."
+  (unless (listp msg)
+    (error "Harness Protocol Schema Error: Message must be a property list (got ~s)" (type-of msg)))
+  
+  (let ((type (getf msg :type)))
+    (unless (member type '(:REQUEST :EVENT :RESPONSE :LOG))
+      (error "Harness Protocol Schema Error: Invalid message type '~a'" type))
+    
+    (case type
+      (:REQUEST 
+       (unless (getf msg :target)
+         (error "Harness Protocol Schema Error: REQUEST missing mandatory :target"))
+       (unless (getf msg :payload)
+         (error "Harness Protocol Schema Error: REQUEST missing mandatory :payload")))
+      
+      (:EVENT
+       (let ((payload (getf msg :payload)))
+         (unless (and payload (listp payload))
+           (error "Harness Protocol Schema Error: EVENT missing or invalid :payload"))
+         (unless (or (getf payload :action) (getf payload :sensor))
+           (error "Harness Protocol Schema Error: EVENT payload must contain :action or :sensor"))))
+      
+      (:RESPONSE
+       (unless (getf msg :payload)
+         (error "Harness Protocol Schema Error: RESPONSE missing mandatory :payload"))))
+    
+    t))
+#+end_src
+
+* Registration
+#+begin_src lisp :tangle ../src/protocol-validator.lisp
+(defskill :skill-harness-protocol-validator
+  :priority 95
+  :trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:protocol-received)))
+  :neuro nil
+  :symbolic (lambda (action ctx)
+              (declare (ignore ctx))
+              (validate-harness-protocol-schema action)
+              action))
+#+end_src