Contributing to Overseer Kit

Overseer Kit v1 is deliberately small: a trusted-host local Git/Muse utility for repository identity, status, and one canonical NEXT handoff. Read README.md, docs/decisions/V1-SCOPE-RESET.md, and tests/README.md before changing it.

Supported scope

The public commands are status, init, sync, adopt, next, and next-write. Keep repository/root/UUID binding, canonical docs/NEXT.md, explicit context checks, stale-state refusal, deterministic source imports, confined atomic writes, and living-document preservation intact.

The owner's scope correction requires a per-repository choice of Git/GitHub only or MuseHub authority with controlled GitHub mirroring. Preserve standalone Git-only operation without a Muse dependency. R1 local authority/adoption is implemented; mirror repair and combined validation remain pending. Use the validation audit and R1 results as the baseline rather than reactivating the entire legacy CLI.

Former hosted, desktop, governance-sync, freeze-review, publishing, registry, receipt, transaction, and orchestration implementations remain historical source. Do not expose them through the v1 entrypoint or treat their old documentation and tests as current requirements.

Development setup

Use Python 3.11 or newer:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-v1-dev.txt
.venv/bin/python -m pytest -q

The default pytest collection is the supported matrix in tests/v1 and tests/retained. Do not delete or rewrite historical tests to obtain a green run. Changes to Muse integration also require the real tests/muse matrix with --muse-python /absolute/muse-venv/bin/python, in addition to the default suite. The pinned Muse environment is separate and requires Python >=3.14. See tests/README.md; no skip may conceal an unavailable supported integration check.

Making a change

1. Start from current main on a feature branch.
2. Keep the change within bounded-v1 scope.
3. Add meaningful supported tests when behavior changes.
4. Run the complete supported suite and git diff --check.
5. Update docs/ROADMAP.md and docs/OVERSEER-HANDOVER.md together when status changes. Only docs/NEXT.md, published through next-write, carries an action.
6. Push the feature branch and open a pull request. Never push directly to main.

Do not commit checkout-local bindings: .overseer/config.yaml, .overseer/bin/, .overseer/local/, docs/NEXT.md, or .cursor/. They contain physical paths and are generated for each initialized checkout. Do not commit secrets, .env*, private keys, consumer content, or machine-specific run logs.

Pull request checklist

• The supported suite passes with exact counts reported.
• No supported requirement is skipped or marked expected-failure.
• Runtime files, VERSION, and pyproject.toml agree when the version changes.
• README and CHANGELOG describe the behavior users actually receive.
• gitleaks or an equivalent secret scan finds no new secret.
• The branch contains no checkout-local paths or bindings.
• No consumer, hook, network operation, release, or deployment occurred without explicit authorization.

Security reports follow SECURITY.md. The MIT license remains in LICENSE.