Amr Gharbeia
639bc348d9
Some checks failed
Deploy (Gitea) / deploy (push) Failing after 2s
- Remove system-prompt-augment mechanism, introduce *standing-mandates* - Fix false token-overhead claims in DESIGN_DECISIONS + ROADMAP - Update security vector count 9-10 across all docs and dispatcher docstring - Rewrite README with agent section, soften aspirational claims - Register 10 cognitive tools in programming-tools.org with test suite - Enforce NO-HARDCODED-CONSTANTS in .env.example - ROADMAP: mark v0.3.x patches DONE, add LOGBOOKs, mark releases - AGENTS.md: rewrite compact (180 to 50 lines), move refs to CONTRIBUTING - Normalize org tangle directives to file-level PROPERTY inheritance
117 lines
4.7 KiB
Org Mode
117 lines
4.7 KiB
Org Mode
#+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)
|