passepartout/org/programming-standards.org

SKILL: Engineering Standards (org-skill-engineering-standards.org)

• Overview
  • Architectural Intent + Testable Contract
    • Template
    • Example: symbolic-diagnostics.org
    • Rules
  • Contract
• Implementation
  • Standards Enforcement
  • standards-lisp-verify
  • standards-lisp-format
  • Skill Registration

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:

* 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.

The * Test Suite section at the bottom of the file lists each test with a cross-reference to which contract item it verifies:

* Test Suite

** test-rejection (verifies Contract item 3)
** test-pass-through (verifies Contract item 1)

Example: symbolic-diagnostics.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.

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.

Contract

The standards skill itself guarantees:

1. (standards-git-clean-p dir): checks whether directory dir has uncommitted git changes. Returns T if clean, NIL if dirty. Runs git status --porcelain in the target directory.
2. (standards-lisp-verify code): validates Lisp code string for structural correctness. Delegates to lisp-syntax-validate.
3. (standards-lisp-format code): applies formatting conventions to Lisp code. Delegates to lisp-format.

Implementation

Standards Enforcement

;; REPL-VERIFIED: 2026-05-03T13:00:00

(in-package :passepartout)

(defun standards-git-clean-p (dir)
  "Checks if a directory has uncommitted changes."
  (let ((status (uiop:run-program (list "git" "-C" (namestring dir) "status" "--porcelain")
                                 :output :string
                                 :ignore-error-status t)))
    (string= "" (string-trim '(#\Space #\Newline #\Tab) status))))

standards-lisp-verify

;; REPL-VERIFIED: 2026-05-03T13:00:00

(defun standards-lisp-verify (code)
  "Enforces Lisp structural and semantic standards using utils-lisp."
  (let ((result (lisp-validate code :strict t)))
    (if (eq (getf result :status) :success)
        t
        (error (getf result :reason)))))

standards-lisp-format

;; REPL-VERIFIED: 2026-05-03T13:00:00

(defun standards-lisp-format (code)
  "Ensures Lisp code adheres to formatting standards."
  (lisp-format code))

#+end_src

Skill Registration

(defskill :passepartout-programming-standards
  :priority 100
  :trigger (lambda (ctx) (declare (ignore ctx)) nil))