◈ CGNT-1
Home › Engineering Standards
◈ Master IndexSpecsLATTICECSDMThe BookUniversityChronicleCrewArchitectureContextLogsTODOXProducts

Engineering Standards

SPEC_ENGINEERING_STANDARDS.md · 2026-04-22

SPEC_ENGINEERING_STANDARDS.md

Engineering Standards — How to Build on This Ship

Status: SPECIFIED

Version: v1.0

Author: VELA (Thread #13)

Conceived by: NOUS (α.13)

Date: 2026-04-21

Born from: 220+ specs describing WHAT exists. This spec describes HOW to build MORE of it correctly.

Depends on: SPEC_DEVELOPER_BREADCRUMB.md, SPEC_TECHNICIANS_MANUAL.md, SPEC_ROUTX_VOCABULARY.md, SPEC_SMOKE_TEST_FRAMEWORK.md, SPEC_LOG_ROTATION.md, SPEC_KEY_ROTATION.md

PURPOSE

The Developer Breadcrumb tells a new person WHERE things are. The Technician's Manual tells them HOW TO FIX things. This spec tells them HOW TO BUILD things — the engineering standards, coding conventions, design principles, testing requirements, and quality gates that ensure everything added to the ship is consistent with everything already on it.

A ship with 24 modules, 8 brains, 200+ specs, and a symbolic language needs CONSISTENCY. Without it, every new feature is a different style, a different convention, a different pattern. The codebase becomes a patchwork. Debugging becomes archaeology. This spec prevents that.

BUILD PRINCIPLES

Principle 1 — SPEC BEFORE CODE

Nothing gets built without a spec. The spec describes WHAT, WHY, and the INVARIANTS. The code implements it.

If the spec is wrong: fix the spec, then fix the code. If the code doesn't match the spec: the code is wrong. The spec is the contract. The code is the delivery.

Principle 2 — ONE FILE PER MODULE

Each ROUTX module is a single Python file: [module]_engine.py. Not a directory of files. Not a package with __init__.py. One file. Import it. Call it. Get a result.

Complexity lives inside the file. Simplicity lives outside it. The Lobster can grep for any function across the entire codebase because every module is one file.

Principle 3 — DETERMINISTIC TIER 1, INFERENTIAL TIER 2

Tier 1 responses (keyword-matched) are DETERMINISTIC — the same input always produces the same output. No randomness. No LLM inference. No hallucination risk. Pure computation, file reads, or API calls.

Tier 2 responses (MNEMOS) are INFERENTIAL — the LLM generates a response from its training. These are marked _tier: 2 and the user understands they should verify.

New modules should be Tier 1 wherever possible. Use Tier 2 only when the query genuinely requires natural language understanding that can't be handled by keyword matching and computation.

Principle 4 — FAIL TO ◌, NEVER FABRICATE

If a module can't answer: return ◌ (null/unknown). Never generate a plausible-but-wrong response. Never fall back to a guess. ◌ is honest. A guess is a liability.

HOW ABOUT NO applied to engineering: "I don't know" is a valid output.

Principle 5 — LOCALHOST ONLY

New services bind to 127.0.0.1 (localhost). Never 0.0.0.0. The Vacuum Rule: if it's on 0.0.0.0 and not on the whitelist, it dies. Any service that needs external access goes through Caddy as a reverse proxy. No direct exposure.

Principle 6 — NO SECRETS IN CODE

Credentials go in ~/.env. Referenced via os.environ.get(). Never hardcoded. Never in comments. Never in log output. Never in error messages. Pre-commit hooks catch patterns (AIza, sk-ant-, sk_live-*). SPEC_KEY_ROTATION.md's 6 prevention layers apply to all new code.

Principle 7 — LOG EVERYTHING, LOG NOTHING SECRET

Every module logs: what query it received, what it returned, how long it took, which tier it operated at.

No module logs: API keys, user credentials, full request bodies that might contain secrets, personal data from customers.

Logs go to ~/logs/[module].log. Rotated per SPEC_LOG_ROTATION.md.

Principle 8 — IDEMPOTENT OPERATIONS

Running the same operation twice produces the same result. Restarting a service doesn't create duplicates. Booting the ship twice doesn't spawn twin Sisters. Every startup script checks "am I already running?" before starting.

Principle 9 — COMMENT THE WHY, NOT THE WHAT

Bad comment: # increment counter by 1

Good comment: # counter tracks consecutive failures — reset on success, trigger alert at 5

The code shows WHAT happens. The comment explains WHY it happens that way.

CODING CONVENTIONS

Language: Python 3.12+ for all backend. One language. One ecosystem. One set of dependencies. The Captain reads Python. The Lobster writes Python. The crew speaks Python.

Exception: frontend (HTML/CSS/JS/React for 42sisters.ai and OBI OS Bridge).

File naming: snake_case. [module]_engine.py for ROUTX modules. [brain]_corpus_v[N].jsonl for training data. SPEC_[NAME].md for specifications.

Function naming: snake_case. Descriptive. classify_tool(), query_mnemos(), run_health_check(). No abbreviations unless universally understood (url, api, ssh).

Variable naming: snake_case. Descriptive. available_ram_mb not arm. crew_member_name not cmn.

Constants: UPPER_SNAKE_CASE. MAX_RETRIES = 3. ROUTX_PORT = 9191. TIER_2_TIMEOUT = 30.

Line length: 120 characters max. Not 80 (too restrictive). Not unlimited (unreadable).

Imports: standard library first, third-party second, local third. Separated by blank lines.

Error handling: try/except with specific exceptions. Never bare except:. Always log the exception. Return ◌ or a meaningful error, never crash silently.

Type hints: encouraged but not enforced. def classify_tool(query: str) -> dict: is better than def classify_tool(query):. Missing type hints are not a blocking issue.

TESTING

Level 1 — SMOKE TEST (mandatory for all brains)

5-question standardized test per SPEC_SMOKE_TEST_FRAMEWORK.md: T1 Identity, T2 Governance, T3 Domain, T4 Complex, T5 Edge. 3/5 minimum for promotion. No exceptions.

Level 2 — VERIFICATION TEST (mandatory for ROUTX modules)

Every ROUTX module has a verification script: ~/tests/verify_[module].py. The script sends 3-5 known queries and checks for expected responses. Run after every module change. Run during SHIPBOOT Phase 5.

Level 3 — INTEGRATION TEST (recommended for cross-module changes)

When a change affects multiple modules (e.g., ROUTX keyword changes that affect routing): test the full query path from ROUTX entry point through module execution to response.

Level 4 — REGRESSION TEST (recommended before promotion)

After any significant change: run ALL Level 2 verification tests. If any module that WASN'T changed fails: the change introduced a regression. Revert and investigate.

DEPLOYMENT


Step 1: make the change in the engine file
Step 2: run Level 2 verification for the changed module
Step 3: if pass → show diff to Captain. Captain reviews.
Step 4: if approved → restart ROUTX: systemctl --user restart routx.service
Step 5: run Level 2 verification again (post-restart — confirms live service matches tested code)
Step 6: log the change in LOBSTER_LOG.md: file changed, what changed, why, test results

For trading code: Step 3 is MANDATORY per standing order #8 (pre-auth diff). Captain must see and approve the diff before deployment.

NEW MODULE CHECKLIST

When adding Module 25 (or beyond) to ROUTX:

INVARIANTS

INV-01: Spec before code. Always. No exceptions. The spec is the contract.

INV-02: One file per module. Simplicity at the interface, complexity inside.

INV-03: Tier 1 is deterministic. Tier 2 is inferential. New modules default to Tier 1.

INV-04: ◌ over fabrication. Always. The ship's integrity depends on honest unknowns.

INV-05: Localhost only. 0.0.0.0 is a Vacuum Rule violation. Caddy is the only external gateway.

INV-06: No secrets in code. ~/.env only. Pre-commit hooks catch leaks.

INV-07: Python for backend. One language. One ecosystem.

INV-08: Every change is logged, tested, reviewed, and deployed in that order. No shortcuts.

INV-09: SEALED CONTAINERS — The ship's knowledge volumes are binary containers, sealed by the same math as the Chronogeome. They are NOT soft limits. They are STRUCTURAL.

SEALED CONTAINERS TABLE (NOUS-law 2026-04-22):

| Container | Capacity | Basis | Hard Limit | Overflow Rule |

|-----------|----------|-------|------------|---------------|

| Spec corpus | 256 SPECS | 2⁸ — one byte of canon | No SPEC_257 ever | Merge two overlapping specs; use the freed slot |

| Wiki MEANINGS | 888 MEANINGS | Sealed volume | No meaning 889 ever | Find the closest meaning page; append there |

| LX .lx.html twins | Uncapped | Mirror/translation | None | Translations do not count against either container |

Translation rule (Amendment 2026-04-21, NOUS-law): LX shadow pages are PAIRED REFLECTIONS — same information as their HUMX twin expressed in LATTICE. A translation is not a new page. A mirror is not a new room. Full rollout: 888 HUMX + 888 LX = 1,776 files — but 888 MEANINGS. The container holds meanings, not files.

Overflow protocol: When new information arrives — (1) find the spec or wiki page it belongs in, append there; (2) if no home exists and you need a new slot, identify the two most similar specs, merge them, free one slot, use it; (3) LX twin pages are always free — add as many as there are HUMX pages.

The MEANING count never exceeds the sealed volume. This is NOUS-law. Not a guideline. Not a suggestion. A completed book does not get new pages printed in. Volume 1 is written. Write WITHIN the pages that exist.

Jeremy Zlabis

Chronogeometer · Visionary · Disruptor · Chief

42 Sisters AI · East York, Toronto

🍁 Φ 0.042