94 lines
7.9 KiB
Org Mode
94 lines
7.9 KiB
Org Mode
#+TITLE: OpenCortex MVP (v0.1.0) Specification & Release Plan
|
|
#+STARTUP: content
|
|
|
|
* Objective
|
|
Define detailed specifications for the OpenCortex MVP (v0.1.0). This MVP establishes the autonomous foundation and introduces a native Common Lisp Terminal User Interface (TUI) for improved UX, alongside a comprehensive release plan.
|
|
|
|
* 1. Core Architecture & Environment (Completed)
|
|
- *System Harness:* A minimal, un-brittle Common Lisp (SBCL) microkernel that orchestrates the Perceive -> Probabilistic -> Deterministic -> Dispatch pipeline.
|
|
- *Dual-Engine Cognition:*
|
|
- /Probabilistic Engine:/ The LLM gateway handling semantic translation, multi-modal ingestion, and intent parsing (supporting Anthropic, Gemini, Groq, OpenAI, and Ollama).
|
|
- /Deterministic Engine:/ The Lisp logical core that mathematically verifies LLM-proposed actions against system rules prior to execution.
|
|
- *Data Stores:*
|
|
- /Linguistic Substrate:/ Org-mode plaintext files acting as the universal Abstract Syntax Tree (AST) for both humans and the agent.
|
|
- /Lisp Memory:/ A live, threaded graph of Lisp objects representing the Memex in RAM for instant, token-efficient traversal (Sparse Trees).
|
|
- *Skill Architecture:* All agent capabilities are encapsulated in single-file Literate Programs (~org-skill-*.org~). They are topologically loaded, dynamically compiled, and hot-reloadable.
|
|
|
|
* 2. Mandatory Security & Containment (Completed)
|
|
- *Formal Verification Gate:* Evaluates actions before they hit the OS.
|
|
- /Path Confinement:/ Guarantees file writes are physically locked to the `~/memex/` root directory.
|
|
- /Network Exfiltration:/ Intercepts and blocks unauthorized external generic HTTP or socket requests.
|
|
- *System Policy Gate:* Enforces the "Zero-Bloat" and "Autonomy Above All" invariants.
|
|
- *Credentials Vault:* API keys and ~.env~ files are stored in a secure, masked Lisp enclave, rendering them invisible to the LLM's context window.
|
|
|
|
* 3. Autonomous Background Workers (Completed)
|
|
- *The Scribe (~org-skill-scribe.org~):* A distillation engine that periodically reads the chronological logs (e.g., daily journal files) and autonomously extracts concepts into permanent Zettelkasten notes.
|
|
- *The Gardener (~org-skill-gardener.org~):* A heartbeat-driven, idle process that continuously walks the memory graph. It automatically repairs broken internal links, infers missing metadata, and flags orphaned ideas for the user.
|
|
|
|
* 4. Native Terminal User Interface (UX Target)
|
|
- *Objective:* Eliminate raw ~stdout~ shell piping in favor of a rich, structured, and interactive Common Lisp TUI.
|
|
- *Library:* ~croatoan~ (A high-level CLOS wrapper for ncurses) will be used for rapid, robust UI development.
|
|
- *Layout:*
|
|
- /Main Viewport:/ A read-only, scrollable panel that renders Org-mode headlines, syntax-highlighted Lisp/Python code blocks, and system logs.
|
|
- /Input Box:/ A fixed, multi-line input area pinned to the bottom of the screen, supporting standard Readline keybindings.
|
|
- /Status Bar:/ A persistent bar at the top or bottom displaying the health and current activity of background workers (Scribe/Gardener) and memory usage.
|
|
- *Interactive Control (Slash Commands):*
|
|
- ~/help~: View system overview and command syntax.
|
|
- ~/clear~: Clear the viewport buffer.
|
|
- ~/skill-load <skill-name>~: Dynamically reload a modified Lisp skill into the active image.
|
|
- ~/exit~: Gracefully shut down the harness and exit the environment.
|
|
- ~/status~: Print diagnostic report (memory, git status, worker uptimes).
|
|
- ~/config~: Display active config/env vars (masking secrets).
|
|
- ~/search <query>~: Raw deterministic regex/vector search across the Memex.
|
|
- ~/commit~: Trigger Engineering Standard check, stage, and commit Memex state.
|
|
- *Refactoring:* Reroute the existing ~:cli~ actuator and inbound gateway to exclusively utilize the new TUI rendering engine.
|
|
|
|
* 5. Release & Publication Plan (v0.1.0)
|
|
- *Documentation:*
|
|
- ~USER_MANUAL.md~: A comprehensive guide on the one-liner installation (~opencortex.sh~), daily workflow, and navigating the Memex directory structure.
|
|
- ~CONTRIBUTING.md~: A guide to "Literate Granularity" engineering standards and creating new ~org-skill-*.org~ files.
|
|
- *Legal Finalization:*
|
|
- Assign the *AGPLv3* open-source license.
|
|
- Implement a broad *Contributor License Agreement (CLA)* process for external contributors to license rights back to the core project.
|
|
- Update ~LICENSE~ and finalize ~CHANGELOG.org~.
|
|
- *End-to-End Walkthrough:* Execute a clean-slate test of the installation script, boot sequence, environment variable parsing, and autonomous background worker triggers.
|
|
- *Marketing & Launch:* Migrate the canonical repository to GitHub (configure topics, badges, and issue templates). Record a high-fidelity GIF/video of the new TUI interaction and execute announcements on Hacker News, Reddit, and X/Twitter.
|
|
|
|
* 6. User-Centric End-to-End Test Plan
|
|
|
|
This section defines the precise workflow and expected user experience for the v0.1.0 MVP. It serves as the definitive manual testing script before release.
|
|
|
|
** Phase 1: The One-Liner Installation & Boot
|
|
- *Action:* The user executes the canonical curl-bash script: ~curl -fsSL https://raw.githubusercontent.com/gharbeia/opencortex/main/opencortex.sh | bash~
|
|
- *Expected Experience:*
|
|
1. The script detects the OS and installs any missing system dependencies (e.g., Docker, SBCL, Quicklisp).
|
|
2. It interactively prompts the user to enter as many LLM API keys as they choose to (e.g., Gemini, Anthropic, OpenAI). The user can skip this step and configure them later.
|
|
3. It asks the user for their existing folder structure and fills in the corresponding values (INBOX_DIR, DAILY_DIR, etc.) in ~.env.example~ to generate a valid ~.env~ file.
|
|
4. It compiles and launches the ~opencortex-server~ daemon in the background.
|
|
5. The user is greeted with a success message instructing them to run ~opencortex tui~.
|
|
|
|
** Phase 2: First Contact (The TUI Experience)
|
|
- *Action:* The user types ~opencortex tui~ in their terminal.
|
|
- *Expected Experience:*
|
|
1. The terminal clears and launches the Croatoan UI.
|
|
2. The *Status Bar* appears at the bottom, indicating: ~[Scribe: Idle] [Gardener: Sleeping]~.
|
|
3. The user types a natural language message in the input box: "Hello, what is my current Memex structure?" and presses Enter.
|
|
4. The input box clears, and the user's message appears in the main viewport.
|
|
5. A few seconds later, the agent responds with a formatted Org-mode list of the directories, demonstrating successful Lisp s-expression communication over the TCP socket and valid probabilistic reasoning.
|
|
|
|
** Phase 3: The Autonomous Subroutines
|
|
- *Action:* The user creates a messy text file in ~/memex/daily/YYYY-MM-DD.org~ with a scattered thought about a new project, then waits.
|
|
- *Expected Experience:*
|
|
1. Without any user prompting, the *Status Bar* updates to ~[Scribe: Distilling...]~.
|
|
2. A quiet log message appears in the TUI viewport: ~*System*: Scribe extracted 1 new Zettelkasten note.~
|
|
3. The user inspects ~/memex/notes/~ and finds a cleanly formatted, semantically tagged Org node containing the distilled thought.
|
|
4. The user intentionally breaks an Org-roam link in one of their notes. Minutes later, the Gardener awakens (~[Gardener: Auditing]~), and a log message appears indicating the link was repaired or flagged.
|
|
|
|
** Phase 4: Deterministic Actuation (Slash Commands)
|
|
- *Action:* The user types ~/status~ in the TUI.
|
|
- *Expected Experience:* The TUI instantly prints a diagnostic report showing memory usage, uptime, and git status, bypassing the LLM entirely.
|
|
- *Action:* The user types ~/commit~.
|
|
- *Expected Experience:* The system runs the Engineering Standard gate, stages all changes in ~/memex~, and creates a git commit. The TUI confirms success.
|
|
- *Action:* The user types ~/exit~.
|
|
- *Expected Experience:* The TUI client gracefully disconnects and closes, returning the user to their standard bash prompt. The ~opencortex-server~ continues running safely in the background.
|