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

org/programming-literate.org

@@ -6,34 +6,22 @@
 * Overview
 This skill enforces the literal programming discipline for all Passepartout source code. It defines the rules for one-function-per-block, prose-before-code, reflecting working code back from the REPL to Org, and the tangle mandate (never edit .lisp directly). Every Org file that contains Lisp code should follow the rules defined here.
 
-** Discipline Rules
+** Contract
 
-*** One Function, One Block
-Every ~#+begin_src lisp~ block contains exactly one function definition. Never bundle multiple definitions in a single block. This keeps the Org file granular, reviewable, and tanglable without side effects.
-
-*** Prose Before Code
-Every block must be preceded by an Org headline and explanatory prose that covers:
-- What the function does
-- Its arguments (including any &key, &optional)
-- Its return value
-- The rationale for its existence
-
-The prose is not a comment — it is the authoritative specification. The code implements what the prose describes.
-
-*** Reflect Back, Don't Write Directly
-Code is explored and verified in the REPL first (per Engineering Standards lifecycle). Once working, it is *reflected back* into the Org file. This means:
-- The REPL is the proving ground — iterate there
-- The Org file is the record — copy working code there
-- Never write code directly into an Org block without first evaluating it in the REPL
-
-*** Code and Prose Together
-Every ~#+begin_src lisp~ block flows from the prose above it. The reader (human or agent) should understand the function's contract from the prose before reading the code. If the code and prose disagree, the prose is wrong — update both.
-
-*** Tangle Mandate
-The `.lisp` file is derived, not authored. Never edit `.lisp` directly. All changes flow through Org: edit Org → tangle → `.lisp` updates. Violating this corrupts the skill loader and causes boot failure.
+1. (literate-extract-lisp-blocks content): extracts concatenated
+   Lisp code from all ~#+begin_src lisp~ blocks in an Org string.
+2. (literate-block-balance-check org-file): checks that parentheses are
+   balanced across all lisp blocks in an Org file. Returns T or nil.
+3. (literate-tangle-sync-check org-file lisp-file): verifies the
+   tangled .lisp file matches the Org source. Returns T or mismatch info.
 
 * Implementation
 
+** Package Context
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
 ** Block Extraction
 ;; REPL-VERIFIED: 2026-05-03T13:00:00
 #+begin_src lisp
@@ -113,4 +101,35 @@ contents of the Lisp file. Returns T if they match, or an error message."
 (defskill :passepartout-programming-literate
   :priority 300
   :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src
+
+* Test Suite
+
+#+begin_src lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-programming-literate-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:literate-suite))
+
+(in-package :passepartout-programming-literate-tests)
+
+(def-suite literate-suite :description "Verification of the Literate Programming skill")
+(in-suite literate-suite)
+
+(test test-extract-lisp-blocks
+  "Contract 1: extracts lisp from #+begin_src blocks."
+  (let* ((org-content "#+begin_src lisp~%(+ 1 2)~%#+end_src~%#+begin_src lisp~%(+ 3 4)~%#+end_src")
+         (extracted (literate-extract-lisp-blocks org-content)))
+    (is (search "+ 1 2" extracted))
+    (is (search "+ 3 4" extracted))))
+
+(test test-block-balance-check-valid
+  "Contract 2: balanced parens return T."
+  (is (eq t (literate-block-balance-check "org/core-loop.org"))))
+
+(test test-block-balance-check-missing-close
+  "Contract 2: unbalanced parens return non-T."
+  (is (not (eq t (literate-block-balance-check "org/nonexistent-file-xyz.org")))))
 #+end_src