# Contributing — mgf-hrb

`mgf-hrb` is a Magogi Foundation sibling and **inherits the
cross-project engineering standards** from
[`mgf-common`](https://codeberg.org/magogi-admin/mgf-common).
This file is short on purpose; the canonical contributor guide
is the federation contract.

**Dual-language repo.** `mgf-hrb` is a single repo with two sides of a
no-FFI boundary: the **Zig broker** in [`hrb-code/`](hrb-code/) (kernel
side — enforcement, hardware, hot path) and the **Python SDK** in
[`src/mgf/hrb/`](src/mgf/hrb/) (ergonomics, policy, tooling). They live
together so the two sides of the Unix-socket wire protocol never skew.
The federation standards below govern the **Python SDK**; the Zig side
is governed by its own conformance contracts (the kabi behavioural
suite [`hrb-code/src/conformance.zig`](hrb-code/src/conformance.zig) and
the S1–S5 survivability bar). See [`STANDARDS_NOTE.md`](STANDARDS_NOTE.md)
for the deeper reasoning.

## First read

1. [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) — the contract.
2. [mgf-standard/docs/standards/](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/) — the rule corpus.

## Rule families (quick reference)

| Family | Covers                                                |
|--------|-------------------------------------------------------|
| AP-*   | API stability tiers, deprecation cycle                 |
| CF-*   | Layered config + env-var precedence                    |
| DEP-*  | Pin discipline, transitive caps                        |
| DOC-*  | Docs layout (universal-5 + sibling MUSTs)              |
| DP-*   | Design principles (frozen types, TZ-aware, …)          |
| EH-*   | Typed exception hierarchy                              |
| FB-*   | Feedback discipline (PAPER-NN flow)                    |
| LG-*   | Structured logging, redaction, audit emission          |
| PR-*   | Presentation-layer separation (SDK forbids UI frameworks) |
| REL-*  | Build → test → tag → push → upload order               |
| SC-*   | Atomic writes, redaction, secret handling              |
| TS-*   | Test discipline, four-gate CI                          |

## Dev setup

**Python SDK** (editable, with dev tools):

```sh
uv venv && uv pip install -e '.[dev]'
```

**Zig broker** (from this same repo — Zig 0.16; no `zig` on PATH?
`uv pip install ziglang` and alias `zig` to `python3 -m ziglang`):

```sh
scripts/zig-fetch-deps            # cache carved Zig deps (one-time)
cd hrb-code && zig build && ./zig-out/bin/mgf-hrb-server
```

## Process

1. **Bug / feature:** file in [FEEDBACK.md](FEEDBACK.md)
   (sibling-scoped) — or in
   [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md)
   if cross-cutting (per DOC-13 / FB-04).
2. **PR:** branch from main; run the gates locally for the side you
   touched:
   ```sh
   # Python SDK — four-gate CI:
   .venv/bin/python -m ruff check src/ tests/
   .venv/bin/python -m mypy --strict src/
   .venv/bin/python -m pytest
   .venv/bin/python -m coverage report
   .venv/bin/python -m import_linter      # PR-01 / PR-06 layering contracts
   # Zig broker — behavioural + survivability suite:
   cd hrb-code && zig build test --summary all
   # Cross-language E2E (after `zig build`):
   pytest -m e2e
   # Or the budget-aware supervisor across both sides:
   scripts/mtest --tier 0-1 --budget 60s
   ```
3. **CHANGELOG.md:** add an `[Unreleased]` entry per
   [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
4. **Public-API delta:** update [PUBLIC_API.md](PUBLIC_API.md)
   in the same PR; the pinned test gate will catch a missed entry.
5. **Decisions:** if the change carries a non-obvious tradeoff, add a
   `D-NNN` entry to [DECISIONS.md](DECISIONS.md).
6. **Reviewer:** the federation owner (mgf-common maintainer).

## Release flow

See [REL-* in mgf-common standards](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/RELEASING.md).
The Python SDK wheel is built + published **from this monorepo** via
`scripts/publish-wheel` (the broker and SDK deliberately stay in one
repo so the two sides of the no-FFI wire protocol never skew). Short
version: bump → regen PUBLIC_API.json → build → test → `twine check`
→ commit → tag → push tag → upload.

## See also

- [STARTHERE.md](STARTHERE.md) — entry point
- [INDEX.md](INDEX.md) — deep navigator (design, code, decisions, recipes)
- [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) §7 — feedback discipline
- [mgf-common/CONTRIBUTING.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/CONTRIBUTING.md) — the canonical contributor guide
