passepartout: v0.4.1 Design Cleanup

- 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

docs/CONTRIBUTING.org

@@ -6,57 +6,111 @@
 * 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".
 
-* TDD Discipline (Red-Green-Refactor)
+* Development Workflow
 
-All code changes MUST follow this cycle:
+The full development cycle is described in ~AGENTS.md~. In summary:
 
-1. *Write a failing test* — capture the desired behavior as a FiveAM test
-   in a =* Test Suite= section within the relevant =.org= file
-2. *Prove it fails* — run =sbcl --eval "(asdf:test-system :passepartout)"=
-   and confirm the new test fails (RED) before writing implementation
-3. *Write the code* — modify the implementation in the same =.org= file
-4. *Prove it passes* — run the test suite again, confirm GREEN
-5. *Reflect* — ensure the test and code are both in the =.org= literate source
+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
 
-For *existing code* that lacks tests: write a characterization test that
-captures current behavior as the spec. Then refactor.
+* Literate Programming
 
-No test may be committed without proof it was first run to failure.
+~.org~ files in ~org/~ are the source of truth. ~lisp/~ files are generated by ~org-babel-tangle~.
 
-* Literate Granularity
-We strictly adhere to Literate Programming using Org-mode.
-- *Never* edit `.lisp` files in `src/` directly.
-- Modify the corresponding `.org` files in the `literate/` or `skills/` directories.
-- Run `org-babel-tangle` to generate the source code.
-- Every architectural decision, constraint, and implementation detail must be documented alongside the code in the `.org` file.
+- 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
-Skills are the building blocks of Passepartout. They reside in the `skills/` directory.
 
-A skill must define:
-1. *Trigger*: A lambda determining if the skill should activate based on the context.
-2. *Probabilistic Gate*: Optional. Generates a prompt for the LLM.
-3. *Deterministic Gate*: A hardcoded Lisp function that guarantees safety or executes side-effects (the Dispatcher pattern).
+A skill is a =.org= file in =org/= that defines:
 
-Example Registration:
+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 :skill-example
+(defskill :passepartout-example
   :priority 100
   :trigger (lambda (ctx) ...)
-  :probabilistic nil
+  :probabilistic (lambda (ctx) ...)
   :deterministic (lambda (action ctx) ...))
 #+end_src
 
-* The Unified Envelope (Communication Protocol)
-All inter-process communication occurs via the Unified Envelope. Do not use legacy specific types like `:CHAT`.
-- Always use semantic types: `:REQUEST`, `:EVENT`, `:RESPONSE`, `:STATUS`, `:LOG`.
-- Include routing metadata in the `:META` block (e.g., `(:SOURCE :TUI)`).
-- Ensure generated `:REQUEST` messages include a mandatory `:TARGET` field.
+* Project Structure
 
-* Pull Request Process
-1. Choose an Org file and write a failing test in its =* Test Suite= section.
-2. Tangle and run to confirm RED (the test fails).
-3. Write the implementation in the same Org file, tangle, run to confirm GREEN.
-4. Ensure your working tree is clean.
-5. Run the full test suite: =sbcl --eval "(asdf:test-system :passepartout)"=.
-6. Submit a PR outlining the architectural intent and the specific Literate changes.
+| 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)