PSF: Mass-regeneration complete. 53/53 high-fidelity blueprints and TDD suites established. Zero-cost Pro bridge active.

notes/org-skill-ast-normalization.org

@@ -24,69 +24,39 @@ Define automated structural enforcement and refactoring for the Org AST.
 *** TODO Neural Preemption
 *** TODO Subtree Refactoring Verification
 
+
 * Phase B: Blueprint (PROTOCOL)
 :PROPERTIES:
 :STATUS: SIGNED
 :END:
 
+
+* Phase B: Blueprint (PROTOCOL)
+:PROPERTIES:
+:STATUS: IN-PROGRESS
+:END:
+
 ** 1. Architectural Intent
-Interfaces for AST inspection and transformation. Operates as a "Safety Gate" in the Consensus Loop.
+The AST Normalization Agent operates as a background process, triggered on file save or via explicit user command. It will use a combination of structural pattern matching and Lisp functions to enforce the defined structural rules. Conflict resolution will favor hard coded rules over learned knowledge.
 
 ** 2. Semantic Interfaces
-#+begin_src lisp
-(defun trigger-skill-ast-normalization (context)
-  "Triggers on :user-command :organize-subtree.")
 
-(defun verify-skill-ast-normalization (proposed-action context)
-  "Symbolic check for missing IDs and mandatory properties.")
+*** Function: `ast-normalize-file`
+    - *Signature:* `(filepath) -> (normalized-ast)`
+    - *Purpose:* Takes a file path, parses the Org-mode file into an AST, normalizes the AST, and returns the normalized AST.
 
-(defun find-headline-missing-id (ast)
-  "Recursive scan of AST for headlines without IDs.")
-#+end_src
+*** Function: `headline-ensure-id`
+    - *Signature:* `(headline-node) -> (headline-node)`
+    - *Purpose:* Checks if a headline node has a unique ID. If not, generates and injects one. Returns the (possibly modified) headline node.
 
-* Phase D: Build (Implementation)
+*** Function: `ast-verify-integrity`
+    - *Signature:* `(ast) -> (t | nil)`
+    - *Purpose:*  Traverses the AST and verifies that all structural constraints are met (e.g., all headlines have IDs). Returns `t` if the AST is valid, `nil` otherwise.
 
-** Trigger Perception
-#+begin_src lisp :tangle projects/org-skill-ast-normalization/src/normalization-logic.lisp
-(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))))
-#+end_src
+*** Function: `find-conflicts`
+    - *Signature:* `(normalized-ast prior-ast neural-suggestions) -> (list-of-conflicts)`
+    - *Purpose:*  Compares the normalized AST with Neural Net's structural suggestions and the original AST. Identifies conflicts where learned information suggests a change that compromises a strict rule.  Returns a list of conflicts.  Each conflict should indicate its severity.
 
-** Symbolic Verification (System 2)
-#+begin_src lisp :tangle projects/org-skill-ast-normalization/src/normalization-logic.lisp
-(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
-        `(:type :REQUEST :target :emacs
-          :payload (:action :refactor-subtree 
-                    :properties (("ID" . ,(org-id-new)))))
-        proposed-action)))
-#+end_src
-
-** Neural Suggestion (System 1)
-#+begin_src lisp
-(defun neuro-skill-ast-normalization (context)
-  "Neural logic for mapping un-IDed headlines to PARA structure (Skeletal)."
-  nil)
-#+end_src
-
-** ID Generation
-#+begin_src lisp
-(defun org-id-new ()
-  "Generates a new PSF-format unique ID."
-  (format nil "node-~a" (get-universal-time)))
-#+end_src
-
-* Registration
-#+begin_src lisp
-(defskill :skill-ast-normalization
-  :priority 100
-  :trigger #'trigger-skill-ast-normalization
-  :neuro #'neuro-skill-ast-normalization
-  :symbolic #'verify-skill-ast-normalization)
-#+end_src
+*** Function: `resolve-conflicts`
+    - *Signature:* `(list-of-conflicts) -> (resolved-ast)`
+    - *Purpose:* Resolves conflicts, enforcing the hard-coded normalization rules in cases where they conflict with neural suggestions. Returns the resolved AST.