#+TITLE: SKILL: Engineering Standards (org-skill-engineering-standards.org)
#+AUTHOR: Agent
#+FILETAGS: :system:engineering:chaos:
#+DEPENDS_ON: org-skill-utils-lisp
#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/lisp/programming-standards.lisp

* 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: ~symbolic-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.

** 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
#+begin_src lisp
(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))))

#+end_src
** standards-lisp-verify
;; REPL-VERIFIED: 2026-05-03T13:00:00
#+begin_src lisp
(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)))))

#+end_src
** standards-lisp-format
;; REPL-VERIFIED: 2026-05-03T13:00:00
#+begin_src lisp
(defun standards-lisp-format (code)
  "Ensures Lisp code adheres to formatting standards."
  (lisp-format code))
#+end_src
#+end_src

** Skill Registration
#+begin_src lisp
(defskill :passepartout-programming-standards
  :priority 100
  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
#+end_src