# Contributing to Nika

Welcome. Nika is a Rust workflow engine for AI. **0.124 is its current
release line.** Work stays focused on maintenance, security and the media
capabilities workflows need, so security fixes, bug fixes and compatibility
fixes help most; native video is planned for 0.125. The engine is a
workspace of layered crates (the count is projected, never a gate — ADR-037
horizon 50-90 · cap 100 · ruled D-2026-07-21-N1), each passing a 12-gate
admission checklist before joining the workspace. This document explains how
to contribute.

See also: [`README.md`](README.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md),
[`SECURITY.md`](SECURITY.md), [`AGENTS.md`](AGENTS.md),
[`DIAMOND.md`](DIAMOND.md) (strategy overview),
[`ROADMAP.md`](ROADMAP.md) (current status, then the earlier long-range plan),
[`docs/architecture/BLUEPRINT_2036.md`](docs/architecture/BLUEPRINT_2036.md)
(the earlier long-range proposal, kept as history).

---

## What is in scope

0.124 is the current release line, and 0.123.x is the previous one. The
`main` branch is the only maintenance branch: fixes land there and ship in
the next release. Legacy v0.79.3 lives on `brouillon` (read-only · accessed
via `git show brouillon:path`).

- **Bug reports, security reports, questions** — welcome now. Security
  issues go to the private channel in [`SECURITY.md`](SECURITY.md).
- **Bug fixes, security fixes, compatibility fixes and documentation** —
  welcome via PR, with a test or a reproduction where the change allows one.
- **A media capability your workflows need** — open an issue that describes
  the use case before a PR.
- **Other new features, new crate admissions, new ADRs** — out of scope for
  the 0.124 line.

If you are unsure whether something is in scope, open an issue first.

---

## Philosophy

- **Real semver** (D-2026-06-20-N1). The current workspace version is declared in `Cargo.toml`; published binaries are listed in [GitHub Releases](https://github.com/supernovae-st/nika/releases). 0.124 is the current release line: work stays focused on maintenance, security and the media capabilities workflows need, and native video is planned for 0.125. Each version is diamond-grade for its declared scope.
- **Quality over speed.** No deadline pressure. A PR lands when it is ready.
- **Perfect diamond.** Zero band-aid, zero residue, zero ghost reference. Every leftover gets fixed or flagged — never ignored.
- **Craft, not extraction.** Legacy code on `brouillon` (v0.79.3) is a read-only reference. Diamond rewrites each crate from scratch, guided by the legacy.

---

## Local development setup

### Prerequisites

- Rust 1.91 (`rust-toolchain.toml` pins the toolchain; the 2024 edition
  comes from `Cargo.toml`).
- macOS, Linux, or Windows (WSL). Primary dev on macOS.

### Core commands

```bash
# Run all lib tests (always --lib to avoid macOS Keychain popups)
cargo test --workspace --lib

# Clippy, zero warnings required
cargo clippy --all-targets -- -D warnings

# Format check
cargo fmt --check

# Engine-internal hygiene vectors
bash scripts/hygiene/check-all.sh

# Regenerate the canonical status block
bash scripts/refresh-status.sh
```

### Useful extras

```bash
# Per-crate gate check
bash scripts/ci/check-crate-gates.sh <crate-name>

# Mutation testing (slow, per crate)
cargo mutants -p <crate-name>

# Doc build, zero warnings required
cargo doc --workspace --no-deps
```

---

## The 12-gate crate admission model

A crate may join `Cargo.toml` `members = [...]` as WIP, listed in
`[workspace.metadata.diamond] wip`, before it is admitted. No crate leaves
that list without all 12 gates passing in the same PR. No "we'll fix gate X
later."

| # | Gate           | What it checks                                                       |
|---|----------------|----------------------------------------------------------------------|
| 1 | SPEC           | `docs/crate-specs/nika-X.md` exists — purpose, layer, LOC, public API |
| 2 | TDD            | Tests written **before** implementation, red before green             |
| 3 | IMPL           | Minimal, compiles, tests pass, no `# TEMP` without removal plan       |
| 4 | CLIPPY         | `cargo clippy --workspace --all-targets -- -D warnings` (0)           |
| 5 | MUTATION       | `cargo mutants -p nika-X` ≥ 90% killed                                |
| 6 | PROPERTY       | Proptest for parsers, encoders, security-sensitive paths              |
| 7 | BENCHMARKS     | `benches/` if hot path (or justified exemption in spec)               |
| 8 | DOCS           | `cargo doc --no-deps` 0 warnings, all pub items documented            |
| 9 | CANARY E2E     | `tests/canary-X.nika` passes (or justified exemption)            |
| 10| PARITY LEGACY  | Golden test vs `git show brouillon:...` output                             |
| 11| REVIEW SWARM   | 3 parallel reviewers (`spn-nika:code-reviewer`, `spn-rust:rust-pro`, `feature-dev:code-reviewer`), P0/P1 fixed same session |
| 12| ATOMIC COMMIT  | 1 commit, co-authored Nika                                            |

Full spec: [`.claude/rules/diamond-discipline.md`](.claude/rules/diamond-discipline.md) +
[`docs/architecture/forward-compat-invariants.md`](docs/architecture/forward-compat-invariants.md).

---

## Architecture invariants

Before modifying any crate, know these:

- **L0** crates: zero I/O, zero async, ≤ 25,000 production LOC (ADR-154).
- **L0.5** crates: traits only (`nika-kernel`, `nika-kernel-mock`).
- **L1** effect crates: one trait impl each (clock, fs, http, blob, process, ...).
- **L2** domain crates: `verb-*`, service crates, memory stubs.
- **L3** orchestration: runtime + daemon.
- **L4** interfaces: cli, cli-host, session, tui, tui-core, lsp, mcp, dap,
  serve, arm, trace, onboard, compile*, models (full list:
  `docs/architecture/crate-layer-registry.md`).
- **L5** binary: `nika` (≤ 500 LOC composition root · the `nika` bin target is already born in L4's `nika-cli`; L5 will own it, never rename it · ADR-135).

Strict **downward** dependencies only. No upward imports.
Enforced by `scripts/ci/check-layering.sh` + `cargo-deny`.

Forward-compat is non-negotiable. Public API surface is protected by
`cargo public-api` + `cargo semver-checks` + `cargo deny` +
`#[non_exhaustive]` on every public type. See
[`docs/architecture/forward-compat-invariants.md`](docs/architecture/forward-compat-invariants.md).

---

## Commit convention

Format: `type(scope): lowercase description`.

```
feat(nika-X): admit to workspace — all 12 gates passed
fix(nika-Y): propagate parse error via ? instead of panic
refactor(dx): split oversized hygiene script into modules
docs(roadmap): refresh current state section
chore(deps): bump tokio 1.42 to 1.43
```

Every commit message ends with:

```
Co-Authored-By: Nika 🦋 <nika@supernovae.studio>
```

Full rules: [`.claude/rules/commit-granularity.md`](.claude/rules/commit-granularity.md).

### Banned

- `git add -A` or `git add .` (stage by explicit path).
- `--no-verify` on commits (fix the hook instead).
- `git commit --amend` on pushed commits.
- `Co-Authored-By: Claude` (always Nika).
- Running credential/Keychain/provider tests without inspecting their effects. Use `--lib` for local unit coverage and select hermetic integration tests when the changed contract requires them.

---

## Developer Certificate of Origin

Every PR commit carries a `Signed-off-by` trailer matching the commit
author ([DCO 1.1](https://developercertificate.org) — the Linux-kernel
convention, the lightweight alternative to a CLA). Signing off certifies
you have the right to submit the change under AGPL-3.0-or-later.

```
git commit -s                       # appends: Signed-off-by: Your Name <your-commit-email>
git rebase --signoff origin/main    # repair an existing branch, then force-push it
```

CI enforces this on every PR (`.github/workflows/dco.yml`). Merge
commits and bot-authored commits (`*[bot]`) are exempt, so the heal
lanes keep flowing.

---

## Pull request expectations

- **Atomic.** One logical change per PR. No "feat + refactor + docs" bundles.
- **Tests pass.** `cargo test --workspace --lib` green.
- **Clippy clean.** Zero warnings.
- **Hygiene clean.** `bash scripts/hygiene/check-all.sh` green.
- **No `.unwrap()` / `.expect(` in `src/`.** Use `?` propagation. Enforced by `workspace.lints.clippy.unwrap_used = "deny"`.
- **No `#[allow(dead_code)]`.** Delete or make `pub(crate)`.
- **`#[non_exhaustive]` on every public error enum + response struct.**
- **Files ≤ 2,500 LOC, crates ≤ 25,000 production LOC.** Enforced in CI; the hygiene
  dashboard warns above 1,500 and 15,000 without blocking (ADR-154).
- **One crate admission = one PR.** Never batch two admissions.

### PR review

- Small changes: single reviewer, merge when green.
- Crate admissions: 3-agent review swarm, all P0/P1 fixed in the same session before merge.
- Architecture / ADR changes: explicit escalation, no silent merges.

---

## Reporting issues

- **Bug**: GitHub Issues, include minimal repro and `nika --version`.
- **Feature request** (engine behavior): new features beyond the media capabilities workflows need are out of scope for the 0.124 line. An issue that describes the use case still helps the record; a gap that is a defect of existing behavior is a bug.
- **Language change** (anything normative: syntax, verbs, permits, envelope): the spec's [NEP door](https://github.com/supernovae-st/nika-spec/blob/main/governance/nep-0000-the-nep-process.md) — nobody amends the standard directly, maintainers included. Engine issues cannot change the language.
- **Security vulnerability**: see [`SECURITY.md`](SECURITY.md). Email `security@supernovae.studio`, **not** a public issue.

---

## Code of Conduct

By participating, you agree to uphold the
[Contributor Covenant v2.1](CODE_OF_CONDUCT.md). Contact for reports:
`nika@supernovae.studio`.

---

## Contact

- General: [`nika@supernovae.studio`](mailto:nika@supernovae.studio)
- Website: [nika.sh](https://nika.sh)
- Docs: [docs.nika.sh](https://docs.nika.sh)
- Studio: [supernovae.studio](https://supernovae.studio)

Merci. Nika is a small project that takes quality seriously.
Every contribution — however small — helps keep the diamond clean.