docs: add repository health contract

README.md

@@ -10,6 +10,8 @@
 
 In 2026, code is written by fleets of AI agents. Arbiter knows *who* wrote each line -- human or AI -- and scores quality accordingly.
 
+Repository health, validation, and stewardship expectations are tracked in [docs/REPO_HEALTH.md](docs/REPO_HEALTH.md).
+
 ## Install
 
 ```bash

docs/REPO_HEALTH.md

@@ -0,0 +1,88 @@
+# Repository Health Contract
+
+## Identity
+
+- **Repository**: `hummbl-dev/arbiter`
+- **Canonical URL**: `https://github.com/hummbl-dev/arbiter`
+- **Package distribution**: `arbiter-score`
+- **CLI**: `arbiter`
+- **Owner**: HUMMBL Team
+- **Stewardship scope**: Deterministic, agent-aware code quality scoring, PR diff scoring, contribution tracking, analyzer integration, leaderboard reporting, and governance quality gates.
+
+## Lifecycle
+
+- **Status**: Active public repository and PyPI-oriented package.
+- **Default branch**: `main`.
+- **Current package version**: `0.6.0`.
+- **Release posture**: Core scoring logic, analyzer integrations, CLI surfaces, CI templates, and governance-reporting features may continue through reviewed pull requests.
+- **Archive trigger**: Archive only if the Arbiter scoring package and reusable quality-gate workflow are superseded by another declared canonical source of truth.
+
+## Source Of Truth
+
+- `pyproject.toml` defines package metadata, optional analyzer dependencies, test dependencies, and the `arbiter` CLI entry point.
+- `src/arbiter/` contains the importable package and CLI implementation.
+- `tests/` contains the validation suite for scoring, analyzers, CI templates, governance quality, reports, API behavior, and contribution tracking.
+- `.github/workflows/ci.yml` is the primary PR and push validation workflow.
+- `.github/workflows/arbiter-quality-gate.yml` is the reusable workflow contract for downstream quality gates.
+- `docs/CERTIFICATION_REPORT.md`, `docs/PLATFORM_DESIGN.md`, and related docs describe certification and platform behavior.
+- `README.md` is the public overview and should stay aligned with package metadata, install commands, analyzer extras, and CLI behavior.
+
+## Required Local Validation
+
+Before merging non-trivial code changes:
+
+```bash
+python -m pip install -e ".[test]"
+PYTHONPATH=src python -m pytest tests/ -v --ignore=tests/test_api.py
+PYTHONPATH=src python -m pytest tests/test_api.py -v
+```
+
+Analyzer and quality-gate changes should also run:
+
+```bash
+python -m pip install -e ".[analyzers]"
+arbiter score . --fail-under 90
+arbiter diff . --base main --fail-under 70
+```
+
+Documentation-only changes should at minimum pass:
+
+```bash
+git diff --check
+```
+
+## CI Expectations
+
+Expected GitHub Actions coverage:
+
+- `.github/workflows/ci.yml` runs the test suite on Python 3.11 and 3.12.
+- `.github/workflows/ci.yml` runs `tests/test_api.py` separately after the main test pass.
+- `.github/workflows/ci.yml` runs a self-grade gate with `arbiter score . --fail-under 90`.
+- `.github/workflows/ci.yml` runs PR diff scoring with `arbiter diff . --base origin/main --fail-under 70`.
+- `.github/workflows/publish.yml` builds and verifies the package before PyPI publish.
+- `.github/workflows/arbiter-quality-gate.yml` provides the reusable downstream diff-score gate.
+- `.github/workflows/weekly-leaderboard.yml` runs scheduled leaderboard generation.
+
+## Branch Protection Expectation
+
+`main` should require pull request review and the hosted CI checks that protect tests, API behavior, self-grade threshold, and PR diff-score threshold.
+
+Branch protection is tracked centrally in `hummbl-dev/hummbl-dev#18`; do not overclaim required checks until that audit is updated.
+
+## Operational Notes
+
+- The core package should remain usable without analyzer extras; analyzer-specific integrations belong behind optional extras.
+- Public install instructions must match `pyproject.toml` package metadata and published distribution names.
+- Self-grade and reusable quality-gate thresholds are product contracts, not decorative metrics.
+- Changes to scoring formulas, analyzer weights, noise thresholds, or agent attribution should include before/after evidence.
+- Generated scoring artifacts such as local JSONL audit files should not be treated as source-of-truth documentation unless explicitly committed by design.
+
+## Fleet Scan Classification
+
+Future fleet scans can classify this repository as:
+
+- **Lifecycle**: active public package
+- **Visibility**: public
+- **Primary function**: deterministic code quality and governance scoring
+- **Validation entrypoint**: `pytest` plus Arbiter self-grade
+- **Primary metadata owner**: HUMMBL Team