REFAC: Shift terminology to Autonomy and harden CLI via socat
This commit is contained in:
@@ -1,18 +1,18 @@
|
||||
#+TITLE: v0.1.0 Launch & Marketing Plan
|
||||
#+AUTHOR: Amr
|
||||
#+FILETAGS: :marketing:release:psf:
|
||||
#+FILETAGS: :marketing:release:autonomy:
|
||||
#+STARTUP: content
|
||||
|
||||
* Overview
|
||||
With the v0.1.0 "Sovereign MVP" released, the goal is to leverage GitHub's social graph to build a community of early adopters, contributors, and power users who resonate with the "Thin Harness, Fat Skills" and "Local-First" philosophy.
|
||||
With the v0.1.0 "Autonomous MVP" released, the goal is to leverage GitHub's social graph to build a community of early adopters, contributors, and power users who resonate with the "Thin Harness, Fat Skills" and "Local-First" philosophy.
|
||||
|
||||
* 1. Licensing Strategy
|
||||
Before wide promotion, the project's license must align with its goals.
|
||||
- **MIT License (Current):** Maximum adoption, frictionless for developers to embed in their own tools. Good for rapid growth.
|
||||
- **GPLv3 / AGPLv3:** Enforces copyleft. Ensures any modifications or integrations by corporations must remain open-source. Protects the "Sovereign" ethos from proprietary enclosure.
|
||||
- **GPLv3 / AGPLv3:** Enforces copyleft. Ensures any modifications or integrations by corporations must remain open-source. Protects the "Autonomous" ethos from proprietary enclosure.
|
||||
- **Dual Licensing:** Open-source for individuals, commercial license for enterprise usage (if monetization is a future goal).
|
||||
|
||||
*Decision Needed:* Do we stick with MIT, or switch to a copyleft license (AGPL) to protect the sovereign nature of the project?
|
||||
*Decision Needed:* Do we stick with MIT, or switch to a copyleft license (AGPL) to protect the autonomous nature of the project?
|
||||
|
||||
* 2. The GitHub Migration & Setup
|
||||
To maximize visibility, the repository must be optimized for GitHub's ecosystem.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
#+TITLE: Quickstart Guide: The Road to Sovereignty
|
||||
#+TITLE: Quickstart Guide: The Road to Autonomousty
|
||||
#+AUTHOR: Amr
|
||||
#+DATE: [2026-04-11 Sat]
|
||||
#+FILETAGS: :quickstart:onboarding:guide:
|
||||
@@ -13,7 +13,7 @@ Before launching the harness, ensure your host environment has:
|
||||
- **Emacs (Optional)**: For the full literate experience via ~org-agent.el~.
|
||||
|
||||
* 3. Installation & Enclosure
|
||||
** Step 1: Clone the Sovereignty
|
||||
** Step 1: Clone the Autonomousty
|
||||
#+begin_src bash
|
||||
git clone https://github.com/amr/org-agent.git
|
||||
cd org-agent
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
#+TITLE: Root Cause Analysis: Micro-Loader & Deterministic Boot Sequence
|
||||
#+DATE: 2026-04-11
|
||||
#+FILETAGS: :rca:boot:loader:topological-sort:psf:
|
||||
#+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.
|
||||
@@ -31,7 +31,7 @@ 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. PSF Mandate Alignment
|
||||
* 4. org-agent Mandate Alignment
|
||||
** Evolutionary Kernel
|
||||
The boot sequence is now a verifiable, mathematical process rather than a side-effect of filesystem organization.
|
||||
** Literate Granularity
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
#+TITLE: Root Cause Analysis: Deterministic Engine Bouncer & Authorization Gate
|
||||
#+DATE: 2026-04-11
|
||||
#+FILETAGS: :rca:bouncer:authorization:psf:security:
|
||||
#+FILETAGS: :rca:bouncer:authorization:autonomy:security:
|
||||
|
||||
* Executive Summary
|
||||
Implemented the "Planning Mode" Bouncer to intercept high-risk Probabilistic Engine proposals (e.g., shell commands, Lisp evaluation). The system now forces these actions into an asynchronous "Flight Plan" Org node for manual Sovereign approval, fulfilling the "everything is a node" and high-integrity mandates.
|
||||
Implemented the "Planning Mode" Bouncer to intercept high-risk Probabilistic Engine proposals (e.g., shell commands, Lisp evaluation). The system now forces these actions into an asynchronous "Flight Plan" Org node for manual Autonomous approval, fulfilling the "everything is a node" and high-integrity mandates.
|
||||
|
||||
* 1. Issue: Automated High-Risk Execution
|
||||
** Symptoms
|
||||
@@ -20,13 +20,13 @@ Architecture gap. The system lacked an authorization state between "Safe" and "E
|
||||
|
||||
* 2. Design Decision: Org-native Approval
|
||||
** Requirement
|
||||
Align with "Homoiconic Memory" and "Lisp Machine Sovereignty".
|
||||
Align with "Homoiconic Memory" and "Lisp Machine Autonomousty".
|
||||
** Selected Path
|
||||
State-Based Approval (Org-native).
|
||||
- *Pros:* Auditable, asynchronous, utilizes existing Org-mode workflows.
|
||||
- *Cons:* Slightly more latency than an interactive prompt.
|
||||
** Alignment
|
||||
Ensures that the agent's "Flight Plans" are first-class citizens in the Memex, allowing the Sovereign to review and approve them using standard GTD tools.
|
||||
Ensures that the agent's "Flight Plans" are first-class citizens in the Memex, allowing the Autonomous to review and approve them using standard GTD tools.
|
||||
|
||||
* 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.
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
#+TITLE: Root Cause Analysis: Lisp-Native Formal Verification Gate
|
||||
#+DATE: 2026-04-11
|
||||
#+FILETAGS: :rca:security:formal-verification:psf:
|
||||
#+FILETAGS: :rca:security:formal-verification:autonomy:
|
||||
|
||||
* Executive Summary
|
||||
Implemented a Lisp-Native Deterministic Prover to replace heuristic whitelisting with formal security invariants. This ensures that every high-impact action (shell, file I/O) is mathematically proven safe against the Sovereign's core mandates.
|
||||
Implemented a Lisp-Native Deterministic Prover to replace heuristic whitelisting with formal security invariants. This ensures that every high-impact action (shell, file I/O) is mathematically proven safe against the Autonomous's core mandates.
|
||||
|
||||
* 1. Architectural Shift: Native vs. External
|
||||
** Issue
|
||||
@@ -25,7 +25,7 @@ Incorrect assumption about the Quicklisp system name vs. the package name. The l
|
||||
- **Path Confinement:** Deterministically proves that any file operation or absolute path in a shell command is strictly within the `/home/user/memex` root.
|
||||
- **No Network Exfiltration:** Prevents the shell from invoking common exfiltration tools (`nc`, `ssh`, etc.) by inspecting the parsed command structure.
|
||||
|
||||
* 4. PSF Mandate Alignment
|
||||
* 4. org-agent Mandate Alignment
|
||||
** Soundness over Heuristics
|
||||
By moving to formal invariants, we have moved from "blacklisting bad things" to "proving safety." Any action that cannot be proven to satisfy all invariants is denied by default.
|
||||
** Literate Granularity
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
#+TITLE: Root Cause Analysis: Matrix Gateway & Communication Track Completion
|
||||
#+DATE: 2026-04-11
|
||||
#+FILETAGS: :rca:gateway:matrix:chat:psf:
|
||||
#+FILETAGS: :rca:gateway:matrix:chat:autonomy:
|
||||
|
||||
* Executive Summary
|
||||
Successfully implemented the third and final external communication channel (Matrix) for Org-agent v1.0. Resolved integration issues related to case-sensitivity in JSON keys and strict header requirements in `dexador`.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
#+TITLE: Root Cause Analysis: Signal Gateway & Multi-Channel Chat
|
||||
#+DATE: 2026-04-11
|
||||
#+FILETAGS: :rca:gateway:signal:chat:psf:
|
||||
#+FILETAGS: :rca:gateway:signal:chat:autonomy:
|
||||
|
||||
* Executive Summary
|
||||
Successfully implemented the second external communication channel (Signal) using `signal-cli`. Further hardened the multi-channel chat logic and resolved JSON mapping discrepancies between Common Lisp and external CLI outputs.
|
||||
@@ -22,7 +22,7 @@ Unlike Telegram's HTTP API, Signal requires a local binary (`signal-cli`).
|
||||
** Security
|
||||
The system uses the pre-configured Signal account `+13322690326` discovered in the user's memex.
|
||||
|
||||
* 3. Alignment with PSF Mandates
|
||||
* 3. Alignment with org-agent Mandates
|
||||
** Literate Granularity
|
||||
Strictly adhered to the "one definition per block" mandate throughout the new `org-skill-gateway-signal.org` file.
|
||||
** Verification
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
#+TITLE: Root Cause Analysis: Telegram Gateway & Channel-Aware Chat
|
||||
#+DATE: 2026-04-11
|
||||
#+FILETAGS: :rca:gateway:telegram:chat:psf:
|
||||
#+FILETAGS: :rca:gateway:telegram:chat:autonomy:
|
||||
|
||||
* Executive Summary
|
||||
Successfully implemented the first external communication channel (Telegram) and decoupled the Chat Agent from its Emacs-centric roots. Resolved significant load-order and dependency issues identified during integration.
|
||||
@@ -32,8 +32,8 @@ Misinterpretation of the `UIOP` API. `setenv` is not a standard export; the port
|
||||
** Resolution
|
||||
Updated all test environment setup to use the `setf` accessor.
|
||||
|
||||
* 4. PSF Mandate Alignment
|
||||
** Sovereign Boundary
|
||||
* 4. org-agent Mandate Alignment
|
||||
** Autonomous Boundary
|
||||
By moving the Telegram API logic to a user-space skill and communicating with the core via standard stimuli, we have respected the microkernel boundary.
|
||||
** Homoiconic Memory
|
||||
All Telegram interactions are now logged as `:chat-message` events, ensuring the agent's history is unified regardless of the platform.
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
#+TITLE: Root Cause Analysis: Containerized Infrastructure (Docker)
|
||||
#+DATE: 2026-04-11
|
||||
#+FILETAGS: :rca:docker:deployment:infrastructure:psf:
|
||||
#+FILETAGS: :rca:docker:deployment:infrastructure:autonomy:
|
||||
|
||||
* Executive Summary
|
||||
Standardized the `org-agent` execution environment by creating a production-grade Docker infrastructure. This ensures that all system dependencies, including the Lisp runtime and external binaries like `signal-cli`, are locked down and portable.
|
||||
|
||||
* 1. Architectural Intent: The "Clean Room" Model
|
||||
** Problem
|
||||
The `org-agent` was relying on host-local binaries (`sbcl`, `signal-cli`) and manually configured Quicklisp dists. This made deployment to other environments (e.g., a VPS or a Sovereign Home Server) fragile and prone to version drift.
|
||||
The `org-agent` was relying on host-local binaries (`sbcl`, `signal-cli`) and manually configured Quicklisp dists. This made deployment to other environments (e.g., a VPS or a Autonomous Home Server) fragile and prone to version drift.
|
||||
** Solution
|
||||
1. **Dockerfile:** Created a multi-step build process that installs Debian Bookworm, SBCL, Java, and `signal-cli 0.14.0`.
|
||||
2. **Pre-Caching:** The build process triggers a `ql:quickload` of the `:org-agent` system, ensuring all Lisp dependencies are pre-downloaded and stored in the image layer, drastically reducing startup time.
|
||||
@@ -15,11 +15,11 @@ The `org-agent` was relying on host-local binaries (`sbcl`, `signal-cli`) and ma
|
||||
|
||||
* 2. Volume Mapping & Persistence
|
||||
** Strategy
|
||||
To maintain the "Sovereign" mandate, the agent's code is isolated, but its memory (the `memex`) remains on the host.
|
||||
To maintain the "Autonomous" mandate, the agent's code is isolated, but its memory (the `memex`) remains on the host.
|
||||
- **Mapping:** `../..` (host) -> `/memex` (container).
|
||||
- **State:** Created a named Docker volume `signal-state` to ensure that `signal-cli` identities and cryptographic keys survive container restarts and image updates.
|
||||
|
||||
* 3. Alignment with PSF Mandates
|
||||
* 3. Alignment with org-agent Mandates
|
||||
** Evolutionary Completion
|
||||
By moving to Docker, we have achieved "Evolutionary Completion" for the deployment track. The system is no longer a collection of scripts; it is a deployable appliance.
|
||||
** Documentation
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
#+TITLE: Root Cause Analysis: Asynchronous Lisp Repair Syntax Gate
|
||||
#+DATE: 2026-04-11
|
||||
#+FILETAGS: :rca:lisp:repair:decoupling:architecture:psf:
|
||||
#+FILETAGS: :rca:lisp:repair:decoupling:architecture:autonomy:
|
||||
|
||||
* Executive Summary
|
||||
Reimplemented the `org-skill-lisp-repair` to align with the "Sovereign Boundary" mandate. The previously synchronous, core-blocking repair logic has been replaced with an asynchronous, event-driven architecture using the Reactive Signal Pipeline.
|
||||
Reimplemented the `org-skill-lisp-repair` to align with the "Autonomous Boundary" mandate. The previously synchronous, core-blocking repair logic has been replaced with an asynchronous, event-driven architecture using the Reactive Signal Pipeline.
|
||||
|
||||
* 1. Issue: Core Bloat & Synchronous Coupling
|
||||
** Symptoms
|
||||
@@ -22,8 +22,8 @@ Mismatched expectations of signal nesting. The skill expected the code at `(getf
|
||||
** Resolution
|
||||
Updated the deterministic logic to correctly traverse the nested signal structure: `(getf (getf context :candidate) :payload)`.
|
||||
|
||||
* 3. PSF Mandate Alignment
|
||||
** Sovereign Boundary
|
||||
* 3. org-agent Mandate Alignment
|
||||
** Autonomous Boundary
|
||||
The core is now strictly a parser. Repair is an optional, user-space service.
|
||||
** Reactive Signal Pipeline
|
||||
Leveraged the pipeline's ability to re-inject `EVENT` signals to flatten the recursion of the repair loop.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
#+TITLE: Root Cause Analysis: Playwright-Python Bridge (High-Fidelity Browsing)
|
||||
#+DATE: 2026-04-11
|
||||
#+FILETAGS: :rca:intelligence:browsing:automation:psf:
|
||||
#+FILETAGS: :rca:intelligence:browsing:automation:autonomy:
|
||||
|
||||
* Executive Summary
|
||||
Successfully implemented a high-fidelity browsing bridge using Playwright and Python. This allows the `org-agent` to interact with modern, JavaScript-rendered web applications that were previously inaccessible via simple HTTP clients.
|
||||
@@ -28,7 +28,7 @@ Created the `:browser` cognitive tool, which exposes three primary capabilities
|
||||
- **Extraction:** Targeted text retrieval via CSS selectors.
|
||||
- **Vision:** Base64-encoded screenshot capture for future multimodal processing.
|
||||
|
||||
* 4. PSF Mandate Alignment
|
||||
* 4. org-agent Mandate Alignment
|
||||
** Zero-Bloat (Managed)
|
||||
While adding Playwright increases the image size, it is a "Complexity Earned" trade-off that dramatically expands the agent's capability frontier.
|
||||
** Literate Granularity
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
#+TITLE: Root Cause Analysis: Individual Provider Track Verification
|
||||
#+DATE: 2026-04-11
|
||||
#+FILETAGS: :rca:providers:llm:testing:psf:
|
||||
#+FILETAGS: :rca:providers:llm:testing:autonomy:
|
||||
|
||||
* Executive Summary
|
||||
Verified the unified LLM gateway implementation for all 6 individual provider tracks (Anthropic, Gemini, Groq, OpenAI, OpenRouter, Ollama). Identified and resolved critical parsing failures in the Gemini track and integration gaps in the system build definition.
|
||||
@@ -30,7 +30,7 @@ Gemini requests failed with "API Key missing" even when environment variables we
|
||||
** Resolution
|
||||
Updated `vault-get-secret` to map both `:gemini` and `:gemini-api` to the same `GEMINI_API_KEY` environment variable.
|
||||
|
||||
* 4. PSF Mandate Alignment
|
||||
* 4. org-agent Mandate Alignment
|
||||
** Invariant Check
|
||||
- *High-Integrity Memory:* All individual provider tracks are now backed by automated unit tests (`llm-gateway-tests.lisp`).
|
||||
- *Literate Programming:* Updated `org-skill-llm-gateway.org` to reflect the improved `get-nested` utility.
|
||||
|
||||
@@ -29,9 +29,9 @@ Refactored `org-agent.asd` to use a **Flat Component Structure**.
|
||||
- *After:* `:components ((:file "src/package") ...)`
|
||||
This eliminates unnecessary nesting levels and drastically reduces the surface area for syntax errors.
|
||||
|
||||
* 3. PSF Mandate Alignment
|
||||
* 3. org-agent Mandate Alignment
|
||||
** Invariant Check
|
||||
- *Lisp Machine Sovereignty:* Verification utilized hot-reloading (`load-skill-from-org`) without restarting the SBCL image.
|
||||
- *Lisp Machine Autonomousty:* Verification utilized hot-reloading (`load-skill-from-org`) without restarting the SBCL image.
|
||||
- *Literate Programming:* Updated `org-skill-self-fix.org` to match the finalized `self-fix.lisp` logic.
|
||||
- *Institutional Memory:* This RCA documents the decision to flatten the `.asd` structure to prevent future "Parenthesis Hell" incidents.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
#+TITLE: Root Cause Analysis: Shell Actuator Security Hardening
|
||||
#+DATE: 2026-04-11
|
||||
#+FILETAGS: :rca:security:shell:injection:psf:
|
||||
#+FILETAGS: :rca:security:shell:injection:autonomy:
|
||||
|
||||
* Executive Summary
|
||||
During the formal verification of the `org-skill-shell-actuator`, a critical command injection vulnerability was identified and patched. The previous implementation relied on a naive whitelist check that could be bypassed using shell metacharacters.
|
||||
@@ -23,7 +23,7 @@ The `execute-shell-safely` function only checked the first space-delimited word
|
||||
** Resolution
|
||||
Added the `in-package` header to `shell-logic.lisp`.
|
||||
|
||||
* 3. PSF Mandate Alignment
|
||||
* 3. org-agent Mandate Alignment
|
||||
** Invariant Check
|
||||
- *High-Integrity Memory:* The shell actuator is now formally verified with 4 new unit tests covering whitelist enforcement and injection blocking.
|
||||
- *Literate Programming:* Updated `org-skill-shell-actuator.org` Phase A and Build sections to reflect the hardened logic.
|
||||
|
||||
@@ -23,7 +23,7 @@ Selected "Majority Rules" over "First-to-Finish".
|
||||
- *Pros:* Higher accuracy, mathematically consistent.
|
||||
- *Cons:* Slower (latency limited by the slowest provider).
|
||||
** Invariant Alignment
|
||||
Aligns with PSF Mandate 4 (Radical Transparency) and Invariant 2 (Technical Mastery) by ensuring decisions are auditable and consistent across multiple brains.
|
||||
Aligns with org-agent Mandate 4 (Radical Transparency) and Invariant 2 (Technical Mastery) by ensuring decisions are auditable and consistent across multiple brains.
|
||||
|
||||
* 3. Design Decision: Task Integrity Gate
|
||||
** Requirement
|
||||
@@ -33,7 +33,7 @@ Added `task-integrity-check` in `deterministic.lisp`.
|
||||
** Invariant Alignment
|
||||
Enforces the "High-Integrity Memory" mandate by ensuring the Org-mode AST remains semantically valid according to GTD rules (e.g., no orphaned active tasks).
|
||||
|
||||
* 4. PSF Mandate Violations during Session (Corrected)
|
||||
* 4. org-agent Mandate Violations during Session (Corrected)
|
||||
** Violations
|
||||
1. Editing without prior commit.
|
||||
2. Direct `.lisp` edits vs Literate Org tangling.
|
||||
@@ -45,4 +45,4 @@ Enforces the "High-Integrity Memory" mandate by ensuring the Org-mode AST remain
|
||||
|
||||
* 5. Permanent Learnings
|
||||
- *Check Exports:* Always verify that symbols exported in `package.lisp` have a corresponding definition in the literate source.
|
||||
- *Strict PSF Mode:* Enable a pre-save hook or agent check to ensure all edits are performed within `#+begin_src` blocks in Literate Org files to avoid synchronization debt.
|
||||
- *Strict org-agent Mode:* Enable a pre-save hook or agent check to ensure all edits are performed within `#+begin_src` blocks in Literate Org files to avoid synchronization debt.
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
#+TITLE: User Experience (UX) Journey
|
||||
#+AUTHOR: Amr
|
||||
#+FILETAGS: :ux:design:psf:
|
||||
#+FILETAGS: :ux:design:autonomy:
|
||||
#+STARTUP: content
|
||||
|
||||
* Overview
|
||||
This document traces the intended User Experience (UX) journey for the ~org-agent~. It serves as a living design document to ensure that architectural decisions align with a frictionless, sovereign, and intuitive user interaction model.
|
||||
This document traces the intended User Experience (UX) journey for the ~org-agent~. It serves as a living design document to ensure that architectural decisions align with a frictionless, autonomous, and intuitive user interaction model.
|
||||
|
||||
* 1. The Zero-to-One Experience (Onboarding)
|
||||
** Goal
|
||||
@@ -23,7 +23,7 @@ The script verifies Docker presence and then launches an interactive prompt befo
|
||||
3. *Neural Provider:* "Select your primary neural provider [Gemini/OpenRouter/Anthropic/OpenAI]" -> Configures API Keys.
|
||||
4. *Data Gravity:* "Where is your Memex located?" -> Maps the host directory to the Docker container.
|
||||
|
||||
*Outcome:* The `.env` is generated, core skills are seeded into the user's Memex, and `docker-compose up -d` launches the daemon in the background. The user sees: /"Booting your sovereign brain in the background..."/
|
||||
*Outcome:* The `.env` is generated, core skills are seeded into the user's Memex, and `docker-compose up -d` launches the daemon in the background. The user sees: /"Booting your autonomous brain in the background..."/
|
||||
|
||||
* 2. The First Contact (The CLI Gateway)
|
||||
** Goal
|
||||
@@ -42,7 +42,7 @@ This opens a slick, colorful interactive terminal session:
|
||||
> Agent: You currently have 3 active projects:
|
||||
> 1. Org-agent v1.0
|
||||
> 2. Home Renovation
|
||||
> 3. Read 'The Sovereign Individual'
|
||||
> 3. Read 'The Autonomous Individual'
|
||||
#+end_example
|
||||
|
||||
** Behind the Scenes
|
||||
|
||||
Reference in New Issue
Block a user