memex/notes/org-skill-ast-normalization.org

SKILL: AST Normalization Agent (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • ID Injection
    • Neural Preemption
    • Subtree Refactoring Verification
• Phase B: Blueprint (PROTOCOL)
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
    • Function: `ast-normalize-file`
    • Function: `headline-ensure-id`
    • Function: `ast-verify-integrity`
    • Function: `find-conflicts`
    • Function: `resolve-conflicts`

Overview

The AST Normalization Agent maintains the structural integrity of the Org-mode Abstract Syntax Tree. It ensures all nodes adhere to strict metadata requirements and handles deterministic refactoring.

Phase A: Demand (PRD)

1. Purpose

Define automated structural enforcement and refactoring for the Org AST.

2. User Needs

• Structural Enforcement: Mandatory unique IDs for all headlines.
• Deterministic Preemption: Symbolic verification must override neural suggestions if errors exist.
• Fidelity: Preservation of content during metadata normalization.

3. Success Criteria

TODO ID Injection

TODO Neural Preemption

TODO Subtree Refactoring Verification

Phase B: Blueprint (PROTOCOL)

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

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

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.

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.

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.

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.

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.