:PROPERTIES:
:ID:       74f65792-1bf2-4b33-ab1a-e8a4830143fb
:CREATED:  [2026-03-30 Mon 21:16]
:EDITED:   [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Task Integrity Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :gtd:integrity:safety:psf:

* Overview
The *Task Integrity Agent* is the "Guardian" of the GTD system. It ensures that all task transitions adhere to semantic rules, preventing logical inconsistencies and maintaining the structural health of the task hierarchy.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Define automated behaviors for GTD state consistency and dependency verification.

** 2. User Needs
- *Semantic Enforcement:* Valid state transitions (Active vs. Resolved).
- *Dependency Awareness:* Block closing parents with active children.
- *Proactive Assistance:* Suggesting next logical actions based on momentum.
- *Fidelity:* Preservation of metadata during state transitions.

** 3. Success Criteria
*** TODO Semantic Category Mapping
*** TODO Active Children Detection
*** TODO State Transition Block Verification


* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:


* Implementation

** Semantic Mapping
#+begin_src lisp

(defun semantic-mapping (task-state)
  "Maps Org-mode task states to semantic categories."
  (case (intern (string-upcase task-state) :keyword)
    ((:todo :active :started :wait) :active)
    ((:done :cancelled :resolved) :resolved)
    (t :unknown)))
#+end_src

** Active Children Detection
#+begin_src lisp
(defun detect-active-children (task-id)
  "Checks if a task has any child tasks in an active state."
  (let ((children (list-objects-with-attribute :PARENT task-id)))
    (remove-if-not (lambda (child)
                     (let ((todo (getf (org-object-attributes child) :TODO)))
                       (and todo (eq (semantic-mapping todo) :active))))
                   children)))
#+end_src

** Integrity Check (task-integrity-check)
Enforces high-integrity semantic rules for task management.

#+begin_src lisp
(defun task-integrity-check (action)
  "Enforces semantic GTD integrity rules on proposed actions."
  (let* ((payload (getf action :payload))
         (act (or (getf payload :action) (getf action :action)))
         (id (or (getf payload :id) (getf action :id)))
         (new-attrs (or (getf payload :attributes) (getf action :attributes))))
    (when (and (eq act :update-node) 
               (equal (getf new-attrs :TODO) "DONE"))
      (let ((active-children (detect-active-children id)))
        (when active-children
          (return-from task-integrity-check 
            (format nil "Blocked by Task Integrity: ~a active children exist." (length active-children))))))
    nil))
#+begin_src

** Skill Definition
#+begin_src lisp
(defskill :skill-task-integrity
  :priority 90
  :trigger (lambda (ctx) (declare (ignore ctx)) nil)
  :probabilistic nil
  :deterministic (lambda (action context)
              (declare (ignore context))
              (let ((err (task-integrity-check action)))
                (if err
                    (list :type :LOG :payload (list :text err))
                    action))))
#+end_src