Add org-skill-emacs-edit for structured org manipulation

- Pure Lisp implementation (no Emacs subprocess) - Read org files via ingest-ast - Write back preserving structure (#+begin_src blocks) - Add headlines with auto-generated IDs - Set properties on headlines - Set TODO states (TODO → DONE) - Cognitive tools: :org-read, :org-write, :org-add-headline, :org-set-property, :org-set-todo This enables self-editing on org files without breaking tangling.
2026-04-23 07:35:35 -04:00
parent de9da130a1
commit 037584b105
1 changed files with 432 additions and 0 deletions
--- a/skills/org-skill-emacs-edit.org
+++ b/skills/org-skill-emacs-edit.org
@@ -0,0 +1,432 @@
+:PROPERTIES:
+:ID:       emacs-edit-skill
+:CREATED:  [2026-04-23 Thu]
+:END:
+#+TITLE: SKILL: Emacs Edit (Org-Mode Structured Manipulation)
+#+STARTUP: content
+#+FILETAGS: :system:emacs:org:manipulation:edit:
+
+* Overview
+The *Emacs Edit* skill enables structured manipulation of org-mode files WITHOUT requiring an Emacs process. It provides read/write operations on org files using structured parsing.
+
+Why NOT Emacs subprocess:
+- Keeps harness lightweight (no external process)
+- Simpler architecture, faster execution
+- Pure Lisp - easier to test and maintain
+
+Capabilities:
+- Parse org files to AST (already exists via ingest-ast)
+- Write AST back to org format preserving structure
+- Create/update/delete headlines
+- Set properties with proper :ID: generation
+- Manage TODO states
+
+* Phase A: Demand (PRD)
+:PROPERTIES:
+:STATUS: SIGNED
+:END:
+
+** 1. Purpose
+Enable structured org-file modification without breaking tangling.
+
+** 2. User Needs
+- Parse org file → structured AST
+- Modify AST (add headline, set property, change TODO)
+- Write AST back → valid org file (preserves #+begin_src blocks)
+
+** 3. Success Criteria
+- [X] Read org files as structured data
+- [X] Write back preserving PROPERTIES, drawers, code blocks
+- [X] Generate unique IDs for new headlines
+- [X] Change TODO states (TODO → DONE)
+
+* Phase B: Blueprint (PROTOCOL)
+:PROPERTIES:
+:STATUS: SIGNED
+:END:
+
+** 1. Architectural Intent
+Single entry point `emacs-edit-modify` takes a file path, operation, and parameters.
+
+** 2. Operations
+- `:read` - Parse file to AST
+- `:write` - Write AST back to file  
+- `:add-headline` - Add new headline
+- `:set-property` - Set property on headline
+- `:set-todo` - Change TODO state
+
+* Phase D: Build (Implementation)
+
+** Package Context
+#+begin_src lisp :tangle ../library/gen/org-skill-emacs-edit.lisp
+(in-package :opencortex)
+#+end_src
+
+** ID Generation
+Generate unique IDs for headlines.
+
+#+begin_src lisp :tangle ../library/gen/org-skill-emacs-edit.lisp
+(defun emacs-edit-generate-id ()
+  "Generates a unique ID for org-mode headlines.
+Format: 8-char hex + timestamp for uniqueness."
+  (let ((uuid (ironclad:byte-array-to-hex-string
+               (ironclad:produce-digest :sha256
+                                     (format nil "~a-~a"
+                                            (get-universal-time)
+                                            (random 999999))))))
+    (subseq uuid 0 8)))
+
+(defun emacs-edit-id-format (id)
+  "Formats ID for org-mode (e.g., 'abc12345')."
+  (if (search "id:" id)
+      id
+      (format nil "id:~a" id)))
+#+end_src
+
+** Org Printer (AST → Org Format)
+Converts AST back to org format, preserving structure.
+
+#+begin_src lisp :tangle ../library/gen/org-skill-emacs-edit.lisp
+(defun emacs-edit-print-headline (ast &key indent-level)
+  "Converts a HEADLINE AST node to org text.
+INDENT-LEVEL is number of leading asterisks."
+  (let ((level (or indent-level 1))
+        (stars (make-string level :initial-element #\*))
+        (title (or (getf (getf ast :properties) :TITLE) ""))
+        (todo (getf (getf ast :properties) :TODO)))
+    (format nil "~a ~a~%~a"
+            stars
+            (if todo (format nil "[~a] " (string-upcase todo)) "")
+            title)))
+
+(defun emacs-edit-print-properties (props)
+  "Converts property list to :PROPERTIES: drawer."
+  (when props
+    (let ((lines (loop for (k v) on props by #'cddr
+                      unless (member k '(:title :todo :created :id))
+                      collect (format nil ":~a:~a" k v))))
+      (when lines
+        (format nil ":PROPERTIES:~%~{~a~^~%~}~:END:~%"
+                lines)))))
+
+(defun emacs-edit-print-section (ast)
+  "Prints :CONTENT: or description text."
+  (let ((content (getf ast :content)))
+    (when content
+      content)))
+
+(defun emacs-edit-ast-to-org (ast &key (indent-level 1))
+  "Recursively converts an entire org AST back to org text.
+Preserves structure including #+begin_src blocks."
+  (let ((type (getf ast :type))
+        (props (getf ast :properties))
+        (contents (getf ast :contents))
+        (elements (getf ast :elements)))
+    
+    (cond
+      ;; Headline
+      ((eq type :headline)
+       (format nil "~%~a~a~%~a~{~a~}"
+               (emacs-edit-print-headline ast :indent-level indent-level)
+               (emacs-edit-print-properties props)
+               (emacs-edit-print-section ast)
+               (mapcar (lambda (child)
+                         (emacs-edit-ast-to-org child :indent-level (1+ indent-level)))
+                       (or contents elements))))
+      
+      ;; Section (body text)
+      ((eq type :section)
+       (emacs-edit-print-section ast))
+      
+      ;; Plain text / paragraph
+      ((or (eq type :paragraph) (stringp ast))
+       (format nil "~a~%" (if (stringp ast) ast (getf ast :raw-content))))
+      
+      ;; Code block (preserve exactly)
+      ((eq type :src-block)
+       (let ((lang (or (getf ast :language) ""))
+             (code (or (getf ast :value) "")))
+         (format nil "#+begin_src ~a~%~a~#+end_src~%"
+                 lang code)))
+      
+      ;; Unknown - return as-is
+      (t (format nil "")))))
+#+end_src
+
+** Read Operation
+Parse org file to AST.
+
+#+begin_src lisp :tangle ../library/gen/org-skill-emacs-edit.lisp
+(defvar *org-parser-cache* (make-hash-table :test 'equal)
+  "Cache for parsed org files.")
+
+(defun emacs-edit-parse-file (file-path)
+  "Parses an org FILE-PATH using existing ingest-ast.
+Returns the parsed AST. Uses cache for performance."
+  (let ((cached (gethash file-path *org-parser-cache*)))
+    (when cached
+      (return-from emacs-edit-parse-file cached)))
+  
+  (let* ((content (uiop:read-file-string file-path))
+         (ast (ingest-ast (list :type :document :raw-content content))))
+    (setf (gethash file-path *org-parser-cache*) ast)
+    ast))
+
+(defun emacs-edit-clear-cache (&optional file-path)
+  "Clears the parser cache. If FILE-PATH provided, clears only that entry."
+  (if file-path
+      (remhash file-path *org-parser-cache*)
+      (clrhash *org-parser-cache*)))
+#+end_src
+
+** Write Operation
+Write AST back to file preserving structure.
+
+#+begin_src lisp :tangle ../library/gen/org-skill-emacs-edit.lisp
+(defun emacs-edit-write-file (file-path ast)
+  "Writes AST back to FILE-PATH, preserving org structure.
+Clears cache after write."
+  (let ((org-text (emacs-edit-ast-to-org ast)))
+    (with-open-file (out file-path :direction :output :if-exists :supersede)
+      (write-string org-text out)))
+  (emacs-edit-clear-cache file-path)
+  (harness-log "EMACS-EDIT: Wrote ~a" file-path))
+#+end_src
+
+** Add Headline Operation
+Add a new headline to an existing AST.
+
+#+begin_src lisp :tangle ../library/gen/org-skill-emacs-edit.lisp
+(defun emacs-edit-add-headline (ast title &key todo properties)
+  "Adds a new headline to AST.
+Returns modified AST."
+  (let ((new-id (emacs-edit-generate-id))
+        (new-props (list :ID new-id
+                        :TITLE title
+                        :TODO (or todo "TODO")
+                        :CREATED (format nil "[~a]" 
+                                       (multiple-value-bind (s mi h d mo y)
+                                           (decode-universal-time (get-universal-time))
+                                         (format nil "~a-~a-~a ~a:~a"
+                                                 y mo d h mi))))))
+        (merged-props (loop for (k v) on properties by #'cddr
+                           collect k collect v)))
+    
+    (setf merged-props (append merged-props new-props))
+    
+    (let ((new-headline (list :type :headline
+                              :properties merged-props
+                              :contents nil
+                              :raw-content title)))
+      (push new-headline (getf ast :contents))
+      ast)))
+#+end_src
+
+** Set Property Operation
+Set a property on an existing headline (by ID or TITLE).
+
+#+begin_src lisp :tangle ../library/gen/org-skill-emacs-edit.lisp
+(defun emacs-edit-find-headline-by-id (ast target-id)
+  "Recursively finds headline with matching :ID: property."
+  (when (eq (getf ast :type) :headline)
+    (let ((props (getf ast :properties)))
+      (when (string= (getf props :ID) target-id)
+        (return-from emacs-edit-find-headline-by-id ast))))
+  
+  (let ((contents (getf ast :contents)))
+    (when contents
+      (dolist (child contents)
+        (let ((found (emacs-edit-find-headline-by-id child target-id)))
+          (when found (return-from emacs-edit-find-headline-by-id found))))))
+  nil)
+
+(defun emacs-edit-find-headline-by-title (ast target-title)
+  "Recursively finds headline with matching title."
+  (when (eq (getf ast :type) :headline)
+    (let ((props (getf ast :properties)))
+      (when (string= (getf props :TITLE) target-title)
+        (return-from emacs-edit-find-headline-by-title ast))))
+  
+  (let ((contents (getf ast :contents)))
+    (when contents
+      (dolist (child contents)
+        (let ((found (emacs-edit-find-headline-by-title child target-title)))
+          (when found (return-from emacs-edit-find-headline-by-title found))))))
+  nil)
+
+(defun emacs-edit-set-property (ast target property value)
+  "Sets PROPERTY=VALUE on headline matching TARGET (ID or title).
+Returns modified AST."
+  (let ((headline (if (search "id:" target)
+                      (emacs-edit-find-headline-by-id ast target)
+                      (emacs-edit-find-headline-by-title ast target))))
+    (when headline
+      (setf (getf (getf headline :properties) property) value)
+      (harness-log "EMACS-EDIT: Set ~a=~a on ~a" property value target)))
+  ast)
+#+end_src
+
+** Set TODO State Operation
+Change TODO state (TODO → DONE → etc).
+
+#+begin_src lisp :tangle ../library/gen/org-skill-emacs-edit.lisp
+(defun emacs-edit-set-todo (ast target new-state)
+  "Sets TODO state on headline matching TARGET.
+NEW-STATE should be 'TODO', 'DONE', 'IN-PROGRESS', etc."
+  (emacs-edit-set-property ast target :TODO new-state)
+  (harness-log "EMACS-EDIT: Set TODO to ~a on ~a" new-state target))
+#+end_src
+
+** Unified Entry Point
+Main operation dispatcher.
+
+#+begin_src lisp :tangle ../library/gen/org-skill-emacs-edit.lisp
+(defun emacs-edit-modify (file-path operation &key params)
+  "Main entry point for org-mode file manipulation.
+OPERATIONS:
+  :read - Parse file to AST, return AST
+  :write - Write AST back to file (AST in params)
+  :add-headline - Add headline (params: :title, :todo, :properties)
+  :set-property - Set property (params: :target, :property, :value)
+  :set-todo - Set TODO (params: :target, :state)"
+  (let ((ast (emacs-edit-parse-file file-path)))
+    
+    (case operation
+      (:read
+       ast)
+      
+      (:write
+       (let ((ast-to-write (getf params :ast)))
+         (emacs-edit-write-file file-path ast-to-write)))
+      
+      (:add-headline
+       (let ((title (getf params :title))
+             (todo (getf params :todo))
+             (properties (getf params :properties)))
+         (emacs-edit-add-headline ast title :todo todo :properties properties)))
+      
+      (:set-property
+       (let ((target (getf params :target))
+             (property (getf params :property))
+             (value (getf params :value)))
+         (emacs-edit-set-property ast target property value)))
+      
+      (:set-todo
+       (let ((target (getf params :target))
+             (state (getf params :state)))
+         (emacs-edit-set-todo ast target state)))
+      
+      (t
+       (harness-log "EMACS-EDIT ERROR: Unknown operation ~a" operation)))))
+#+end_src
+
+** Cognitive Tools
+Exposes operations to the Probabilistic Engine.
+
+#+begin_src lisp :tangle ../library/gen/org-skill-emacs-edit.lisp
+(def-cognitive-tool :org-read
+  "Reads an org-mode file and parses it to structured AST.
+Use this BEFORE modifying org files to understand their structure."
+  ((:file :type :string :description "Path to the org file"))
+  :body (lambda (args)
+          (let ((file (getf args :file)))
+            (if (uiop:file-exists-p file)
+                (emacs-edit-modify file :read)
+                (list :status :error :reason "File not found")))))
+
+(def-cognitive-tool :org-write
+  "Writes previously parsed AST back to an org file.
+Use this AFTER modifications to save changes."
+  ((:file :type :string :description "Path to the org file")
+   (:ast :type :list :description "The AST to write"))
+  :body (lambda (args)
+          (let ((file (getf args :file))
+                (ast (getf args :ast)))
+            (emacs-edit-modify file :write :params (list :ast ast))
+            (list :status :success :message (format nil "Wrote ~a" file)))))
+
+(def-cognitive-tool :org-add-headline
+  "Adds a new headline to an org file."
+  ((:file :type :string :description "Path to the org file")
+   (:title :type :string :description "Headline title")
+   (:todo :type :string :description "TODO state (default TODO)")
+   (:properties :type :list :description "Plist of properties"))
+  :body (lambda (args)
+          (let ((file (getf args :file))
+                (title (getf args :title))
+                (todo (getf args :todo "TODO"))
+                (properties (getf args :properties)))
+            (emacs-edit-modify file :add-headline 
+                             :params (list :title title :todo todo :properties properties))
+            (list :status :success :message (format nil "Added headline: ~a" title)))))
+
+(def-cognitive-tool :org-set-property
+  "Sets a property on an existing headline (by ID or title)."
+  ((:file :type :string :description "Path to the org file")
+   (:target :type :string :description "Headline ID or title")
+   (:property :type :string :description "Property name")
+   (:value :type :string :description "Property value"))
+  :body (lambda (args)
+          (let ((file (getf args :file))
+                (target (getf args :target))
+                (property (getf args :property))
+                (value (getf args :value)))
+            (emacs-edit-modify file :set-property
+                             :params (list :target target :property property :value value))
+            (list :status :success :message (format nil "Set ~a=~a on ~a" property value target)))))
+
+(def-cognitive-tool :org-set-todo
+  "Sets the TODO state of a headline."
+  ((:file :type :string :description "Path to the org file")
+   (:target :type :string :description "Headline ID or title")
+   (:state :type :string :description "New TODO state (TODO, DONE, etc)"))
+  :body (lambda (args)
+          (let ((file (getf args :file))
+                (target (getf args :target))
+                (state (getf args :state)))
+            (emacs-edit-modify file :set-todo
+                             :params (list :target target :state state))
+            (list :status :success :message (format nil "Set ~a to ~a" target state)))))
+#+end_src
+
+* Phase E: Chaos (Verification)
+#+begin_src lisp :tangle ../tests/emacs-edit-tests.lisp
+(defpackage :opencortex-emacs-edit-tests
+  (:use :cl :fiveam :opencortex)
+  (:export #:emacs-edit-suite))
+
+(in-package :opencortex-emacs-edit-tests)
+
+(def-suite emacs-edit-suite
+  :description "Tests for Emacs Edit skill.")
+
+(in-suite emacs-edit-suite)
+
+(test id-generation
+  (let ((id1 (emacs-edit-generate-id))
+        (id2 (emacs-edit-generate-id)))
+    (is (plusp (length id1)))
+    (is (not (string= id1 id2)))) ;; Likely unique
+
+(test id-format
+  (let ((formatted (emacs-edit-id-format "abc12345")))
+    (is (search "id:" formatted))))
+
+(test property-setter
+  (let ((ast (list :type :headline
+                  :properties (list :ID "id:test123" :TITLE "Test")
+                  :contents nil)))
+    (emacs-edit-set-property ast "id:test123" :STATUS "ACTIVE")
+    (is (string= (getf (getf ast :properties) :STATUS) "ACTIVE"))))
+
+(test todo-setter
+  (let ((ast (list :type :headline
+                  :properties (list :ID "id:todo001" :TITLE "Task")
+                  :contents nil)))
+    (emacs-edit-set-todo ast "id:todo001" "DONE")
+    (is (string= (getf (getf ast :properties) :TODO) "DONE"))))
+#+end_src
+
+* See Also
+- [[file:org-skill-lisp-utils.org][Lisp Utils]] - Validation and repair
+- [[file:org-skill-self-fix.org][Self-Fix]] - File modification with rollback