amr/passepartout
1
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: global terminology update from kernel/core to harness

Browse Source
This commit is contained in:
Amr Gharbeia
2026-04-12 18:28:11 -04:00
parent 475f79e79d
commit 3f8c37712c
71 changed files with 255 additions and 499 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/quickstart.org
View File

@@ -7,7 +7,7 @@
Welcome to ~org-agent~, the "Executive Soul" of your personal OS. This guide will help you set up and interact with your first neurosymbolic agent.
* 2. Prerequisites
Before launching the kernel, ensure your host environment has:
Before launching the harness, ensure your host environment has:
- **Docker & Docker Compose**: The primary enclosure for the Lisp Machine.
- **LLM API Keys**: At least one key for Gemini, Anthropic, or OpenAI.
- **Emacs (Optional)**: For the full literate experience via ~org-agent.el~.
@@ -33,7 +33,7 @@ docker-compose up --build -d
#+end_src
* 4. Interaction Gateways
Once the kernel is "Ready", you can interact with it via multiple sensors.
Once the harness is "Ready", you can interact with it via multiple sensors.
** Gateway A: Emacs (OACP)
If you have configured the ~org-agent~ package in Emacs:
@@ -44,7 +44,7 @@ If you have configured the ~org-agent~ package in Emacs:
If you enabled Signal or Telegram in ~.env~, send a message directly to your bot.
* 5. Verification (The Chaos Check)
To ensure the kernel is fully healthy, check the logs for the Micro-Loader summary:
To ensure the harness is fully healthy, check the logs for the Micro-Loader summary:
#+begin_src bash
docker-compose logs -f org-agent
#+end_src
@@ -52,4 +52,4 @@ Look for: ~LOADER: Boot Complete. [Ready: 34] [Failed: 0]~
* 6. Next Steps
- **Extend the Brain**: Read the [[file:skill-creation.org][Skill Creation Guide]] to add custom Lisp skills.
- **Deep Dive**: Explore the [[file:../literate/][literate/]] directory to understand the kernel's architecture.
- **Deep Dive**: Explore the [[file:../literate/][literate/]] directory to understand the harness's architecture.

2
docs/rca/rca-boot-sequence.org
View File

@@ -3,7 +3,7 @@
#+FILETAGS: :rca:boot:loader:topological-sort:psf:
* Executive Summary
Refactored the arbitrary skill loading mechanism into a robust **Micro-Loader**. The system now calculates a deterministic boot sequence based on `#+DEPENDS_ON:` tags and protects the kernel from malformed or hanging skills via package-based jailing and execution timeouts.
Refactored the arbitrary skill loading mechanism into a robust **Micro-Loader**. The system now calculates a deterministic boot sequence based on `#+DEPENDS_ON:` tags and protects the harness from malformed or hanging skills via package-based jailing and execution timeouts.
* 1. Issue: Fragile Load Order
** Symptoms

4
docs/rca/rca-bouncer.org
View File

@@ -12,7 +12,7 @@ System 1 proposals involving `shell` or `eval` were executed immediately upon pa
Architecture gap. The system lacked an authorization state between "Safe" and "Executed".
** Resolution
1. **Interceptor:** Added `bouncer-check` to `symbolic.lisp`. It flags high-risk actions that lack the `:approved t` property.
2. **Asynchronous Event:** If flagged, the kernel emits an `:approval-required` event.
2. **Asynchronous Event:** If flagged, the harness emits an `:approval-required` event.
3. **Flight Plan Skill:** Created `org-skill-bouncer.org` to:
- Catch the event and create a serialized Org node with state `PLAN`.
- Monitor the Object Store for `APPROVED` states.
@@ -30,4 +30,4 @@ Ensures that the agent's "Flight Plans" are first-class citizens in the Memex, a
* 3. Permanent Learnings
- **Serial Bypass:** Always include a specific bypass flag (e.g., `:approved t`) when re-injecting intercepted actions to prevent infinite interception loops.
- **Heartbeat Listeners:** Periodic scanning of the Object Store for state transitions is an effective way to implement asynchronous authorization gates without blocking the kernel.
- **Heartbeat Listeners:** Periodic scanning of the Object Store for state transitions is an effective way to implement asynchronous authorization gates without blocking the harness.

4
docs/rca/rca-gateway-telegram.org
View File

@@ -7,9 +7,9 @@ Successfully implemented the first external communication channel (Telegram) and
* 1. Issue: Undefined Foundational Functions
** Symptoms
During compilation, `gateway-telegram.lisp` failed with `UNDEFINED-FUNCTION` for `register-actuator` and `kernel-log`.
During compilation, `gateway-telegram.lisp` failed with `UNDEFINED-FUNCTION` for `register-actuator` and `harness-log`.
** Root Cause
Poorly scoped foundational functions. These were defined in `core.lisp` (the loop orchestrator), which was loaded *after* the gateways in `org-agent.asd`. This created a "Circular Intention" where the gateways needed the kernel to exist before the kernel could load the gateways.
Poorly scoped foundational functions. These were defined in `core.lisp` (the loop orchestrator), which was loaded *after* the gateways in `org-agent.asd`. This created a "Circular Intention" where the gateways needed the harness to exist before the harness could load the gateways.
** Resolution
1. **Relocation:** Moved `*actuator-registry*` and `register-actuator` to `protocol.lisp` (the foundation).
2. **Reordering:** Adjusted `org-agent.asd` to load `core.lisp` (containing the stimulus loop) immediately after the symbolic gates but before the physical sensors (gateways).

2
docs/rca/rca-lisp-repair-async.org
View File

@@ -30,4 +30,4 @@ Leveraged the pipeline's ability to re-inject `EVENT` signals to flatten the rec
* 4. Permanent Learnings
- **Emit, Don't Call:** In a microkernel, if a non-fatal error occurs, always emit a signal rather than calling a recovery function. This allows the system to remain asynchronous and modular.
- **Signal Inspection:** When writing symbolic gates, always verify the exact shape of the `context` signal being passed by the kernel to avoid nesting errors.
- **Signal Inspection:** When writing symbolic gates, always verify the exact shape of the `context` signal being passed by the harness to avoid nesting errors.

2
docs/rca/rca-shell-hardening.org
View File

@@ -19,7 +19,7 @@ The `execute-shell-safely` function only checked the first space-delimited word
** Symptoms
`UNDEFINED-FUNCTION EXECUTE-SHELL-SAFELY` during unit tests.
** Root Cause
`src/shell-logic.lisp` was missing an `(in-package :org-agent)` declaration, causing symbols to be defined in the default `COMMON-LISP-USER` package instead of the kernel package.
`src/shell-logic.lisp` was missing an `(in-package :org-agent)` declaration, causing symbols to be defined in the default `COMMON-LISP-USER` package instead of the harness package.
** Resolution
Added the `in-package` header to `shell-logic.lisp`.