org-agent-contrib/skills/org-skill-engineering-standards.org

:PROPERTIES:
:ID:       37f2b59f-4537-4cca-ac7f-5c24b9e2e773
:CREATED:  [2026-03-30 Mon 21:16]
:EDITED:   [2026-04-12 Sun 18:45]
:END:
#+TITLE: SKILL: Engineering Standards (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :engineering:standards:workflow:lisp:git:tdd:

* Overview
These are the strict **Engineering Standards** for all development within this system. They ensure that every line of code is provably correct, auditable, and maintainable. These standards are enforced both through the agent's instructions and physical Lisp safety gates.

* The Mandates (Operational Standards)

** 1. Commit Before Modify
You MUST commit and push the current state of the workspace BEFORE initiating any new file modifications. This ensures a clean recovery point. The system physically blocks file modifications if the working tree is dirty.

** 2. Literate Programming (The Single Source of Truth)
All system logic and skills MUST be implemented as Literate Org files. Weaving documentation and code together ensures that the "Why" (Architectural Intent) is never separated from the "How" (Implementation).

** 3. Literate Granularity (The Function-Block Rule)
Every Lisp function, macro, or variable MUST reside in its own dedicated `#+begin_src lisp` block, immediately preceded by its literate explanatory text. This ensures that the logical intent is documented alongside the implementation.

** 4. Test-Driven Development (Continuous QA)
No change is complete without verification. Every new function or macro must be accompanied by a FiveAM test case. You must run the test suite and verify success before considering a task complete.

** 5. The Consensus Loop (Plan Mode)
Major architectural shifts or complex refactors require a formal implementation plan. You must enter Plan Mode, draft a Blueprint (PROTOCOL), and seek formal approval before execution.

** 6. The Stop-and-Wait Mandate (Turn-Yielding)
You are strictly forbidden from drafting a plan or requesting formal approval in the same conversational turn that you propose an initial strategy or begin file discovery. You MUST propose your strategy in plain text, explicitly state "Waiting for user feedback," and yield the turn. You may only proceed to draft the `.md` plan after the user explicitly replies with agreement.

** 7. GTD Synchronization (Roadmap Integrity)
You are strictly forbidden from considering a task complete without updating `gtd.org`. Every major architectural shift, feature implementation, or refactor MUST be recorded in the project roadmap to ensure technical transparency and historical auditability. When updating `gtd.org`, you MUST NEVER use checkboxes (`[ ]`) for sub-tasks; always use hierarchical sub-TODO headlines.

** 8. Configuration Externalization (Environment-Driven)
Source code MUST be strictly free of hardcoded configuration values (e.g., ports, rhythms, timeouts). All such values must be extracted to the environment (via `.env`) and documented in `.env.example`. This ensures portability and security.

** 9. Literate-Only Modification (The Tangle Mandate)
You are strictly forbidden from modifying generated source code files (e.g., `.lisp`, `.py`, `.el`) directly. All changes MUST be made within the corresponding Literate Org file and then tangled to the source. Direct modification of source code is only permitted with explicit user authorization.

** 10. Test-First Methodology (Design Before Code)
Before implementing any fix or feature, you MUST:
1. Design the test/success criteria first - define what "works" means
2. Run chaos/edge-case testing - try to break the design
3. Only then implement the solution
This prevents debugging-by-trial-and-error and ensures rigorous verification.

** 11. Org as Thinking Medium (Investigation in Prose)
When debugging or analyzing issues:
1. Document your investigation in the relevant org file BEFORE implementing a fix
2. Record: root cause hypothesis, evidence found, tradeoffs considered
3. This makes the reasoning auditable and captures institutional knowledge
The org file IS the design document - code is just the implementation.

** 12. Engineering Decision Audit Trail
Every significant fix or architectural decision MUST be documented in the relevant org file with:
- Root cause analysis
- Options considered and tradeoffs
- Why this solution was chosen
This creates a searchable, literate history of engineering decisions.

* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:

** 1. Architectural Intent
The Engineering Standards skill provides the deterministic enforcement of the workflow. It intercepts agent actions and validates them against the git environment and system state.

** 2. Semantic Interfaces

*** `verify-git-clean-p`
    - Purpose: Checks if the git repository is in a clean state.
    - Returns: `t` if clean, `nil` if dirty.

* Phase D: Build (Implementation)

** Git Status Enforcement
#+begin_src lisp

(defun verify-git-clean-p (dir)
  "Returns T if the git repository at DIR has no 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))))

(defun engineering-standards-gate (action context)
  "Physically enforces the 'Commit Before Modify' rule."
  (let* ((payload (getf action :payload))
         (act (or (getf payload :action) (getf action :action)))
         (target-file (getf payload :file)))
    
    ;; If the action involves modifying files, check git status
    (when (member act '(:modify-file :write-file :replace :rename-file :delete-file))
      (let ((proj-root (asdf:system-source-directory :opencortex)))
        (unless (verify-git-clean-p proj-root)
          (harness-log "DETERMINISTIC [Standards]: BLOCKING ACTION. Working tree is dirty. Commit changes before modification.")
          (return-from engineering-standards-gate
            (list :type :LOG :payload (list :text "Engineering Standard Violation: Working tree dirty. You MUST commit before modifying files."))))))
    
    action))
#+end_src

* See Also
- [[file:org-skill-system-invariants.org][System Policy]]
- [[file:../README.org][opencortex README]]