diff --git a/README.md b/README.md index 1bdc70c..dadfcfd 100644 --- a/README.md +++ b/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 diff --git a/docs/REPO_HEALTH.md b/docs/REPO_HEALTH.md new file mode 100644 index 0000000..97d3059 --- /dev/null +++ b/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