opusmanSEEKv4/CONTRIBUTING.md

Contributing To Nexus OS

This repository is governed infrastructure. Contributions must preserve the core invariant: changes are evidence-grounded, bounded, test-gated, and auditable.

Read First

Before opening an issue, branch, or pull request, read:

• 01_PROJECT_STATE.md
• AGENTS.md
• docs/governance/04_GOVERNANCE.md
• docs/architecture/02_ARCHITECTURE.md

If those files conflict with chat history or external reports, tracked repository files win.

Contribution Scope

Accepted contribution areas:

• Tests for existing behavior.
• Documentation that clarifies verified repository state.
• Bug fixes with focused diffs and test evidence.
• API/interface work that preserves the Python governance backend as canonical.
• Mock or wrapper work that does not expose private models, raw DoppelGround exports, or TWAVE internals.

Not accepted in Phase 0 without explicit approval:

• TWAVE algorithm changes.
• Model deletion, promotion, fine-tuning, or uncensoring work.
• Automatic provenance commits or automatic governance approvals.
• Raw research dumps, model weights, .env files, secrets, or generated caches.
• Claims of cryptographic VAP, full A2A maturity, OWASP ASI coverage, SkillFortify, or production ASBOM maturity unless locally verified.

Git Workflow

• Do not use git add ..
• Stage explicit reviewed paths only.
• Keep unrelated work in separate commits.
• Do not include sandbox files, mock credentials, generated caches, local databases, or downloaded archives unless explicitly approved.
• Commit messages must state the behavior changed and the verification result.

Recommended commit format:

type(scope): concise behavior change

Explain what changed, why it is safe, and the verification command/result.

Examples:

fix(engine): correct dependency cycle traversal

Follow dependency edges downstream during cycle detection.
Verified with tests/engine/test_router.py and full suite: 617 passed.

docs(state): add canonical Nexus project state

Capture current local HEAD, verification gate, blockers, and P0 sequence.
No runtime code changed.

Governance Requirements

All implementation work must satisfy the relevant gate:

• Core code changes require focused tests.
• DB, router, governor, bridge, vault, GMR, or monitoring changes require the full test suite unless explicitly blocked.
• Security-sensitive defaults must fail closed.
• Development escape hatches must be explicit in configuration.
• Retrospective provenance tools must start as dry-run/report-only.

External Team Boundaries

TWAVE wrapper work:

• Allowed: wrapper API, health checks, artifact handling, VRAM pre-checks, structured error responses.
• Not allowed: TWAVE math, quantization algorithm changes, ABI/runtime redesign, private internals.
• Canonical port: 7353 under /twave/*.

GeniusTurtle UI work:

• Allowed: UI surfaces, mock API integration, operator workflows.
• Not allowed: model weights, direct Ollama exposure, embedded governance decisions, secrets.

Nexus governance work:

• Python/FastAPI is the canonical governance control plane.
• Dashboard, Bun, Next.js, and relay layers are proxies or clients only.
• Canonical port: 7352.

Attribution And License Position

Until a final LICENSE is committed, contributors must not assume public/commercial terms beyond what is explicitly tracked in this repository.

Every external contribution must include attribution when it uses or adapts external sources:

• Paper, repository, dataset, or article references.
• Prior implementation source.
• Generated code source when relevant to licensing or provenance.

Recommended attribution footer for non-trivial files:

Attribution:
- Author: <name or handle>
- Source: <paper/repo/link if applicable>
- Notes: <short provenance note>

By submitting a contribution, you confirm that you have the right to contribute it and that it may be incorporated into Nexus OS under the repository's final tracked license terms.

Pull Request Checklist

• Read 01_PROJECT_STATE.md.
• Diff is bounded to one coherent task.
• No secrets, raw dumps, model weights, .env files, generated caches, or local databases.
• Tests or verification evidence included.
• Documentation updated when behavior or boundaries change.
• Public/private boundaries preserved.
• Any appendix asset promoted from Downloads is clearly reconciled against canonical repository files.