Skip to content

Latest commit

 

History

History
156 lines (117 loc) · 8.18 KB

CONTRIBUTING.md

File metadata and controls

156 lines (117 loc) · 8.18 KB

HumOS & LINGHOS Contribution Guidelines

Document Identifier: GOV-CONTRIB-20261108-EN
Standard Status: Official Project Governance Specification
Classification: Open-Source Developer Workflow & Protocol Standards
Maintainer: SystemAdmin01


1. Code of Technical Conduct & Architectural Philosophy

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:

  1. Zero Hallucination Tolerance: The compiler and runtime must never output non-deterministic or speculative state parameters.
  2. Strict Context Budgeting: Token overhead must be minimized at all serialization boundaries.
  3. Formal Invariant Guarantees: Core Self isolation (CS_SECURE), spatial proximity mathematics, and thermodynamic accounting (RAM, BPM) cannot be bypassed or weakened.

2. Primitive Proposal Protocol (PPP)

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.

2.1 Criteria for Primitive Acceptance

Before submitting a proposal for a new primitive (e.g., MEMORY.*, THREAD.*, SHIELD.*), the author must demonstrate that:

  1. Non-Redundancy: The capability cannot be synthesized using an existing primitive sequence (e.g., RAM.alloc() + THREAD.spawn()).
  2. Context Window Efficiency: The serialized token footprint of the primitive must not exceed 24 tokens under standard UTF-8 Byte-Pair Encoding (BPE).
  3. 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).
  4. Backward Parser Compatibility: The addition must not introduce Lookahead conflicts ($LR(1)$ shift-reduce or reduce-reduce ambiguities) in linghos/parser.py.

2.2 Formal RFC Template for Primitive Proposals

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.

3. Pull Request Verification Standard (PRVS)

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]
Loading

3.1 Step-by-Step Verification Checklist

  • 1. Strict Grammar & Lexer Compliance

    • All .lghos and .lgh examples compile cleanly through linghos/compiler.py without syntax warnings.
    • Semicolons, block closures (Main() { ... }), directives (/SET_Lockdown_Mode), and macro headers (#include) strictly follow the grammar defined in docs/SPEC.md.
    • No trailing whitespace or broken delimiters.
  • 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.
  • 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 bytes for 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_shield prevents thermal throttling when RAM exceeds $85%$.

4. Conventional Commit Standards & HumOS Scopes

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.

4.1 Commit Structure

<type>(<scope>): <short imperative summary>

[optional body providing technical justification]

[optional footer referencing issue or breaking change]

4.2 Approved Types & HumOS-Specific Scopes

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

4.3 Commit Message Examples

✅ Valid Commit Messages

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 contracts

❌ Invalid Commit Messages

updated 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 verb

5. Development Environment Setup & Validation

To 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.py

Authored under the HumOS Specification Group.
Official Repository: https://github.com/SystemAdmin01/HumOS