43 lines
2.8 KiB
Org Mode
43 lines
2.8 KiB
Org Mode
#+TITLE: Root Cause Analysis: Micro-Loader & Deterministic Boot Sequence
|
|
#+DATE: 2026-04-11
|
|
#+FILETAGS: :rca:boot:loader:topological-sort:autonomy:
|
|
|
|
* 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 harness from malformed or hanging skills via package-based jailing and execution timeouts.
|
|
|
|
* 1. Issue: Fragile Load Order
|
|
** Symptoms
|
|
Skills that depended on functions or variables from other skills would randomly fail to load depending on the filesystem's directory traversal order.
|
|
** Root Cause
|
|
`initialize-all-skills` used a simple `dolist` over `uiop:directory-files`, which has no semantic awareness of inter-skill dependencies.
|
|
** Resolution
|
|
1. **Metadata Scanning:** Implemented `parse-skill-metadata` to extract `:ID:` and `#+DEPENDS_ON:` without executing code.
|
|
2. **Topological Sort:** Implemented a DFS-based `topological-sort-skills` to guarantee that prerequisites are loaded before their dependents.
|
|
3. **Circular Detection:** Added explicit detection and error reporting for circular dependency loops.
|
|
|
|
* 2. Issue: Shared State Corruption (Brain Rot)
|
|
** Symptoms
|
|
Variables or functions with the same name in different skills would silently overwrite each other, causing unpredictable behavior.
|
|
** Root Cause
|
|
All skills were being evaluated directly into the `opencortex` package.
|
|
** Resolution
|
|
**Package-Based Jailing:** Each skill is now evaluated within its own dedicated, shadowed package (e.g., `OPENCORTEX.SKILLS.ORG-SKILL-CHAT`). This ensures logical isolation while still allowing access to kernel exports.
|
|
|
|
* 3. Issue: Boot Stall (The Hanging Skill)
|
|
** Symptoms
|
|
A single skill with an infinite loop or heavy synchronous initialization could hang the entire agent during startup.
|
|
** Root Cause
|
|
Skill loading was strictly synchronous and blocking on the main thread.
|
|
** Resolution
|
|
**Execution Timeouts:** Implemented `load-skill-with-timeout`, which wraps the loader in a monitored thread. If a skill takes longer than 5 seconds to initialize, the loader terminates the thread, jails the failure, and continues with the rest of the boot sequence.
|
|
|
|
* 4. opencortex Mandate Alignment
|
|
** Evolutionary Kernel
|
|
The boot sequence is now a verifiable, mathematical process rather than a side-effect of filesystem organization.
|
|
** Literate Granularity
|
|
The `org-skill-skills.org` source was refactored into a strictly granular "one definition per block" format.
|
|
|
|
* 5. Permanent Learnings
|
|
- **Reverse Topological Order:** Remember that a DFS-based sort with `push` needs an `nreverse` to place dependencies at the front of the list.
|
|
- **Path Portability:** Use `uiop:getcwd` instead of `pwd` for more reliable path resolution across different Lisp implementations and OSes.
|