standards: add Architectural Intent + Testable Contract template to engineering lifecycle

org/programming-standards.org

@@ -7,6 +7,78 @@
 * Overview
 The *Engineering Standards Skill* defines the REPL-first engineering lifecycle and enforces technical invariants, including the **Commit-Before-Modify** rule and **Chaos-Driven Development**.
 
+** Architectural Intent + Testable Contract
+
+Every Org module must open with an ~* Architectural Intent~ section.
+This section is the machine-readable specification that tests are written
+against. A test that does not verify a stated intent is testing trivia.
+An intent without a test is aspirational.
+
+*** Template
+
+Place this before ~* Implementation~ in every Org file:
+
+#+begin_src org
+,* Architectural Intent
+
+[Prose: why this module exists, what problem it solves.]
+
+,** Contract
+
+The functions in this module guarantee the following:
+
+1. (function-name): accepts X, returns Y. Preserves invariant Z.
+2. (function-name): when given A, guarantees B (error, signal, or result).
+3. ...
+
+,** Boundaries
+
+What this module explicitly does NOT do, and where that responsibility
+lives instead.
+#+end_src
+
+The ~* Test Suite~ section at the bottom of the file lists each test
+with a cross-reference to which contract item it verifies:
+
+#+begin_src org
+,* Test Suite
+
+,** test-rejection (verifies Contract item 3)
+,** test-pass-through (verifies Contract item 1)
+#+end_src
+
+*** Example: ~system-diagnostics.org~
+
+#+begin_src org
+,* Architectural Intent
+
+The Diagnostics skill is the self-knowledge of Passepartout. It answers
+"Is everything working?" by probing external dependencies at startup.
+
+,** Contract
+
+1. (diagnostics-dependencies-check): probes PATH for every binary in
+   *diagnostics-binaries*. Returns T if all found, NIL if any is
+   missing. Side-effect: populates *doctor-missing-deps*.
+2. (diagnostics-env-check): validates XDG directories exist. Returns T
+   if all critical dirs present, NIL otherwise.
+3. (diagnostics-run-all): orchestrates 1-3. Returns a plist with
+   :deps, :env, :llm keys. Respects :auto-install nil.
+
+,** Boundaries
+
+- Does NOT fix missing dependencies — that is diagnostics-dependencies-install.
+- Does NOT start or stop LLM services — that is the provider layer.
+#+end_src
+
+*** Rules
+
+1. Every ~.org~ file with ≥1 ~defun~ MUST have an ~* Architectural Intent~ section.
+2. The ~** Contract~ section MUST list every public function.
+3. Every test in ~* Test Suite~ MUST reference a specific Contract item.
+4. If you change a function's signature, you MUST update its Contract item.
+5. These files are excluded (no defuns): ~core-manifest.org~, ~setup.org~.
+
 ** Engineering Lifecycle (Two-Track)
 
 The canonical workflow. Two tracks, not to be confused:
@@ -22,9 +94,9 @@ This track stays in Org. No code is written yet.
 4. If a bug: document investigation in Org before fixing (Org as thinking medium)
 
 **** Phase A: Test-First Design
-1. Write the success criteria in Org prose — what the function does, arguments, return value, rationale
-2. Write the FiveAM test in a ~#+begin_src lisp :tangle no~ block
-3. Tangle the test and evaluate in the REPL — confirm it fails (red)
+1. Write the success criteria as Contract items in the ~** Contract~ section
+2. Write the FiveAM test in the ~* Test Suite~ section at the bottom of the file, with a comment referencing which Contract item it verifies. Tests are embedded — no ~:tangle ../tests/...~ override.
+3. Tangle and evaluate in the REPL — confirm it fails (red)
 4. The failing test is the success criteria. Do not proceed to Track 2 until it exists and is red.
 
 *** Track 2 — REPL-First: Implementation, Iteration, Reflection (Phases B/C/D/E)