docs: add Contract sections + tag tests to contract items (Tier 2 — 10 files)

org/core-loop-reason.org

@@ -36,6 +36,22 @@ A plist is simultaneously:
 
 This is not a cosmetic choice. It means the reasoning pipeline can generate, modify, and execute its own communication protocol without external parsing libraries. There is no JSON encoder, no schema validator, no serialization layer between the two engines. They speak the same language because they *are* the same language.
 
+** Contract
+
+1. (cognitive-verify proposed-action context): runs all registered
+   deterministic gates sorted by priority. Returns a rejection plist
+   (~:LOG~ or ~:EVENT~) if any gate blocks the action, an
+   ~:approval-required~ event if a gate requires HITL, or the action
+   (potentially modified) if it passes.
+2. (loop-gate-reason signal): the full reason pipeline — only processes
+   ~:user-input~ and ~:chat-message~ sensors. Runs ~think~ to generate
+   a candidate, then ~cognitive-verify~ to gate it. Retries up to 3
+   times on rejection. Sets ~:status :reasoned~ on completion.
+3. (reason-gate signal): thin alias for ~loop-gate-reason~.
+4. (backend-cascade-call prompt): iterates ~*provider-cascade*~ calling
+   each backend's handler until one succeeds. Returns the LLM content
+   string, or a ~:LOG~ failure if all backends are exhausted.
+
 * Implementation
 
 ** Package Context
@@ -360,6 +376,7 @@ Verifies that the deterministic engine correctly rejects unsafe actions (like ~r
 (in-suite pipeline-reason-suite)
 
 (test test-decide-gate-safety
+  "Contract 1: cognitive-verify blocks unsafe actions with :LOG rejection."
   (clrhash passepartout::*skill-registry*)
   (passepartout::defskill :mock-safety
     :priority 50
@@ -375,7 +392,7 @@ Verifies that the deterministic engine correctly rejects unsafe actions (like ~r
     (is (eq :LOG (getf result :type)))))
 
 (test test-cognitive-verify-pass-through
-  "Safe actions should pass through cognitive-verify unchanged."
+  "Contract 1: safe actions pass through cognitive-verify unchanged."
   (clrhash passepartout::*skill-registry*)
   (passepartout::defskill :mock-passthrough
     :priority 50
@@ -389,7 +406,7 @@ Verifies that the deterministic engine correctly rejects unsafe actions (like ~r
     (is (equal candidate result))))
 
 (test test-cognitive-verify-empty-registry
-  "When no gates are registered, the action passes through unchanged."
+  "Contract 1: with no gates registered, action passes through unchanged."
   (clrhash passepartout::*skill-registry*)
   (let* ((candidate '(:type :REQUEST :payload (:action :shell :cmd "ls")))
          (signal '(:type :EVENT :payload (:sensor :user-input)))
@@ -397,7 +414,7 @@ Verifies that the deterministic engine correctly rejects unsafe actions (like ~r
     (is (equal candidate result))))
 
 (test test-cognitive-verify-approval-required
-  "A gate returning :level :approval-required should produce an approval event."
+  "Contract 1: gate returning :approval-required produces an approval event."
   (clrhash passepartout::*skill-registry*)
   (passepartout::defskill :mock-approval
     :priority 50