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
4.3 KiB
4.3 KiB
SKILL: Engineering Standards (org-skill-engineering-standards.org)
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
- Every
.orgfile with ≥1defunMUST have an* Architectural Intentsection. - The
** Contractsection MUST list every public function. - Every test in
* Test SuiteMUST reference a specific Contract item. - If you change a function's signature, you MUST update its Contract item.
Contract
The standards skill itself guarantees:
- (standards-git-clean-p dir): checks whether directory
dirhas uncommitted git changes. Returns T if clean, NIL if dirty. Runsgit status --porcelainin the target directory. - (standards-lisp-verify code): validates Lisp code string for
structural correctness. Delegates to
lisp-syntax-validate. - (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))