amr/passepartout
1
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
afe1ad6ed41ad280ea1db45a1f7ec08d1a13147a
passepartout/docs/MVP_SPEC.org

7.7 KiB
Raw Blame History

OpenCortex MVP (v0.1.0) Specification & Release Plan

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 for their primary LLM API key (e.g., Gemini or Anthropic) and Memex path.
    3. It generates a valid .env file and provisions the directory structure (/memex/inbox, /memex/daily, etc.).
    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.
Reference in New Issue View Git Blame Copy Permalink