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

org/system-diagnostics.org

@@ -14,10 +14,15 @@ The Doctor transforms opaque startup failures into actionable engineering report
 ** Detection Invariant
 Binary detection must use shell probing (`which`) to account for varying `$PATH` inheritance between interactive and headless sessions.
 
-* Phase B: Protocol (Success Criteria)
-- Dependency check passes when all required binaries are found
-- Environment check passes when XDG directories exist and are accessible
-- LLM check passes when at least one provider is configured or Ollama is running locally
+* Phase B: Contract
+
+1. (diagnostics-dependencies-check): probes PATH for every binary in
+   ~*diagnostics-binaries*~. Returns T if all found, NIL if any missing.
+   Side-effect: populates ~*doctor-missing-deps*~.
+2. (diagnostics-env-check): validates XDG directories exist. Returns T
+   if all critical dirs present, NIL otherwise.
+3. (diagnostics-run-all &key auto-install): orchestrates 1-3. Returns
+   a plist with ~:deps~, ~:env~, ~:llm~ keys. Respects ~:auto-install nil~.
 
 * Phase C: Implementation (Build)
 
@@ -257,12 +262,12 @@ The doctor checks all supported LLM providers and detects local Ollama instances
 (in-suite diagnostics-suite)
 
 (test test-diagnostics-dependency-fail
-  "Verify that missing binaries are correctly identified as failures."
+  "Contract 1: missing binaries cause diagnostics-dependencies-check to return nil."
   (let ((passepartout::*diagnostics-binaries* '("non-existent-binary-123")))
     (is (null (diagnostics-dependencies-check)))))
 
 (test test-diagnostics-env-fail
-  "Verify that an invalid MEMEX_DIR triggers a critical failure."
+  "Contract 2: invalid MEMEX_DIR causes diagnostics-env-check to return nil."
   (let ((old-m (uiop:getenv "MEMEX_DIR"))
         (old-d (uiop:getenv "PASSEPARTOUT_DATA_DIR")))
     (unwind-protect
@@ -273,7 +278,7 @@ The doctor checks all supported LLM providers and detects local Ollama instances
       (setf (uiop:getenv "PASSEPARTOUT_DATA_DIR") (or old-d "")))))
 
 (test test-diagnostics-dependency-success
-  "When all binaries exist, diagnostics should pass."
+  "Contract 1: all binaries present returns T."
   (let ((passepartout::*diagnostics-binaries* '("ls")))
     (is (eq t (diagnostics-dependencies-check)))))
 #+end_src