6.6 KiB
SKILL: Engineering Standards
- Overview
- Phase 0: Before You Think
- Phase A: Design (Test-First)
- Phase B: Commit (Recovery Point)
- Phase C: Build (Implementation)
- Phase CDD: Chaos-Driven Development (Hardcoded Resilience)
- Phase D: Validate (Proof)
- Phase E: Document (Audit Trail)
- Enforcement Implementation
- Test Suite
Overview
This skill enforces the Engineering Standards for all development within OpenCortex. It observes agent context and gates actions that violate protocol.
Phase 0: Before You Think
Skill-First Query Rule
Before any analysis, debugging, or implementation: check if a skill already covers the problem domain.
Phase A: Design (Test-First)
1. Define Success Criteria First
Before writing code, write the test that proves the feature works. The test defines the contract.
Phase B: Commit (Recovery Point)
2. Commit Before Modify
You MUST commit the current workspace state before initiating new file modifications.
Phase C: Build (Implementation)
3. Literate Programming (Single Source of Truth)
All system logic and skills MUST be implemented as Literate Org files.
4. Function-Block Granularity
Every Lisp function, macro, or variable resides in its own dedicated #+begin_src lisp block.
5. Tangle Mandate
You are forbidden from modifying generated .lisp files directly.
Phase CDD: Chaos-Driven Development (Hardcoded Resilience)
6. Tier 1: Integrity Chaos (Per-Turn)
Mandate: Every turn involving a tangle MUST end with a "Structural Balance" check. Enforcement: The Agent must verify that all tangled artifacts pass the Lisp reader without syntax errors.
7. Tier 2: Integration Chaos (Per-Feature)
Mandate: Every new skill or major feature MUST include an "Adversarial Test Case." Enforcement: The test suite must simulate a failure (e.g., mock network drop, malformed input) and prove the system degrades gracefully.
8. Tier 3: Systemic Chaos (Per-Milestone)
Mandate: Before sealing a milestone, the Agent MUST perform a "Scorched Earth" bootstrap. Enforcement: Wipe XDG directories and verify a 100% autonomous re-initialization from the git source.
Phase D: Validate (Proof)
9. Test Verification
No change is complete without running the test suite. Run chaotic tests alongside the main suite.
Phase E: Document (Audit Trail)
10. Decision Audit Trail
Every significant fix or architectural decision MUST be documented in an org file.
Enforcement Implementation
Package Context
(in-package :opencortex)Global Configuration
(defvar *engineering-std-project-root* nil
"Path to the project root for enforcement checks.")(defstruct engineering-violation
(phase nil)
(rule nil)
(message nil)
(severity nil))CDD Utilities: Tier 1
(defun check-structural-balance (file-path)
"Tier 1 Chaos: Verifies that a Lisp file is syntactically balanced."
(handler-case
(with-open-file (s file-path)
(loop for form = (read s nil :eof)
until (eq form :eof))
t)
(error (c)
(harness-log "CHAOS ERROR [Tier 1]: ~a in ~a" c file-path)
nil)))Git Protocol
(defun verify-git-clean-p (&optional (dir *engineering-std-project-root*))
"Returns T if the git repository at DIR has no uncommitted changes."
(when dir
(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)))))Initializer
(defun engineering-std-init ()
"Initialize the enforcement system."
(let ((env-root (or (uiop:getenv "OC_DATA_DIR")
"/home/user/.local/share/opencortex")))
(setf *engineering-std-project-root* (uiop:ensure-directory-pathname env-root))
(harness-log "ENGINEERING STANDARDS: CDD Protocol Active.")));; Auto-initialize on load
(engineering-std-init)Test Suite
(defpackage :opencortex-engineering-standards-tests
(:use :cl :fiveam :opencortex)
(:export #:engineering-standards-suite))(in-package :opencortex-engineering-standards-tests)(def-suite engineering-standards-suite
:description "Tests for Engineering Standards enforcement")(in-suite engineering-standards-suite)(test git-clean-check-clean
"verify-git-clean-p returns T when git tree is clean."
(let ((tmp-dir "/tmp/eng-std-test-clean/"))
(uiop:ensure-all-directories-exist (list tmp-dir))
(uiop:run-program (list "git" "init" tmp-dir) :output nil)
(is (eq t (opencortex::verify-git-clean-p (uiop:ensure-directory-pathname tmp-dir))))
(uiop:delete-directory-tree (uiop:ensure-directory-pathname tmp-dir) :validate t)))