REFAC: Standardize on Cognitive Cycle and update documentation

This commit is contained in:
2026-04-14 15:59:19 -04:00
parent 34a210228e
commit e29ca5679e
46 changed files with 195 additions and 268 deletions

View File

@@ -4,11 +4,11 @@
:END:
** Analyst Phase
The Chat skill currently tells the LLM to output Org-mode subtrees, but the =org-agent= kernel evaluates LLM output via =read-from-string=. This expects a valid s-expression, specifically a Common Lisp property list (plist) that targets an Emacs actuator with an =:insert-at-end= action. We must explicitly mandate that the LLM wraps its conversational output in this plist.
The Chat skill currently tells the LLM to output Org-mode subtrees, but the =opencortex= kernel evaluates LLM output via =read-from-string=. This expects a valid s-expression, specifically a Common Lisp property list (plist) that targets an Emacs actuator with an =:insert-at-end= action. We must explicitly mandate that the LLM wraps its conversational output in this plist.
** Coder Phase
- [X] Create =inbox/flight-plan-chat-fix.org= (this file).
- [X] Update =notes/org-skill-chat.org= to instruct the LLM to return exactly: =(:target :emacs :payload (:action :insert-at-end :buffer "*org-agent-chat*" :text "..."))=
- [X] Update =notes/org-skill-chat.org= to instruct the LLM to return exactly: =(:target :emacs :payload (:action :insert-at-end :buffer "*opencortex-chat*" :text "..."))=
- [X] Fix tangle paths to root-relative =../projects/...=
** Tester Phase

View File

@@ -10,14 +10,14 @@ The user is seeing the agent's meta-commentary (e.g., "Okay, I've inserted...")
** Coder Phase
- [X] Create =inbox/flight-plan-chat-ui-fix.org= (this file).
- [ ] Update =projects/org-agent/src/org-agent.el= to replace "Thinking..." lines.
- [ ] Update =projects/opencortex/src/opencortex.el= to replace "Thinking..." lines.
- [ ] Update =notes/org-skill-chat.org= to suppress conversational preamble.
- [ ] Tangle and restart.
** Tester Phase
1. Tangle all modified files.
2. Restart the daemon.
3. Reload =org-agent.el= in Emacs.
3. Reload =opencortex.el= in Emacs.
4. Test chat and verify:
- "Thinking..." is replaced by the response.
- No "Okay, I've inserted..." preamble appears.

View File

@@ -22,7 +22,7 @@ This flight plan defines the strict, step-by-step protocol for escaping the Lisp
* Phase B: Tangle & Audit (The Coder)
** TODO 3. Tangle the Literate Source
- Action: Run =emacs --batch --eval '(require (quote ob-tangle))' --eval '(org-babel-tangle-file "~/memex/projects/org-agent/docs/README.org")'=
- Action: Run =emacs --batch --eval '(require (quote ob-tangle))' --eval '(org-babel-tangle-file "~/memex/projects/opencortex/docs/README.org")'=
- Verification: The command must exit with code 0 and report that blocks were tangled.
** TODO 4. Audit the Physical Lisp Files
@@ -31,7 +31,7 @@ This flight plan defines the strict, step-by-step protocol for escaping the Lisp
* Phase C: Quality Gate (The Tester)
** TODO 5. Run the Lisp Test Suite
- Action: Execute =sbcl --non-interactive --eval "(asdf:test-system :org-agent)"=
- Action: Execute =sbcl --non-interactive --eval "(asdf:test-system :opencortex)"=
- Verification: All 13 cognitive tests must pass. If any fail, STOP and return to Phase A.
** TODO 6. Compile the Sovereign Binary
@@ -40,8 +40,8 @@ This flight plan defines the strict, step-by-step protocol for escaping the Lisp
* Phase D: Live Execution (The Sovereign)
** TODO 7. Clean Restart
- Action: Kill all stale =org-agent-server= processes and start the new binary in the background.
- Verification: The log shows =org-agent Kernel Booted Successfully= and =Daemon Listening=.
- Action: Kill all stale =opencortex-server= processes and start the new binary in the background.
- Verification: The log shows =opencortex Kernel Booted Successfully= and =Daemon Listening=.
** TODO 8. Live Model Discovery Test
- Action: Send =@agent list models= via Emacs batch script.

View File

@@ -4,14 +4,14 @@
:END:
** Analyst Phase
The current =org-agent= kernel is a "one-way" sensory system. It receives stimuli from Emacs via Harness Protocol but lacks the physical plumbing to send responses back over the same socket. To fix this, we must:
The current =opencortex= kernel is a "one-way" sensory system. It receives stimuli from Emacs via Harness Protocol but lacks the physical plumbing to send responses back over the same socket. To fix this, we must:
1. Modify the kernel (literately) to pass the client TCP stream through the cognitive loop.
2. Implement the =skill-emacs-bridge= logic to capture this stream and perform framed Harness Protocol writes.
3. Update the =skill-chat= to utilize the new bridge.
** Coder Phase
- [X] Create =inbox/flight-plan-emacs-bridge.org= (this file).
- [ ] Update =projects/org-agent/docs/README.org= (Literate Kernel) with the stream-passing hook.
- [ ] Update =projects/opencortex/docs/README.org= (Literate Kernel) with the stream-passing hook.
- [ ] Update =notes/org-skill-emacs-bridge.org= to implement the Harness Protocol outbound writer.
- [ ] Tangle the updated files.
- [ ] Rebuild the daemon binary.
@@ -20,4 +20,4 @@ The current =org-agent= kernel is a "one-way" sensory system. It receives stimul
1. Tangle all modified files.
2. Restart the daemon.
3. Run the =test-chat.lisp= script to verify two-way communication.
4. Verify in Emacs =*org-agent-chat*=.
4. Verify in Emacs =*opencortex-chat*=.

View File

@@ -3,7 +3,7 @@
#+FILETAGS: :plan:ux:emacs:interface:psf:
* Phase A: Demand (Verify State)
- Current state: The `org-agent` Emacs client uses a single buffer for both input and output, or a clunky side-window for reasoning. The interface is rudimentary and lacks modern chat application affordances.
- Current state: The `opencortex` Emacs client uses a single buffer for both input and output, or a clunky side-window for reasoning. The interface is rudimentary and lacks modern chat application affordances.
- User feedback indicates that responses and reasoning streams are sometimes missing or hard to read.
- Objective: Design a comprehensive, intuitive, and modern UX for the Emacs client.
@@ -18,13 +18,13 @@
** 1. Window Layout Management
We will abandon the single-buffer approach and adopt a dual-window layout for the chat interface:
- **`*org-agent-chat*` (Top, 80% height)**: A read-only `special-mode` or customized `org-mode` buffer dedicated to displaying the conversation history, agent responses, and tool execution logs.
- **`*org-agent-input*` (Bottom, 20% height)**: A dedicated `markdown-mode` or `org-mode` buffer for composing messages. Pressing `C-c C-c` here will send the contents to the daemon, clear the input buffer, and append the user's message to the main chat buffer.
- **`*opencortex-chat*` (Top, 80% height)**: A read-only `special-mode` or customized `org-mode` buffer dedicated to displaying the conversation history, agent responses, and tool execution logs.
- **`*opencortex-input*` (Bottom, 20% height)**: A dedicated `markdown-mode` or `org-mode` buffer for composing messages. Pressing `C-c C-c` here will send the contents to the daemon, clear the input buffer, and append the user's message to the main chat buffer.
** 2. The Output Formatting Engine (Syntax & Color)
To make the main chat buffer appealing, we need a robust formatting engine within `org-agent.el`:
To make the main chat buffer appealing, we need a robust formatting engine within `opencortex.el`:
- **Structured Insertion**: When the daemon sends an `:insert-at-end` command, the Emacs client will parse the payload.
- **Font-Lock Extensions**: We will define custom `font-lock` rules for the `*org-agent-chat*` buffer to highlight specific elements:
- **Font-Lock Extensions**: We will define custom `font-lock` rules for the `*opencortex-chat*` buffer to highlight specific elements:
- *User Messages*: Distinct background or font face.
- *Agent Responses*: Standard Org-mode styling.
- *Tool Executions (Reasoning)*: Dimmed or italicized text for "Thinking..." or "Executing shell command: `ls`".
@@ -37,11 +37,11 @@ To handle code modifications safely and beautifully:
- *Interactive Acceptance*: The user can press a key (e.g., `C-c C-y`) on the diff to accept and apply the patch, realizing the "Active Approval Mode" pattern in Emacs.
** 4. The Reasoning Stream Integration
- Instead of a separate right-side window that clutters the workspace, the reasoning stream (Probabilistic Engine thoughts, tool calls) will be integrated directly into the main `*org-agent-chat*` buffer.
- Instead of a separate right-side window that clutters the workspace, the reasoning stream (Probabilistic Engine thoughts, tool calls) will be integrated directly into the main `*opencortex-chat*` buffer.
- It will be presented as a collapsible Org-mode drawer (e.g., `:REASONING:`) or formatted as dimmed, transient text that provides transparency without overwhelming the primary conversation.
* Phase C: Tester (Verification Strategy)
- Launch `M-x org-agent`.
- Launch `M-x opencortex`.
- Verify the dual-window layout appears correctly.
- Type a message in the input buffer, send it, and verify it clears and appears in the main buffer.
- Trigger a tool call and verify the reasoning stream is formatted clearly (and distinct from the final answer).
@@ -49,5 +49,5 @@ To handle code modifications safely and beautifully:
* Migration Strategy
This overhaul requires significant changes to:
1. `projects/org-agent/src/org-agent.el` (The Emacs client).
1. `projects/opencortex/src/opencortex.el` (The Emacs client).
2. `notes/org-skill-chat.org` (To update the expected payload formats if we move beyond simple `:insert-at-end`).

View File

@@ -28,11 +28,11 @@ Refactor the =.env.example= and secure local =.env= to remove the legacy PARA st
2. *Harden Path Resolution (README.org):*
- Update =load-all-skills= to use =context-resolve-path= when reading the =SKILLS_DIR= environment variable.
- This ensures that if a user sets =SKILLS_DIR="$MEMEX_DIR/notes"=, the Lisp kernel expands it correctly regardless of the OS or username.
3. *Sync Secure .env (~/.local/share/org-agent/.env):*
3. *Sync Secure .env (~/.local/share/opencortex/.env):*
- Refactor the user's secure file to use this dynamic derivation.
** [Tester] Verification Strategy
1. *Portability Test:* Temporarily set =MEMEX_DIR=/tmp/memex-test= in the environment and verify that =(org-agent:context-get-skill-source "test")= attempts to read from the correct expanded path.
1. *Portability Test:* Temporarily set =MEMEX_DIR=/tmp/memex-test= in the environment and verify that =(opencortex:context-get-skill-source "test")= attempts to read from the correct expanded path.
2. *Boot Test:* Restart daemon and ensure all skills load via the new expanded paths.
* NEXT Authorization Gate

View File

@@ -11,14 +11,14 @@ Decouple HTTP request logic from the core neuro kernel (`neuro.lisp`) and migrat
- Solution: Move HTTP logic to `org-skill-provider-*` modules. The kernel's `ask-neuro` becomes a pure interface.
* Phase C: Success (Quality - Analyst Phase)
- **TDD Requirement:** Create `projects/org-agent/tests/neuro-test.lisp` containing assertions for the new `ask-neuro` contract.
- **TDD Requirement:** Create `projects/opencortex/tests/neuro-test.lisp` containing assertions for the new `ask-neuro` contract.
- The tests MUST be executed and PROVE failure before any code is modified.
- Tests will assert that:
1. `ask-neuro` fails gracefully when the `*neuro-backends*` registry is empty.
2. `ask-neuro` succeeds when a mock provider is registered and correctly delegates the prompt to the mock function.
* Phase D: Build (Engineering - Coder Phase)
- Strip `execute-openrouter-request`, `execute-groq-request`, and `execute-gemini-request` from `projects/org-agent/docs/README.org`.
- Strip `execute-openrouter-request`, `execute-groq-request`, and `execute-gemini-request` from `projects/opencortex/docs/README.org`.
- Draft `notes/org-skill-provider-openrouter.org`.
- Draft `notes/org-skill-provider-groq.org`.
- Draft `notes/org-skill-provider-gemini.org`.
@@ -27,4 +27,4 @@ Decouple HTTP request logic from the core neuro kernel (`neuro.lisp`) and migrat
* Phase E: Chaos (Chaos Phase - Final Verification)
- Hot-load the refactored core and new provider skills.
- Run `neuro-test.lisp` and PROVE it passes.
- Inject a complex chat stimulus and monitor `org-agent-repl.log` for successful autonomous execution.
- Inject a complex chat stimulus and monitor `opencortex-repl.log` for successful autonomous execution.

View File

@@ -22,7 +22,7 @@ done
#+begin_src elisp :tangle inject-metadata.el
(require 'org)
(defun org-agent-inject-metadata (file created edited)
(defun opencortex-inject-metadata (file created edited)
(with-current-buffer (find-file-noselect file)
(org-with-wide-buffer
(goto-char (point-min))
@@ -31,12 +31,12 @@ done
(org-id-get-create) ; Ensure drawer exists
(setq props (org-get-property-block))))
(org-set-property "CREATED" (org-agent-format-iso created))
(org-set-property "EDITED" (org-agent-format-iso edited))
(org-set-property "CREATED" (opencortex-format-iso created))
(org-set-property "EDITED" (opencortex-format-iso edited))
(save-buffer)
(kill-buffer))))
(defun org-agent-format-iso (iso-date)
(defun opencortex-format-iso (iso-date)
"Convert 2026-04-07T10:00:00+00:00 to [2026-04-07 Tue 10:00]"
(let ((time (parse-time-string iso-date)))
(format-time-string "[%Y-%m-%d %a %H:%M]" (apply #'encode-time time))))
@@ -48,5 +48,5 @@ done
(dolist (line lines)
(let ((parts (split-string line "|")))
(when (= (length parts) 3)
(org-agent-inject-metadata (nth 0 parts) (nth 1 parts) (nth 2 parts))))))
(opencortex-inject-metadata (nth 0 parts) (nth 1 parts) (nth 2 parts))))))
#+end_src

View File

@@ -3,15 +3,15 @@
#+FILETAGS: :plan:emacs:ui:reasoning:
* Phase A: Demand (Verify State)
- Current state: `org-agent.el` combines final outputs and internal thoughts into a single `*org-agent-chat*` buffer.
- Goal: Create a dedicated `*org-agent-reasoning*` buffer for internal LLM logs. Add an interrupt hotkey (`C-c C-k`).
- Current state: `opencortex.el` combines final outputs and internal thoughts into a single `*opencortex-chat*` buffer.
- Goal: Create a dedicated `*opencortex-reasoning*` buffer for internal LLM logs. Add an interrupt hotkey (`C-c C-k`).
* Phase B: Blueprint (Surgical Edits)
- Modify `projects/org-agent/src/org-agent.el` to route `(:log :LOG)` messages to `*org-agent-reasoning*`.
- Add `org-agent-interrupt` command that sends `(:type :EVENT :payload (:sensor :interrupt))` to the kernel.
- Bind `C-c C-k` to `org-agent-interrupt` in the chat buffer.
- Open `*org-agent-reasoning*` as a side-window when `org-agent-chat` is called.
- Modify `projects/opencortex/src/opencortex.el` to route `(:log :LOG)` messages to `*opencortex-reasoning*`.
- Add `opencortex-interrupt` command that sends `(:type :EVENT :payload (:sensor :interrupt))` to the kernel.
- Bind `C-c C-k` to `opencortex-interrupt` in the chat buffer.
- Open `*opencortex-reasoning*` as a side-window when `opencortex-chat` is called.
* Phase C: Tester (Automated Proof)
- Test Emacs evaluation using batch mode to verify the syntax of the modified `org-agent.el`.
- Test Emacs evaluation using batch mode to verify the syntax of the modified `opencortex.el`.
- Open Emacs and connect to the live kernel to verify message routing.

View File

@@ -1,12 +1,12 @@
# Plan: Recursive Cognitive Kernel
## Objective
Implement a recursive `cognitive-loop` that allows the agent to chain multiple actions (tool calls) and observe results before finalising a response, similar to SOTA agents like Claude Code.
Implement a recursive `cognitive-cycle` that allows the agent to chain multiple actions (tool calls) and observe results before finalising a response, similar to SOTA agents like Claude Code.
## Key Files & Context
- `projects/org-agent/docs/README.org`: The primary source of truth for the kernel logic.
- `projects/org-agent/src/core.lisp`: Tangled kernel implementation.
- `projects/org-agent/src/symbolic.lisp`: Contains the `decide` logic.
- `projects/opencortex/docs/README.org`: The primary source of truth for the kernel logic.
- `projects/opencortex/src/core.lisp`: Tangled kernel implementation.
- `projects/opencortex/src/symbolic.lisp`: Contains the `decide` logic.
## Implementation Steps
@@ -14,11 +14,11 @@ Implement a recursive `cognitive-loop` that allows the agent to chain multiple a
- Define `*interrupt-flag*` and `*interrupt-lock*` in the kernel state.
- Update the `perceive` function to detect the `:interrupt` sensor stimulus and set the flag.
### 2. Recursive `cognitive-loop`
- Modify `cognitive-loop` to accept an optional `depth` parameter (default 0).
### 2. Recursive `cognitive-cycle`
- Modify `cognitive-cycle` to accept an optional `depth` parameter (default 0).
- Add a check at the beginning of the loop for `depth > 10` or `*interrupt-flag*`.
- Refactor the loop to capture the return value of `dispatch-action`.
- If the action was a "Tool Call" (any target except `:emacs` or `:system-message`) and produced a result, recursively call `cognitive-loop` with a new `:EVENT` containing that result.
- If the action was a "Tool Call" (any target except `:emacs` or `:system-message`) and produced a result, recursively call `cognitive-cycle` with a new `:EVENT` containing that result.
### 3. Actuator Harmonization
- Ensure `execute-system-action` (for `:eval`) returns meaningful results that can be fed back into the loop.
@@ -31,5 +31,5 @@ Implement a recursive `cognitive-loop` that allows the agent to chain multiple a
## Verification & Testing
- **Multi-turn Test**: In the chat, ask the agent to "Calculate the sum of 5+5 and then multiply it by 2 using eval".
- **Introspection Check**: Verify the `*org-agent-reasoning*` buffer shows the two distinct `eval` steps.
- **Introspection Check**: Verify the `*opencortex-reasoning*` buffer shows the two distinct `eval` steps.
- **Interrupt Test**: Trigger a long-running or recursive task and press `C-c C-k` in Emacs to verify the loop halts.

View File

@@ -5,19 +5,19 @@
#+STARTUP: content
* Overview
Break the cycle of chaotic debugging by performing a hard Git rollback to the last known stable state of the `org-agent` repository, surgically applying the verified fixes, and executing the Model Discovery connection test one strict step at a time.
Break the cycle of chaotic debugging by performing a hard Git rollback to the last known stable state of the `opencortex` repository, surgically applying the verified fixes, and executing the Model Discovery connection test one strict step at a time.
* Phase A: Purge & Reset (The Scientist)
** TODO 1. Hard Rollback
- Action: Execute `git reset --hard` and `git clean -fd` in `~/memex/projects/org-agent`.
- Action: Execute `git reset --hard` and `git clean -fd` in `~/memex/projects/opencortex`.
- Verification: Directory is clean of untracked files and uncommitted changes.
** TODO 2. Nuke the Lisp Cache
- Action: Delete `~/.cache/common-lisp/` and `~/.local/share/org-agent/quicklisp/cache/`.
- Action: Delete `~/.cache/common-lisp/` and `~/.local/share/opencortex/quicklisp/cache/`.
- Verification: The directories do not exist.
** TODO 3. Verify Environment
- Action: Read `~/.local/share/org-agent/.env`.
- Action: Read `~/.local/share/opencortex/.env`.
- Verification: Ensure `OPENROUTER_API_KEY` and `MEMEX_DIR` are correctly set without trailing quotes or comments.
* Phase B: Surgical Implementation (The Coder)
@@ -41,7 +41,7 @@ Break the cycle of chaotic debugging by performing a hard Git rollback to the la
* Phase D: Live Execution (The Sovereign)
** TODO 9. Foreground Boot Test
- Action: Start the `org-agent-server` daemon in the foreground for 10 seconds.
- Action: Start the `opencortex-server` daemon in the foreground for 10 seconds.
- Verification: Visually confirm that `org-skill-model-explorer` successfully jails and hot-loads.
** TODO 10. Live Model Discovery Test

View File

@@ -5,19 +5,19 @@
#+STARTUP: content
* Overview
Rigorous recovery of the =org-agent= kernel after a series of failed build loops.
Rigorous recovery of the =opencortex= kernel after a series of failed build loops.
* Phase A: Purge & Reset (The Scientist)
** TODO 1. Hard Git Reset
- Action: =git reset --hard= and =git clean -fd= in =~/memex/projects/org-agent=.
- Action: =git reset --hard= and =git clean -fd= in =~/memex/projects/opencortex=.
- Verification: =git status= must be clean.
** TODO 2. Nuke Lisp & Quicklisp Caches
- Action: Delete =~/.cache/common-lisp/= and =~/.local/share/org-agent/quicklisp/cache/=.
- Action: Delete =~/.cache/common-lisp/= and =~/.local/share/opencortex/quicklisp/cache/=.
- Verification: Directories must not exist.
** TODO 3. Verify Secure Environment
- Action: Check =~/.local/share/org-agent/.env=.
- Action: Check =~/.local/share/opencortex/.env=.
- Verification: Confirm =MEMEX_DIR= and =OPENROUTER_API_KEY= are correct.
* Phase B: Restoration (The Coder)

View File

@@ -3,10 +3,10 @@
#+FILETAGS: :plan:architecture:psf:orchestrator:
* Background & Motivation
The `cognitive-loop` pipeline (Consolidation V) established the functional gates (`perceive`, `neuro`, `consensus`, `decide`, `dispatch`). However, the `consensus-gate` remains a pass-through. Furthermore, the `org-agent` currently lacks the ability to formally verify GTD state transitions (Task Integrity) and hand off complex logic to background threads (Delegation). The Task Orchestrator integrates these three capabilities.
The `cognitive-cycle` pipeline (Consolidation V) established the functional gates (`perceive`, `neuro`, `consensus`, `decide`, `dispatch`). However, the `consensus-gate` remains a pass-through. Furthermore, the `opencortex` currently lacks the ability to formally verify GTD state transitions (Task Integrity) and hand off complex logic to background threads (Delegation). The Task Orchestrator integrates these three capabilities.
* Scope & Impact
- *Target Files:* `projects/org-agent/src/core.lisp`, `projects/org-agent/src/neuro.lisp`, `projects/org-agent/src/symbolic.lisp`.
- *Target Files:* `projects/opencortex/src/core.lisp`, `projects/opencortex/src/neuro.lisp`, `projects/opencortex/src/symbolic.lisp`.
- *Impact:* The Probabilistic Engine layer will spawn multiple threads to query providers simultaneously. Deterministic Engine will enforce GTD state integrity and manage sub-agent delegation.
- *Dependencies:* Requires `bordeaux-threads` for sub-agent management and the existing `org-gtd` v4.0 DAG.
@@ -21,7 +21,7 @@ The `cognitive-loop` pipeline (Consolidation V) established the functional gates
* Implementation Plan
** Phase C: Success (Testing)
- Draft `projects/org-agent/tests/orchestrator-test.lisp`.
- Draft `projects/opencortex/tests/orchestrator-test.lisp`.
- Assert that `consensus-gate` correctly handles 3 diverging proposals and selects the safest one.
- Assert that `task-integrity-check` rejects closing a parent task with active children.

View File

@@ -20,13 +20,13 @@
- Update `think` in `src/neuro.lisp` to automatically inject the tool belt into the system prompt.
** 4. Recursive Loop Integration
- Update `cognitive-loop` to recognize and execute tool calls.
- Update `cognitive-cycle` to recognize and execute tool calls.
* Phase D: Build (Implementation)
** 1. Registry & Macro
#+begin_src lisp
(in-package :org-agent)
(in-package :opencortex)
(defvar *cognitive-tools* (make-hash-table :test 'equal))
@@ -63,7 +63,7 @@ Refactor `think` to:
- Generate the tool belt prompt.
- Prepend it to the `system-prompt` in `ask-neuro`.
** 4. Integration with 'cognitive-loop'
** 4. Integration with 'cognitive-cycle'
Update the recursive check to:
- Handle `(:target :tool :action :call ...)` specifically.
- Look up the tool in `*cognitive-tools*`.