Amr Gharbeia
8fd56dece3
Phase 1 — dedup + hardening (~9 items): - Remove duplicate *skill-registry* defvar from core-skills - Merge *backend-registry* into *probabilistic-backends*, delete backend-register - Remove inject-stimulus alias, standardize on stimulus-inject - Add pre-eval sandbox (skill-source-scan) blocks restricted symbols before eval - Remove dead plist-get function; remove duplicate json-alist-to-plist export - Fix read-framed-message whitespace DoS (4096-iteration max) - Add *read-eval* nil to dispatcher-approvals-process read-from-string (RCE) - Add test-op to ASDF; update .asd version 0.4.3→0.7.2 Phase 2 — prose + contracts + reorder: - Split ROADMAP: 2623→1089 lines (TODO only), CHANGELOG: 260→1528 lines (full DONE history, 14 versions reverse chron) - Add Contracts + Overview to 6 channel files + embedding-native + programming-standards + symbolic-scope - Reorder 28 .org files: Contract → Test Suite → Implementation (TDD order) - Add 7-phase inline prose to think() in core-reason - Expand USER_MANUAL: 183→461 lines (10 new sections) Phase 3 — decomposition + export organization: - Decompose think() into think-assemble-prompt, think-call-llm, think-parse-response orchestrator - Organize 188 exports into 16 grouped sections by module Phase 4 — budget enforcement + error protocol: - Per-session budget enforcement (SESSION_BUDGET_USD env var, budget-exhausted-p, guard in think-call-llm) - Error condition hierarchy (6 conditions: pipeline-error, llm-error, gate-error, budget-error, protocol-error) - Restarts in loop-process: skip-signal, use-fallback, abort-pipeline
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 ../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 |