This document defines the coding and development rules for Space Station OS (SSOS).
All contributors are expected to follow these rules.

---

All development must start from an Issue.

• Every PR must be linked to an Issue
• Direct commits to main without Issue are not allowed

---

Each Issue must include User Story and Acceptance Criteria:

Describe the purpose from a system or user perspective.

Example:

As a system integrator,
I want ARS to fail when overheating occurs,
so that failure propagation can be validated.

---

Define testable conditions.

Example:

• Action fails when temperature exceeds threshold
• result.success == false
• summary_message contains "Bed failure"

---

• PR must reference Issue using:

closes #<issue_number>

• PR must include:
  • What was changed
  • Why it was changed
  • Test impact

---

SSOS uses a two-layer model for implementation maturity.

---

Features that are guaranteed in release.

Requirements:

• Covered by tests
• Behavior is deterministic
• Safe for integration with other subsystems

Examples:

• ARS starts when DDCU power is granted
• Invalid CO2 request is rejected
• CO2 storage request failure works

---

All other behaviors.

Includes:

• Simplified simulation
• Incomplete failure semantics
• Boundary conditions not finalized
• Partial implementations

---

Experimental behavior must never be silent.

---

Any Experimental path must emit:

RCLCPP_WARN_ONCE(this->get_logger(), "[EXPERIMENTAL] ");

---

If behavior is not Contracted, output must include:

• "EXPERIMENTAL"
• or equivalent status indicator

Example:

summary_message = "EXPERIMENTAL: fallback path used";

---

• Must pass before release
• Included in CI

---

• Optional
• Not required for release
• May be:
  • Disabled (DISABLED_)
  • Separate test file

---

Behavior Tree defines system logic.

Example:

Rules:

• BT defines execution structure
• Failure semantics must be explicit
• Fallback does not equal failure unless explicitly escalated

---

Failure must follow:

• Contracted failure → Deterministic + tested
• Experimental failure → Logged + clearly marked
• Undefined failure → Must not silently pass

---

SSOS does not require full physical fidelity.

Instead:

• Prioritize system behavior consistency
• Allow partial models
• Explicitly label incomplete logic

---

• Clear naming
• Separation of logic and interface
• No hidden behavior

---

• Use RCLCPP_INFO / WARN / ERROR appropriately
• Avoid silent failures

---

Must include:

• Only Contracted behaviors
• Passing core tests

---

Used for:

• Test fixes
• Behavior clarification
• Contract promotion

---

The core principle is:

Only Contracted behavior is reliable.
Experimental behavior must be visible.