memex/system/skills/org-skill-ast-normalization.org

SKILL: AST Normalization Agent (Structural Integrity)

• Overview
• The Normalization Mandate
• Symbolic Implementation (The Logic)
  • Architectural Intent: Command Trigger
  • Architectural Intent: Neuro-Cognitive Fallback
  • Architectural Intent: Symbolic Verification (System 2)
• Registration

Overview

The AST Normalization Agent is responsible for maintaining the structural integrity of the Org-mode Abstract Syntax Tree (AST) within the Memex. It handles explicit refactoring commands and ensures that all nodes adhere to the system's strict metadata requirements.

The Normalization Mandate

1. Structural Enforcement: Every significant headline must have a unique `#+ID`.
2. Deterministic Preemption: If a deterministic structural issue is detected, the symbolic layer (System 2) MUST preempt any neural suggestions (System 1).
3. Fidelity: Refactoring must preserve the user's content while normalizing its metadata.

Symbolic Implementation (The Logic)

The logic below defines the transition from a user-initiated "organize" command to a verified, high-integrity AST transformation.

Architectural Intent: Command Trigger

This skill triggers on explicit user-driven events, specifically targeting the `organize-subtree` command.

(defun trigger-skill-ast-normalization (context)
  (let ((type (getf context :type))
        (payload (getf context :payload)))
    (and (eq type :EVENT)
         (eq (getf payload :sensor) :user-command)
         (eq (getf payload :command) :organize-subtree))))

Architectural Intent: Neuro-Cognitive Fallback

While primarily symbolic, the neural layer provides a bridge for complex requests where a simple deterministic fix isn't immediately obvious.

(defun neuro-skill-ast-normalization (context)
  (format nil "User requested subtree organization. Context - ~a. Suggest an Org-mode action. Provide concise, high-fidelity suggestions in Lisp plist format." context))

Architectural Intent: Symbolic Verification (System 2)

The core of this skill is the verification phase. It inspects the AST for missing IDs and, if found, generates a deterministic refactoring request that overrides any neural output.

(defun verify-skill-ast-normalization (proposed-action context)
  (let* ((ast (getf (getf context :payload) :ast))
         (missing-id (find-headline-missing-id ast)))
    (if missing-id
        (progn
          (format t "System 2 - Missing ID detected, preempting System 1.~%")
          `(:type :REQUEST :id ,(get-universal-time) 
            :target :emacs
            :payload (:action :refactor-subtree 
                      :target-id nil 
                      :properties (("ID" . ,(format nil "node-~a" (get-universal-time)))))))
        ;; If no deterministic action, allow System 1's proposal to pass
        proposed-action)))

Registration

(defskill :skill-ast-normalization
  :priority 100 ; High priority to preempt general skills
  :trigger #'trigger-skill-ast-normalization
  :neuro #'neuro-skill-ast-normalization
  :symbolic #'verify-skill-ast-normalization)