:PROPERTIES:
:ID:       literate-programming-skill-2026
:CREATED:  [2026-04-25 Sat]
:END:
#+TITLE: SKILL: Literate Programming
#+STARTUP: content
#+FILETAGS: :literate:org:tangle:validation:emacs:

* Overview

This skill enforces the Literate Programming discipline for OpenCortex. All system logic lives in Org files, not raw Lisp files. Generated code is derived, not authored.

A skill org file is not "documentation with code examples." It IS the code. The generated `.lisp` files are build artifacts.

* The Invariants

** 1. One Function, One Block

Every Lisp function, macro, variable, or `defskill` registration MUST live in its own dedicated `#+begin_src lisp` block. No bundling multiple definitions into a single block.

Rationale: Block-level evaluation (`C-c C-c`) validates one semantic unit at a time. Bundling multiple functions into one block makes debugging, diffing, and reasoning about scope impossible.

** 2. Org-Mode Evaluation Gate

After writing or modifying any `#+begin_src lisp` block, evaluate it with `C-c C-c` (org-babel-execute-src-block).

If evaluation fails, fix the block before proceeding. Do not commit a block that does not evaluate cleanly.

Rationale: `C-c C-c` catches syntax errors immediately, at the granularity of a single function.

** 3. Pre-Tangle Structural Check

Before tangling (`C-c C-v t` or `org-babel-tangle-file`), run a structural syntax check:

Every block destined for a `.lisp` file must have balanced parentheses when extracted in isolation.

The skill provides `literate-check-block-balance` for this purpose.

Rationale: The tangle process concatenates blocks. An unbalanced block corrupts the generated file even if the Org file renders fine.

** 4. No Direct `.lisp` Edits

You are forbidden from editing generated `.lisp` files directly. All changes flow through the Org file.

If you edit `.lisp` directly, the change will be overwritten on next tangle and the diff will be unreviewable.

** 5. Code and Prose Together

Every `#+begin_src lisp` block MUST be preceded by explanatory prose. The prose answers:
- What does this function do?
- What are its arguments and return value?
- Why does it exist? (What problem does it solve?)

Code without surrounding prose is a bug report waiting to happen.

* Implementation

** Block Balance Checker

#+begin_src lisp :tangle ../library/gen/org-skill-literate-programming.lisp
(defun literate-check-block-balance (code-string)
  "Returns T if CODE-STRING has balanced parentheses, brackets, and strings.

   Ignores comments (after ;) and tracks string contents to avoid
   counting parens inside string literals."
  (let ((depth 0) (in-string nil) (escaped nil))
    (dotimes (i (length code-string) (zerop depth))
      (let ((ch (char code-string i)))
        (cond
          ;; Escape handling (affects next char only)
          (escaped (setf escaped nil))
          ((char= ch #\\) (setf escaped t))
          ;; String boundaries
          (in-string (when (char= ch #\") (setf in-string nil)))
          ((char= ch #\") (setf in-string t))
          ;; Comment boundaries (skip to end of line)
          ((char= ch #\;)
           (loop while (and (< i (1- (length code-string)))
                           (not (char= (char code-string (1+ i)) #\Newline)))
                 do (incf i)))
          ;; Structural parens
          ((member ch '(#\( #\[)) (incf depth))
          ((member ch '(#\) #\]))
           (if (<= depth 0)
               (return-from literate-check-block-balance
                 (values nil (format nil "Unexpected close paren at position ~a" i)))
               (decf depth))))))))
#+end_src

** File-Level Balance Audit

#+begin_src lisp :tangle ../library/gen/org-skill-literate-programming.lisp
(defun literate-audit-org-file (filepath)
  "Audits all tangled lisp blocks in an Org file for structural balance.

   Returns a list of imbalance reports, or NIL if all blocks are balanced."
  (let* ((content (with-open-file (s filepath)
                    (let ((seq (make-string (file-length s))))
                      (read-sequence seq s)
                      seq)))
         (idx 0)
         (reports nil)
         (block-num 0))
    (loop
      (let ((pos (search "#+begin_src lisp" content :start2 idx :test #'string-equal)))
        (when (null pos) (return (nreverse reports)))
        (let* ((eol (or (position #\Newline content :start pos) (length content)))
               (header (subseq content pos eol))
               (header-lower (string-downcase header))
               (tangle-p (and (search ".lisp" header-lower)
                             (not (search ":tangle no" header-lower)))))
          (if (not tangle-p)
              (setf idx (1+ eol))
              (let ((end-pos (search "#+end_src" content :start2 eol :test #'string-equal)))
                (if (null end-pos)
                    (progn
                      (push (list :block (incf block-num) :status :missing-end-src) reports)
                      (return (nreverse reports)))
                    (let ((raw-block (subseq content (1+ eol) end-pos))
                          (clean-lines nil))
                      ;; Strip PROPERTIES drawers and :END: markers
                      (dolist (line (uiop:split-string raw-block :separator '(#\Newline)))
                        (let ((trimmed (string-trim '(#\Space #\Tab #\Return) line)))
                          (when (and (plusp (length trimmed))
                                     (not (string= (subseq trimmed 0 (min 12 (length trimmed))) ":PROPERTIES:"))
                                     (not (string= (subseq trimmed 0 (min 5 (length trimmed))) ":END:")))
                            (push line clean-lines))))
                      (let ((code (format nil "~{~a~^~%~}" (nreverse clean-lines))))
                        (multiple-value-bind (ok reason) (literate-check-block-balance code)
                          (unless ok
                            (push (list :block (incf block-num)
                                       :status :unbalanced
                                       :reason reason
                                       :code code)
                                  reports))))
                      (setf idx (+ end-pos 9))))))))))
#+end_src

** Skill Registration

#+begin_src lisp :tangle ../library/gen/org-skill-literate-programming.lisp
(defskill :skill-literate-programming
  :priority 1100
  :trigger (lambda (ctx)
             (declare (ignore ctx))
             ;; Trigger on any skill-related action
             t)
  :probabilistic nil
  :deterministic (lambda (action context)
                   (declare (ignore context))
                   ;; Audit the action's target file if it's an org skill
                   (when (and (listp action)
                              (stringp (getf action :file)))
                     (let ((file (getf action :file)))
                       (when (and (search ".org" file)
                                  (search "skill" file :test #'string-equal))
                         (let ((issues (literate-audit-org-file file)))
                           (when issues
                             (harness-log "LITERATE PROGRAMMING: Structural issues found in ~a: ~a"
                                          file issues))))))
                   action))
#+end_src

* See Also
- [[file:org-skill-engineering-standards.org][Engineering Standards Skill]] - Lifecycle mandates
- [[file:org-skill-policy.org][Policy Skill]] - Constitutional constraints