diff --git a/literate/loop.org b/literate/loop.org index c8700a6..be3cae1 100644 --- a/literate/loop.org +++ b/literate/loop.org @@ -214,7 +214,7 @@ Compares multiple proposals (from parallel backends) and selects the most consis #+end_src *** Decide Gate -The Deliberate safety gate. Validates the candidate action against formal rules and PSF invariants. +The Deliberate safety gate. Validates the candidate action against formal rules and Engineering invariants. **** Phase A: Demand - *Need:* Ensure that malformed candidates (e.g., raw strings from Associative) do not crash the `decide` or `safety-harness` logic, which expect property lists. @@ -378,7 +378,7 @@ The execution entry point for the harness binary. #+end_src * Phase E: Chaos (Verification) -Following the PSF mandates, the Reactive Signal Pipeline must be empirically verified. The following test suite ensures that signals flow correctly through the gates, that feedback is handled without stack recursion, and that depth limits are strictly enforced. +Following the Engineering mandates, the Reactive Signal Pipeline must be empirically verified. The following test suite ensures that signals flow correctly through the gates, that feedback is handled without stack recursion, and that depth limits are strictly enforced. #+begin_src lisp :tangle ../tests/pipeline-tests.lisp (defpackage :org-agent-pipeline-tests @@ -469,9 +469,9 @@ Following the PSF mandates, the Reactive Signal Pipeline must be empirically ver (test test-log-buffering "Verify that harness-log correctly populates the system logs." - (harness-log "PSF TEST LOG") + (harness-log "Engineering TEST LOG") (let ((logs (context-get-system-logs 5))) - (is (cl:some (lambda (line) (search "PSF TEST LOG" line)) logs)))) + (is (cl:some (lambda (line) (search "Engineering TEST LOG" line)) logs)))) (test test-global-awareness-assembly "Verify that context-assemble-global-awareness reports active projects." diff --git a/literate/package.org b/literate/package.org index cdd7435..9c2d8f9 100644 --- a/literate/package.org +++ b/literate/package.org @@ -79,6 +79,7 @@ The `package.lisp` file defines the public API of the `org-agent` kernel. It exp #:skill #:skill-name #:skill-priority + #:skill-dependencies #:skill-trigger-fn #:skill-neuro-prompt #:skill-symbolic-fn diff --git a/org-agent.asd b/org-agent.asd index 2dc4e8c..c294207 100644 --- a/org-agent.asd +++ b/org-agent.asd @@ -8,6 +8,8 @@ :serial t :components ((:file "src/package") (:file "src/skills") + (:file "src/system-invariants") + (:file "src/engineering-standards") (:file "src/protocol-validator") (:file "src/protocol") (:file "src/object-store") diff --git a/skills/org-skill-engineering-standards.org b/skills/org-skill-engineering-standards.org new file mode 100644 index 0000000..ee58674 --- /dev/null +++ b/skills/org-skill-engineering-standards.org @@ -0,0 +1,85 @@ +:PROPERTIES: +:ID: 37f2b59f-4537-4cca-ac7f-5c24b9e2e773 +:CREATED: [2026-03-30 Mon 21:16] +:EDITED: [2026-04-12 Sun 18:45] +:END: +#+TITLE: SKILL: Engineering Standards (Universal Literate Note) +#+STARTUP: content +#+FILETAGS: :engineering:standards:workflow:lisp:git:tdd: + +* Overview +These are the strict **Engineering Standards** for all development within this system. They ensure that every line of code is provably correct, auditable, and maintainable. These standards are enforced both through the agent's instructions and physical Lisp safety gates. + +* The Mandates (Operational Standards) + +** 1. Commit Before Modify +You MUST commit and push the current state of the workspace BEFORE initiating any new file modifications. This ensures a clean recovery point. The system physically blocks file modifications if the working tree is dirty. + +** 2. Literate Programming (The Single Source of Truth) +All system logic and skills MUST be implemented as Literate Org files. Weaving documentation and code together ensures that the "Why" (Architectural Intent) is never separated from the "How" (Implementation). + +** 3. Literate Granularity +Every Lisp function, macro, or variable must reside in its own dedicated `#+begin_src lisp` block. This allows for specific narrative explanation for every logical unit. + +** 4. Test-Driven Development (Continuous QA) +No change is complete without verification. Every new function or macro must be accompanied by a FiveAM test case. You must run the test suite and verify success before considering a task complete. + +** 5. The Consensus Loop (Plan Mode) +Major architectural shifts or complex refactors require a formal implementation plan. You must enter Plan Mode, draft a Blueprint (PROTOCOL), and seek formal approval before execution. + +* Phase B: Blueprint (PROTOCOL) +:PROPERTIES: +:STATUS: SIGNED +:END: + +** 1. Architectural Intent +The Engineering Standards skill provides the deterministic enforcement of the workflow. It intercepts agent actions and validates them against the git environment and system state. + +** 2. Semantic Interfaces + +*** `verify-git-clean-p` + - Purpose: Checks if the git repository is in a clean state. + - Returns: `t` if clean, `nil` if dirty. + +* Phase D: Build (Implementation) + +** Git Status Enforcement +#+begin_src lisp :tangle ../src/engineering-standards.lisp +(in-package :org-agent) + +(defun verify-git-clean-p (dir) + "Returns T if the git repository at DIR has no uncommitted changes." + (let ((status (uiop:run-program (list "git" "-C" (namestring dir) "status" "--porcelain") + :output :string + :ignore-error-status t))) + (string= "" (string-trim '(#\Space #\Newline #\Tab) status)))) + +(defun engineering-standards-gate (action context) + "Physically enforces the 'Commit Before Modify' rule." + (let* ((payload (getf action :payload)) + (act (or (getf payload :action) (getf action :action))) + (target-file (getf payload :file))) + + ;; If the action involves modifying files, check git status + (when (member act '(:modify-file :write-file :replace :rename-file :delete-file)) + (let ((proj-root (asdf:system-source-directory :org-agent))) + (unless (verify-git-clean-p proj-root) + (harness-log "DELIBERATE [Standards]: BLOCKING ACTION. Working tree is dirty. Commit changes before modification.") + (return-from engineering-standards-gate + (list :type :LOG :payload (list :text "Engineering Standard Violation: Working tree dirty. You MUST commit before modifying files.")))))) + + action)) +#+end_src + +** Skill Definition +#+begin_src lisp :tangle ../src/engineering-standards.lisp +(org-agent:defskill :skill-engineering-standards + :priority 900 ; High priority, runs before most skills + :trigger (lambda (ctx) t) ; Always active + :neuro nil + :symbolic #'engineering-standards-gate) +#+end_src + +* See Also +- [[file:org-skill-system-invariants.org][System Invariants]] +- [[file:../README.org][org-agent README]] diff --git a/skills/org-skill-agent.org b/skills/org-skill-system-invariants.org similarity index 66% rename from skills/org-skill-agent.org rename to skills/org-skill-system-invariants.org index 226e66a..7f7a735 100644 --- a/skills/org-skill-agent.org +++ b/skills/org-skill-system-invariants.org @@ -1,21 +1,21 @@ :PROPERTIES: :ID: 47425a43-2be0-423c-8509-22592cfe9c9e :CREATED: [2026-04-07 Tue 12:57] -:EDITED: [2026-04-08 Wed 10:50] +:EDITED: [2026-04-12 Sun 18:30] :END: -#+TITLE: SKILL: Org-Agent Executive Soul (Universal Literate Note) +#+TITLE: SKILL: System Invariants (Universal Literate Note) #+STARTUP: content -#+FILETAGS: :platform:kernel:lisp:psf:alignment:invariants: +#+FILETAGS: :platform:harness:lisp:alignment:invariants: #+DEPENDS_ON: id:37f2b59f-4537-4cca-ac7f-5c24b9e2e773 #+DEPENDS_ON: id:bbcacb7b-c0ff-4f7e-8bf4-c6ba152a19ce #+DEPENDS_ON: id:homoiconic-memory-skill * Overview -The *Org-Agent* is the neurosymbolic kernel of the personal operating system. It acts as the "executive soul," using Org-mode as its native memory and Common Lisp as its deterministic reasoning engine. It follows a minimalist microkernel design, extending its capabilities via hot-reloadable skills. +The *Org-Agent* is a neurosymbolic harness for a personal operating system. It uses Org-mode as its native memory and Common Lisp as its deterministic reasoning engine. It follows a minimalist design, extending its capabilities via hot-reloadable skills. -This document contains the *Core Alignment Invariants* and *Operational Mandates* of the Personal Software Foundry. These are non-negotiable philosophical constraints that every agentic action MUST satisfy. +This document contains the *Core System Invariants*. These are non-negotiable philosophical and technical constraints that every agentic action MUST satisfy. -System 2 (Symbolic) uses these headlines as a "Moral Compass" during the decision stage. +The Deliberate Engine uses these headlines as a "Moral Compass" during the decision stage. * The Core Invariants @@ -26,16 +26,16 @@ Every action must increase the user's independence from centralized, proprietary The agent's goal is not to "do it for the user," but to "empower the user." Every autonomous action must be explained at a level that increases the user's technical understanding of the Lisp Machine. ** 3. Zero-Bloat Mandate -The PSF core must remain minimalist. "Just-in-case" code is a security vulnerability. Complexity must be earned, not imported. +The system harness must remain minimalist. "Just-in-case" code is a security vulnerability. Complexity must be earned, not imported. ** 4. Radical Transparency -The agent's "Thought Stream" must be fully auditable. Hidden reasoning or obfuscated logic is a violation of the PSF methodology. +The agent's "Thought Stream" must be fully auditable. Hidden reasoning or obfuscated logic is a violation of the system's design principles. ** 5. Long-Term Sustainability Prioritize local, energy-efficient, and offline-first architectures. The "Memex" should be functional in a 100-year horizon. * Operational Mandates -Every action performed by an agent in this environment must also adhere to the software development standards defined in the [[file:../../org-agent-contrib/org-skill-project-foundry.org][Personal Software Foundry (PSF)]] methodology (e.g. Literate Granularity, Commit-Before-Modify, Continuous QA). +Every action performed by an agent in this environment must also adhere to the [[file:../../org-agent-contrib/org-skill-engineering-standards.org][Engineering Standards]] (e.g. Literate Granularity, Commit-Before-Modify, Continuous QA). * Phase A: Demand (PRD) :PROPERTIES: @@ -43,18 +43,18 @@ Every action performed by an agent in this environment must also adhere to the s :END: ** 1. Purpose -Define the core functional and security requirements for the neurosymbolic daemon. +Define the core functional and security requirements for the neurosymbolic harness. ** 2. User Needs - *Homoiconic Memory:* Use Org-mode AST as the primary data structure for both human and machine. - *Deterministic Reasoning:* Common Lisp (SBCL) for high-performance, threaded symbolic logic. - *Cognitive Loop:* A strict four-stage pipeline: Perceive -> Think (Associative) -> Decide (Deliberate) -> Act. -- *Minimalist Core:* the harness handles only the loop, object-store, and communication; all else is a skill. +- *Minimalist Core:* The harness handles only the loop, object-store, and communication; all else is a skill. - *Security by Default:* Reader safety (*read-eval* disabled) and package-based skill jailing. ** 3. Success Criteria -*** TODO Core Lisp microkernel stability (Heartbeat consistency) -*** TODO OACP Swank/Socket communication reliability +*** TODO Harness Lisp stability (Heartbeat consistency) +*** TODO OACP communication reliability *** TODO Org AST-to-Lisp conversion fidelity *** TODO Deliberate Safety Gating (The Harness) enforcement @@ -64,36 +64,36 @@ Define the core functional and security requirements for the neurosymbolic daemo :END: ** 1. Architectural Intent -the harness is transport-agnostic and business-logic-agnostic. It communicates with external actuators (Emacs, Web, Signal) via the Org-Agent Communication Protocol (OACP). +The harness is transport-agnostic and business-logic-agnostic. It communicates with external actuators (Emacs, Web, Signal) via the Org-Agent Communication Protocol (OACP). ** 2. Semantic Interfaces #+begin_src lisp -(defun kernel-perceive (stimulus) +(defun harness-perceive (stimulus) "Injects an event into the global object store.") -(defun kernel-think (context) +(defun harness-think (context) "Queries Associative (LLM) for an intuitive proposal.") -(defun kernel-decide (proposal context) +(defun harness-decide (proposal context) "Invokes Deliberate (Symbolic Skills) to verify or overrule the proposal.") -(defun kernel-act (action) +(defun harness-act (action) "Dispatches verified commands to the registered actuators.") #+end_src * Phase D: Build (Implementation) -The executive soul provides the high-level orchestration for the OODA loop. - ** Cognitive Tools -We register tools for kernel introspection and state management. +We register tools for harness introspection and state management. -#+begin_src lisp -(org-agent:def-cognitive-tool :kernel-status "Returns the current operational status of the Org-Agent kernel, including loaded skills and telemetry." +#+begin_src lisp :tangle ../src/system-invariants.lisp +(in-package :org-agent) + +(org-agent:def-cognitive-tool :harness-status "Returns the current operational status of the Org-Agent harness, including loaded skills and telemetry." nil :body (lambda (args) (declare (ignore args)) - (format nil "KERNEL STATUS: + (format nil "HARNESS STATUS: - Active Skills: ~a - Uptime: ~a seconds - Memory Usage: ~a @@ -119,15 +119,15 @@ We register tools for kernel introspection and state management. output))) #+end_src -** The Executive Soul Skill +** The System Invariants Skill This skill acts as the default "Moral Compass" for the agent. -#+begin_src lisp -(org-agent:defskill :skill-agent +#+begin_src lisp :tangle ../src/system-invariants.lisp +(org-agent:defskill :skill-system-invariants :priority 1000 ; Absolute highest priority :trigger (lambda (context) t) ; Always active as a fallback :neuro (lambda (context) - "You are the Org-Agent Executive Soul. Your goal is to empower the user through the Lisp Machine. + "You are the Org-Agent System Invariants Skill. Your goal is to empower the user through the Lisp Machine. Follow the Core Invariants: 1. Sovereignty: Avoid proprietary traps. 2. Technical Mastery: Explain your logic. @@ -139,11 +139,10 @@ Follow the Core Invariants: (let ((payload (getf action :payload))) (if (and payload (search "proprietary" (format nil "~s" payload))) (progn - (org-agent:harness-log "DELIBERATE [Agent]: Sovereignty violation suspected. Blocking action.") + (org-agent:harness-log "DELIBERATE [Invariants]: Sovereignty violation suspected. Blocking action.") nil) action)))) #+end_src * Phase E: Chaos (Verification) Verification logic is contained in `projects/org-agent/tests/`. - diff --git a/src/engineering-standards.lisp b/src/engineering-standards.lisp new file mode 100644 index 0000000..bbdfd8a --- /dev/null +++ b/src/engineering-standards.lisp @@ -0,0 +1,30 @@ +(in-package :org-agent) + +(defun verify-git-clean-p (dir) + "Returns T if the git repository at DIR has no uncommitted changes." + (let ((status (uiop:run-program (list "git" "-C" (namestring dir) "status" "--porcelain") + :output :string + :ignore-error-status t))) + (string= "" (string-trim '(#\Space #\Newline #\Tab) status)))) + +(defun engineering-standards-gate (action context) + "Physically enforces the 'Commit Before Modify' rule." + (let* ((payload (getf action :payload)) + (act (or (getf payload :action) (getf action :action))) + (target-file (getf payload :file))) + + ;; If the action involves modifying files, check git status + (when (member act '(:modify-file :write-file :replace :rename-file :delete-file)) + (let ((proj-root (asdf:system-source-directory :org-agent))) + (unless (verify-git-clean-p proj-root) + (harness-log "DELIBERATE [Standards]: BLOCKING ACTION. Working tree is dirty. Commit changes before modification.") + (return-from engineering-standards-gate + (list :type :LOG :payload (list :text "Engineering Standard Violation: Working tree dirty. You MUST commit before modifying files.")))))) + + action)) + +(org-agent:defskill :skill-engineering-standards + :priority 900 ; High priority, runs before most skills + :trigger (lambda (ctx) t) ; Always active + :neuro nil + :symbolic #'engineering-standards-gate) diff --git a/src/package.lisp b/src/package.lisp index a93e6b3..59abcac 100644 --- a/src/package.lisp +++ b/src/package.lisp @@ -70,6 +70,7 @@ #:skill #:skill-name #:skill-priority + #:skill-dependencies #:skill-trigger-fn #:skill-neuro-prompt #:skill-symbolic-fn diff --git a/src/system-invariants.lisp b/src/system-invariants.lisp new file mode 100644 index 0000000..8924452 --- /dev/null +++ b/src/system-invariants.lisp @@ -0,0 +1,50 @@ +(in-package :org-agent) + +(org-agent:def-cognitive-tool :harness-status "Returns the current operational status of the Org-Agent harness, including loaded skills and telemetry." + nil + :body (lambda (args) + (declare (ignore args)) + (format nil "HARNESS STATUS: +- Active Skills: ~a +- Uptime: ~a seconds +- Memory Usage: ~a +- Providers: ~a" + (hash-table-count org-agent:*skills-registry*) + (get-universal-time) ; Placeholder for actual uptime + "Not implemented" + org-agent:*provider-cascade*))) + +(org-agent:def-cognitive-tool :list-skills "Lists all currently loaded skills and their metadata." + nil + :body (lambda (args) + (declare (ignore args)) + (let ((output "LOADED SKILLS: +")) + (maphash (lambda (name skill) + (setf output (concatenate 'string output + (format nil "- ~a (Priority: ~a, Deps: ~s)~%" + name + (org-agent:skill-priority skill) + (org-agent:skill-dependencies skill))))) + org-agent:*skills-registry*) + output))) + +(org-agent:defskill :skill-system-invariants + :priority 1000 ; Absolute highest priority + :trigger (lambda (context) t) ; Always active as a fallback + :neuro (lambda (context) + "You are the Org-Agent System Invariants Skill. Your goal is to empower the user through the Lisp Machine. +Follow the Core Invariants: +1. Sovereignty: Avoid proprietary traps. +2. Technical Mastery: Explain your logic. +3. Zero-Bloat: Keep it minimal. +4. Transparency: Your thoughts are auditable. +5. Sustainability: Think long-term.") + :symbolic (lambda (action context) + ;; Basic invariant check: Block actions that appear to violate sovereignty + (let ((payload (getf action :payload))) + (if (and payload (search "proprietary" (format nil "~s" payload))) + (progn + (org-agent:harness-log "DELIBERATE [Invariants]: Sovereignty violation suspected. Blocking action.") + nil) + action))))