passepartout/docs/CONTRIBUTING.org

Contributing to Passepartout

• Philosophy
• TDD Discipline (Red-Green-Refactor)
• Literate Granularity
• Skill Creation Standard
• The Unified Envelope (Communication Protocol)
• Pull Request Process

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)

All code changes MUST follow this cycle:

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

For existing code that lacks tests: write a characterization test that captures current behavior as the spec. Then refactor.

No test may be committed without proof it was first run to failure.

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.

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 "Bouncer" pattern).

Example Registration:

(defskill :skill-example
  :priority 100
  :trigger (lambda (ctx) ...)
  :probabilistic nil
  :deterministic (lambda (action ctx) ...))

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.

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.