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

org/programming-org.org

@@ -6,6 +6,18 @@
 * Overview
 Structural manipulation tools for Org-mode files. This skill handles reading, writing, and modifying Org files at the AST level: finding headlines by ID or title, setting properties and TODO states, adding new headlines, generating UUIDs, and converting ASTs back to Org text. It also implements the privacy filter — when reading an Org file, it strips headlines tagged with ~@personal~ (or any tag in ~bouncer-privacy-tags~) and rejects files with matching ~#+FILETAGS:~.
 
+** Contract
+
+1. (org-id-generate): returns a new UUID string.
+2. (org-id-format id): ensures the ID has an "id:" prefix.
+3. (org-property-set ast target-id property value): recursively sets a
+   property on a headline matching target-id. Returns T on success.
+4. (org-todo-set ast target-id status): sets TODO status via
+   org-property-set.
+5. (org-headline-add ast parent-id title): adds a new child headline.
+6. (org-find-headline-by-id ast id): returns the subtree for a matching
+   headline ID.
+
 * Implementation
 
 ** Package Context
@@ -352,16 +364,19 @@ Verification of the structural manipulation for Org-mode files and their AST rep
 (in-suite utils-org-suite)
 
 (test id-generation
+  "Contract 1: org-id-generate returns unique UUID strings."
   (let ((id1 (org-id-generate))
         (id2 (org-id-generate)))
     (is (plusp (length id1)))
     (is (not (string= id1 id2)))))
 
 (test id-format
+  "Contract 2: org-id-format ensures 'id:' prefix."
   (let ((formatted (org-id-format "abc12345")))
     (is (search "id:" formatted))))
 
 (test property-setter
+  "Contract 3: org-property-set modifies a property on a headline."
   (let ((ast (list :type :HEADLINE
                   :properties (list :ID "id:test123" :TITLE "Test")
                   :contents nil)))
@@ -369,6 +384,7 @@ Verification of the structural manipulation for Org-mode files and their AST rep
     (is (string= (getf (getf ast :properties) :STATUS) "ACTIVE"))))
 
 (test todo-setter
+  "Contract 4: org-todo-set changes TODO state via org-property-set."
   (let ((ast (list :type :HEADLINE
                   :properties (list :ID "id:todo001" :TITLE "Task")
                   :contents nil)))