Amr Gharbeia
924bf8f479
Some checks failed
Deploy (Gitea) / deploy (push) Failing after 2s
- Restore (in-package :passepartout) to core-reason - Move *VAULT-MEMORY* back to core-skills - Fix ASDF and defstruct/defpackage ordering - Increase daemon timeout to 120s - Handshake: 0.5.0 Verified: daemon processes messages, TUI clean, gate trace works
210 lines
8.7 KiB
Org Mode
210 lines
8.7 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.
|
|
5. These files are excluded (no defuns): ~core-manifest.org~, ~setup.org~.
|
|
6. **NO-HARDCODED-CONSTANTS**: All configurable values (thresholds, intervals,
|
|
paths, limits, counters) MUST be read from environment variables with a
|
|
documented default in ~.env.example~. No magic numbers, no hardcoded
|
|
string literals in function bodies for any value a user might need to
|
|
change. The user owns their configuration — they change it in ~.env~, not
|
|
in the source code. Exceptions: internal implementation details that are
|
|
never user-facing (hash-table sizes, buffer capacity limits, loop
|
|
iteration caps) may live in source. But if the value controls *behavior*
|
|
(how many approvals before a rule, what similarity threshold gates
|
|
context, how long a shell command runs before timeout), it lives
|
|
in ~.env~ with a fallback default.
|
|
|
|
** Engineering Lifecycle (Two-Track)
|
|
|
|
The canonical workflow. Two tracks, not to be confused:
|
|
|
|
*** Track 1 — Org-First: Prose, Tests, Thinking (Phases 0/A)
|
|
|
|
This track stays in Org. No code is written yet.
|
|
|
|
**** Phase 0: Exploration & Documentation
|
|
1. Read the relevant Org source files for context
|
|
2. Explore the problem in the running REPL with ~repl-inspect~ and ~repl-eval~
|
|
3. Document findings in Org prose
|
|
4. If a bug: document investigation in Org before fixing (Org as thinking medium)
|
|
|
|
**** Phase A: Test-First Design
|
|
1. Write the success criteria as Contract items in the ~** Contract~ section
|
|
2. Write the FiveAM test in the ~* Test Suite~ section at the bottom of the file, with a comment referencing which Contract item it verifies. Tests are embedded — no ~:tangle ../tests/...~ override.
|
|
3. Tangle and evaluate in the REPL — confirm it fails (red)
|
|
4. The failing test is the success criteria. Do not proceed to Track 2 until it exists and is red.
|
|
|
|
*** Track 2 — REPL-First: Implementation, Iteration, Reflection (Phases B/C/D/E)
|
|
|
|
Code is prototyped in the REPL, never written directly into Org first.
|
|
|
|
**** Phase B/C: REPL Implementation
|
|
1. Write the function directly in the REPL using ~repl-eval~
|
|
2. Iterate: evaluate, inspect, fix, re-evaluate — the image accumulates state
|
|
3. Run the test in the REPL — confirm green
|
|
4. Explore edge cases with ~repl-inspect~ and ad-hoc evaluations
|
|
5. Before writing any ~defun~ in an Org block, verify it was prototyped and tested in the REPL first
|
|
|
|
**** Phase D: Chaos Verification
|
|
Run the appropriate chaos tier before reflecting code back to Org:
|
|
- *Tier 1 (Deterministic)*: Full FiveAM test suite — required on every change
|
|
- *Tier 2 (Probabilistic)*: Randomized fuzzing — required on every major release
|
|
- *Tier 3 (Stress)*: Load and resource starvation — required during hardening sprints
|
|
|
|
**** Phase E: Reflect Back to Org
|
|
1. Copy the working function into its own ~#+begin_src lisp~ block in the Org file
|
|
2. Update the prose to match what the function actually does (arguments, return, rationale)
|
|
3. Before closing Phase E, run ~(lisp-validate (uiop:read-file-string "path/to/file.lisp") :strict t)~ in the REPL — never external scripts or manual paren-counting
|
|
4. Verify the Org file tangles correctly
|
|
5. Tangle, commit, update GTD
|
|
|
|
**** Syntax Error Protocol
|
|
If a LOADER ERROR or reader-error occurs:
|
|
1. Run ~(lisp-validate (uiop:read-file-string "file.lisp") :strict t)~ in the REPL — never Python, never grep, never manual counting
|
|
2. Fix the error in the Org file (since the code was prototyped in REPL first, this should be rare)
|
|
3. Retangle and re-evaluate
|
|
|
|
Rationale: The two tracks prevent the two failure modes we have observed. Writing implementation code directly in Org (without REPL prototyping) produces syntax errors that require external tools to debug. Skipping Org-first test writing produces code without verified success criteria. The split is not bureaucratic — it is the mechanism by which both failures are prevented.
|
|
|
|
** GTD Conventions
|
|
|
|
Every task headline in the project's ROADMAP.org and gtd.org follows these rules:
|
|
|
|
1. **:ID:** — generated by ~memory-id-generate~ (UUIDv4 with ~id-~ prefix), never written manually. Use ~(memory-id-generate)~ in the REPL to produce one.
|
|
2. **:CREATED:** — ISO-8601 timestamp: ~[2026-05-02 Sat 14:30]~. Set when the headline is first created, never changed.
|
|
3. **:LOGBOOK:** — each state transition is logged: ~- State "DONE" from "TODO" [2026-05-02 Sat 15:00]~.
|
|
4. **CLOSED:** — set when the task reaches DONE: ~CLOSED: [2026-05-02 Sat 15:00]~.
|
|
5. **TODO keywords** follow the standard sequence: ~TODO~ → ~NEXT~ → ~IN-PROGRESS~ → ~DONE~ / ~BLOCKED~ / ~CANCELLED~.
|
|
6. **The Agent** updates these automatically during Phase E of the lifecycle. The human never needs to write a UUID or timestamp manually — the agent generates and inserts them.
|
|
|
|
Example:
|
|
|
|
#+begin_src org
|
|
*** DONE Event Orchestrator
|
|
:PROPERTIES:
|
|
:ID: id-4a2b9c8f-3d7e-4f12-a9b0-1c2d3e4f5a6b
|
|
:CREATED: [2026-05-02 Sat]
|
|
:END:
|
|
:LOGBOOK:
|
|
- State "DONE" from "TODO" [2026-05-02 Sat 18:00]
|
|
:END:
|
|
CLOSED: [2026-05-02 Sat 18:00]
|
|
#+end_src
|
|
|
|
* 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 |