Document Identifier: GOV-CONTRIB-20261108-EN
Standard Status: Official Project Governance Specification
Classification: Open-Source Developer Workflow & Protocol Standards
Maintainer: SystemAdmin01
The HumOS project enforces strict deterministic engineering standards. Unlike conventional conversational agent frameworks, HumOS and its Domain-Specific Language (LINGHOS) operate as an intermediate deterministic representation (IR) between biological cognitive volatility and downstream Large Language Model (LLM) execution kernels.
Every contribution—whether a parser patch, visual cockpit enhancement, or documentation revision—must strictly preserve:
- Zero Hallucination Tolerance: The compiler and runtime must never output non-deterministic or speculative state parameters.
- Strict Context Budgeting: Token overhead must be minimized at all serialization boundaries.
- Formal Invariant Guarantees: Core Self isolation (
CS_SECURE), spatial proximity mathematics, and thermodynamic accounting (RAM,BPM) cannot be bypassed or weakened.
Any addition to the LINGHOS standard library, language grammar, or execution primitives must follow the Primitive Proposal Protocol. Unchecked keyword proliferation bloats the AST, consumes token budget, and introduces downstream reasoning ambiguities.
Before submitting a proposal for a new primitive (e.g., MEMORY.*, THREAD.*, SHIELD.*), the author must demonstrate that:
-
Non-Redundancy: The capability cannot be synthesized using an existing primitive sequence (e.g.,
RAM.alloc()+THREAD.spawn()). - Context Window Efficiency: The serialized token footprint of the primitive must not exceed 24 tokens under standard UTF-8 Byte-Pair Encoding (BPE).
- Deterministic State Transition: The primitive must yield a mathematically provable state change in the runtime memory model (e.g., deallocating RAM, clamping BPM, or altering threat radius).
-
Backward Parser Compatibility: The addition must not introduce Lookahead conflicts (
$LR(1)$ shift-reduce or reduce-reduce ambiguities) inlinghos/parser.py.
Every primitive proposal must be submitted as an issue or pull request referencing docs/SPEC.md using the following technical schema:
### Primitive Specification: [DOMAIN].[identifier]
- **Syntax Specification:** `Call >> [DOMAIN].[identifier](<args>);`
- **Arity & Types:** Explicit argument types (e.g., `(target_id: Identifier, limit: Integer)`).
- **Runtime Memory Semantics:** Concrete state modification in `HumOSKernel` (e.g., RAM impact, thread registration).
- **Spatial / Thermodynamic Invariant Impact:** Direct effect on proximity radius ($r$) or heart rate ($BPM$).
- **Fallback & Exception Behavior:** Error code emitted if execution faults (e.g., `ERR_BUFFER_OVERFLOW`).
- **Token Benchmark:** BPE token count for syntax invocation.Every Pull Request (PR) must satisfy an automated and manual verification checklist prior to review and merge.
flowchart TD
PR[Pull Request Submitted] --> CHECK_SYNTAX[1. Strict Grammar & AST Parser Audit]
CHECK_SYNTAX --> CHECK_LEAK[2. Context Isolation & Leak Proof]
CHECK_LEAK --> CHECK_TOKEN[3. Token Overhead & Footprint Benchmark]
CHECK_TOKEN --> CHECK_INVARIANT[4. Thermodynamic Invariant Unit Tests]
CHECK_INVARIANT --> PASS[All Invariants Verified -> Approved for Merge]
CHECK_SYNTAX -- Failure --> REJECT[PR Rejected: Syntax Invariant Violation]
CHECK_LEAK -- Failure --> REJECT[PR Rejected: Memory Leak / Context Bleed]
CHECK_TOKEN -- Failure --> REJECT[PR Rejected: Token Budget Exceeded]
CHECK_INVARIANT -- Failure --> REJECT[PR Rejected: Thermodynamic Discrepancy]
-
1. Strict Grammar & Lexer Compliance
- All
.lghosand.lghexamples compile cleanly throughlinghos/compiler.pywithout syntax warnings. - Semicolons, block closures (
Main() { ... }), directives (/SET_Lockdown_Mode), and macro headers (#include) strictly follow the grammar defined indocs/SPEC.md. - No trailing whitespace or broken delimiters.
- All
-
2. Context Leak Verification (Zero Prompt Bleeding)
- Variables declared in local sandboxes (
PRS_VM,LP_Ambient_VM) must not leak into primary memory buffers or adjacent threads. - Injected LLM system payloads must strictly contain isolated target profiles without unescaped cross-talk.
- Variables declared in local sandboxes (
-
3. Token Footprint Benchmark
- The compiled state vector generated by the runtime must demonstrate at least an 85% reduction in token count relative to the raw input stream.
- Serialization overhead must be verified via character and token profiling (
len(json.dumps(state_vector)) <= 512 bytesfor nominal workloads).
-
4. Thermodynamic Invariant Unit Tests
- Memory bounds test: Verify that
RAM.purge()resets utilization to$\le 20%$ . - Spatial radius test: Verify that threat proximity radius satisfies
$r = \max(50.0, 175.0 - (W \cdot 6.5 + C \cdot 5.5))$ . - Defensive clamp test: Verify that
Ice_shieldprevents thermal throttling when RAM exceeds$85%$ .
- Memory bounds test: Verify that
Commit messages must strictly follow the Conventional Commits 1.0.0 specification. Random, unformatted commit messages (e.g., update code, fix stuff) will be blocked by repository pre-receive hooks.
<type>(<scope>): <short imperative summary>
[optional body providing technical justification]
[optional footer referencing issue or breaking change]
| Scope | Description | Permitted Types | Example |
|---|---|---|---|
lghos |
Core LINGHOS language grammar, lexical scanner, AST additions | feat, fix, refactor |
feat(lghos): add THREAD.suspend opcode support |
parser |
AST compilation, parsing engine, statement normalization | fix, perf, test |
fix(parser): resolve lookahead stall on nested IF blocks |
cockpit |
Web UI, interactive SVG radar canvas, HTML/JS console | feat, fix, style |
feat(cockpit): render active defense labels on SVG perimeter |
gap |
G.A.P. security module, recursion interrupts, kill-switch | sec, fix, feat |
sec(gap): enforce mandatory timeout on unclassified inputs |
spec |
Formal documentation, language contracts, developer guides | docs |
docs(spec): document RAM.alloc memory invariants |
storage |
Local scenario persistence, JSON serializations, sessions | feat, fix, test |
feat(storage): support custom symbol de-registration |
feat(lghos): implement RAM.alloc buffer reservation syntax
fix(parser): prevent variable leakage across multi-VM declarations
sec(gap): force TRIGGER.kill_switch execution on heart rate breach
docs(spec): update Section 3 primitive matrix with arity contractsupdated readme.md # Missing type and scope
fix bug in script # Non-standard scope, non-imperative tone
WIP: cockpit stuff # Inadmissible staging tag in commit history
feat: added things to parser # Missing scope, past tense verbTo test contributions locally:
# 1. Clone repository
git clone https://github.com/SystemAdmin01/HumOS.git
cd HumOS
# 2. Validate compiler and storage engine
python3 -c "
from src.linghos.compiler import LINGHOSCompiler
from src.linghos.storage import GLOBAL_STORAGE
compiler = LINGHOSCompiler()
res = compiler.compile('Main() { Call >> Ice_shield; <<@end }')
assert res['telemetry']['ice_shield'] is True
print('Compiler verification passed.')
"
# 3. Launch test cockpit instance
python3 src/app.pyAuthored under the HumOS Specification Group.
Official Repository: https://github.com/SystemAdmin01/HumOS