Add org-skill-literate-programming+engineering-standards skills

- Add org-skill-literate-programming: enforce Org discipline
  - One function per block, pre-tangle check, .lisp is derived
- Extend org-skill-engineering-standards with Phase 0-5 lifecycle
  - Test-first design, three chaos tiers
  - Literate programming rules, decision audit trail

skills/org-skill-literate-programming.org

@@ -0,0 +1,166 @@
+: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