Amr Gharbeia
b9a4318ef8
- Changed all 50 org file :tangle targets from ../lisp/ to ~/.local/share/passepartout/lisp/ (XDG data dir) - Removed 49 generated .lisp files from project lisp/ directory - Removed tests/system-integration-tests.lisp (generated) - Removed lisp/*.fasl (compiled, stale) - Updated core-manifest.org to tangle .asd to XDG root - Remapped quicklisp symlink: local-projects/passepartout → XDG TUI fixes in channel-tui-main.org: - Removed with-raw-terminal (stty raw breaks fd 0 reads in this SBCL) - Use cat subprocess + pipe for keyboard input (via :input :interactive) - Blocking read-char on pipe with with-timeout 0.1s for daemon processing - Key events queued via drain-queue alongside daemon messages - Full dialog key routing (Escape, Up/Down, Enter, filters, Backspace) - SIGWINCH resize handling - Post-handshake backend-size re-query - Daemon version in status bar (was v0.5.0 hardcoded) - Handshake version stored in state, no add-msg - :daemon-version and :size-queried in state plist - view-status uses draw-rect for background - Test section gated with #+passepartout-tests
133 lines
4.3 KiB
Org Mode
133 lines
4.3 KiB
Org Mode
#+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 |