Contributing to CXS + CANARY

Thank you for your interest in contributing!

This repository documents the CXS Continuity Architecture and the CANARY runtime drift-monitoring system, originally developed across 2000+ real-world LLM sessions.

Contributions are welcome — but because this project focuses on deterministic continuity, contributions must follow specific rules.

---

1. Code of Conduct

All contributors must:

• respect deterministic state and strict-mode principles,
• avoid speculative or ungrounded architectural additions,
• engage constructively and professionally,
• document any change that affects continuity behavior.

This project’s integrity relies on consistency and clarity.

---

2. Before You Contribute

Please read:

• /spec/cxs-passport.yaml
• /spec/strict-mode.md
• /spec/startup-ritual.md
• /canary/runtime-protocol.md
• /validation folder (for deterministic testing)

This ensures that contributions align with the continuity guarantees.

---

3. Contribution Workflow

Step 1 — Fork and Branch

• Fork the repository
• Create a new branch for your change
  • feature/<name>
  • docs/<name>
  • fix/<name>

Step 2 — Make Your Changes

• Follow strict-state-derivation principles:
  • no invention,
  • no mutation of canonical state,
  • no unconstrained additions,
  • maintain deterministic interpretation.

Step 3 — Write Clear Documentation

Every contribution must include:

• rationale for change,
• before/after example (if relevant),
• any impact on strict-mode or CANARY,
• instructions for users.

If your change affects CXS rules, you must also propose updates to:

• /spec/cxs-passport.yaml
• /spec/strict-mode.md
• /validation/*

Step 4 — Add or Update Tests

If applicable:

• add a new test in /validation, or
• update relevant checklists.

Cross-model and same-model drift tests are encouraged.

Step 5 — Submit a Pull Request

Include:

• a descriptive title
• clear summary of what changed
• justification aligned with strict-mode
• any relevant discussion or references

A maintainer will review the PR and provide feedback.

---

4. Rules for Documentation Contributions

Documentation PRs should:

• be precise,
• avoid vague language,
• avoid adding extraneous conceptual layers,
• reflect the actual behavior of strict-mode and CANARY.

If adding diagrams:

• export them as PNG under /assets
• ensure labels match the paper

---

5. Rules for Spec Changes

Changes to CXS must not break:

• digest determinism
• invariant lock
• constraint lock
• ledger semantics
• anchor semantics
• strictly bounded output scope
• cross-model reproducibility

Spec changes require:

• strong justification
• full validation suite passing
• updated digest spec if required

---

6. Rules for CANARY Contributions

Contributions to CANARY must:

• respect the GREEN/YELLOW/RED health model
• maintain simplicity and low cognitive overhead
• not introduce complexity that destabilizes reasoning
• avoid adding heavy-weight runtime logic

If proposing new heuristics:

• they must be explainable,
• they must be consistent across models,
• they must be testable with existing drift examples.

---

7. Submitting Examples or Evidence

If adding:

• sample passports
• drift events
• verification logs
• cross-model experiments

Please:

• redact sensitive content
• include digests, timestamps, and anchor checksums
• follow naming conventions (DE-YYYY-MM-DD-ID)

---

8. Asking Questions

If you're unsure whether a contribution aligns with CXS:

• open an Issue titled “QUESTION: ”
• describe your scenario clearly
• reference relevant sections of the spec or paper

Discussion is encouraged before proposing heavy changes.

---

9. Acknowledgments

This project originated from over 2000 real-world LLM engineering sessions
and represents the distilled methodology of deterministic continuity.

Your contributions help evolve the ecosystem while preserving its integrity.

Thank you for contributing!