tier3: contracts + tests for 12 remaining modules (all 39 files now have Contracts)

org/system-archivist.org

@@ -14,8 +14,26 @@ events, performing two core functions:
 - Gardener: Scans the Memex for structural issues — broken =[[file:...]]= links
   and orphaned =memory-object= entries — flagging them for human review.
 
+** Contract
+
+1. (archivist-extract-headlines content): parses Org content into a
+   list of headline structures, each with ~:title~, ~:body~, ~:tags~.
+2. (archivist-headline-to-filename title): sanitizes a headline title
+   into a valid filename — lowercased, special chars replaced.
+3. (archivist-create-note headline notes-dir source): writes a
+   Zettelkasten note to disk with frontmatter and backlinks.
+4. (archivist-scribe-distill): heartbeat-driven — reads recent log
+   entries from ~*history-store*~ and creates structured notes.
+5. (archivist-gardener-scan): heartbeat-driven — scans for broken
+   file links and orphaned memory objects.
+
 * Implementation
 
+** Package Context
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
 ** Archivist State
 
 ;; REPL-VERIFIED: 2026-05-03T13:00:00
@@ -318,4 +336,33 @@ and dispatches as needed. Called by the deterministic gate."
   :priority 100
   :trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :heartbeat))
   :deterministic #'archivist-run)
+#+end_src
+
+* Test Suite
+
+#+begin_src lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-system-archivist-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:archivist-suite))
+
+(in-package :passepartout-system-archivist-tests)
+
+(def-suite archivist-suite :description "Verification of the Archivist skill")
+(in-suite archivist-suite)
+
+(test test-extract-headlines
+  "Contract 1: archivist-extract-headlines parses Org content."
+  (let* ((content "* My Headline :tag1:tag2:~%Body text here~%* Another Headline")
+         (headlines (archivist-extract-headlines content)))
+    (is (listp headlines))
+    (is (>= (length headlines) 1))))
+
+(test test-headline-to-filename
+  "Contract 2: archivist-headline-to-filename sanitizes titles."
+  (let ((filename (archivist-headline-to-filename "My Project: Overview")))
+    (is (search "my_project_overview" filename :test #'char-equal))
+    (is (not (search ":" filename)))))
 #+end_src