From 94b939f61a950cd46c89c1111fe0c09fd070411a Mon Sep 17 00:00:00 2001 From: Amr Gharbeia Date: Tue, 5 May 2026 09:08:28 -0400 Subject: [PATCH] docs: enforce TDD red-green-refactor discipline in CONTRIBUTING --- docs/CONTRIBUTING.org | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/docs/CONTRIBUTING.org b/docs/CONTRIBUTING.org index 8b1af0e..bb1bf76 100644 --- a/docs/CONTRIBUTING.org +++ b/docs/CONTRIBUTING.org @@ -6,6 +6,23 @@ * 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. @@ -37,8 +54,9 @@ All inter-process communication occurs via the Unified Envelope. Do not use lega - Ensure generated `:REQUEST` messages include a mandatory `:TARGET` field. * Pull Request Process -1. Ensure your working tree is clean. -2. Write tests for your skill in `tests/`. -3. Tangle all files. -4. Run the test suite: `sbcl --eval "(asdf:test-system :passepartout)"`. -5. Submit a PR outlining the architectural intent and the specific Literate changes. \ No newline at end of file +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. \ No newline at end of file