Overseer Kit

Overseer Kit is a small local command-line tool that keeps one trustworthy next-task handoff inside each Git or explicitly selected Muse repository. It helps prevent an agent or operator from using a prompt from the wrong project, branch, lane, or point in history.

The Git-based handoff core is locally validated, but intended v1 is incomplete. The intended product lets each repository choose Git/GitHub only or MuseHub as its source of truth with a GitHub mirror. The mirror workflow documents explicit preparation, verification and separately authorized delivery. Git-only is a permanent supported choice: no Muse installation, account, or migration is required. R1 implements optional local Muse handoffs and explicit adoption; R2 adds controlled mirror preparation and retry. R3 reconciles the source in isolation and validates combined local operation. The source version 1.0.0 is an unpublished candidate, and its Git-only release is on hold. The behavior described below is the current implementation, not the completed Muse-first product. See the scope decision and the complete validation record.

What it does

Each initialized repository receives:

• a persistent UUID and exact physical-root binding in .overseer/config.yaml;
• a repository-bound launcher at .overseer/bin/ok;
• one canonical handoff in docs/NEXT.md;
• small ROADMAP and HANDOVER documents when they do not already exist.

Before printing NEXT, Overseer checks the repository UUID and root, selected VCS branch, configured lane and model label, action ID and kind, prompt digest, expected NEXT digest when supplied, and authoritative revision freshness. Muse mode also pins the Muse repository identity, store, separate Python environment and package source digest. A copied launcher, copied config, stale handoff, wrong repository, wrong lane, wrong branch, or stale writer is refused without printing the prompt.

The public commands are:

What it does not do

Overseer does not decide what task should come next, execute a prompt, infer that work is complete, verify which AI model is actually running, or judge whether task prose is strategically correct. The operator or agent chooses the task and advances it explicitly with next-write.

Local handoff commands and mirror preparation stay offline. Only explicitly invoked mirror deliver observes Hub/GitHub, pushes the verified distribution commit and creates or verifies its PR. It never merges, releases or deploys. The kit has no hosted service, registry, background process, telemetry, automatic updater, transaction system, or OCI machinery. It supports local Git and Muse code-domain checkouts and linked worktrees. Moving an initialized checkout or moving the kit installation requires an explicitly reviewed rebind; copying is not migration.

Prepare the source installation

Use Python 3.11 or newer and keep this checkout at a stable physical path. The kit uses its own conventional virtual environment; consumer repositories do not install its Python dependencies.

cd /absolute/path/to/overseer-kit
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-v1.txt
./cli/ok --version

Install from the latest published v1.* release or from a reviewed source checkout. Do not treat an unreviewed feature branch as an update. Before the first v1 release is published, only the validated local release candidate is available.

For development and the supported test suite:

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

Muse is optional and stays in its own conventional venv: The supported integration uses exactly Muse 0.2.1rc5 with Python 3.14 or newer. The kit itself still supports Python 3.11 or newer and does not install Muse. To run the additional real Muse matrix:

.venv/bin/python -m pytest -q tests/v1 tests/retained tests/muse \
  --muse-python /absolute/path/to/muse-venv/bin/python

The supported CI entrypoint is tools/ci/supported_v1.py, run with this source installation's .venv/bin/python and a required --junitxml PATH. Supplying --muse-python /absolute/muse-venv/bin/python selects the full Git/Muse/mirror matrix and checks the exact reviewed rc5 package source digest. Omitting it runs the permanent Git-only matrix. No CI step publishes or installs hooks.

.github/workflows/supported-v1.yml defines Git jobs for Python 3.11/3.14 and the combined job for Python 3.14 on Linux. Hosted execution is not yet evidenced. The combined job needs repository variable MUSE_RC5_URL pointing to a retained HTTPS archive whose SHA-256 is 1a17ee8792e423927ff07ac96c85de0016bc7f79ebacc4e8a8e5073b436f2ea6. It fails if the variable or exact archive is unavailable. Staging's moving installer now selects rc11; its rc5 release URL returned 404 during R3. Do not substitute another version or the unverified PyPI package named muse. R3's fresh local environment used a wheel reconstructed from verified installed rc5 files plus freshly installed dependencies; this is not proof that the original upstream archive can be installed on a clean host. Artifact availability, hosted CI, and Linux/3.11 execution remain release prerequisites. See the exact validation results.

Muse rc5's recursive code add . can omit a new dot-directory. Explicitly stage .github/workflows/supported-v1.yml when preparing this source, and compare the actual committed manifest before using it as a distribution or CI input.

Add one repository

Use the repository's absolute path. Initialization preserves existing ROADMAP and HANDOVER files and refuses an existing unmanaged launcher.

./cli/ok -C /absolute/path/to/project init \
  --vcs git \
  --repo-name PROJECT-NAME \
  --lane product \
  --model 'GPT-6 Astra'

Automatic editor hooks are off by default. Keep them off unless you deliberately review and authorize hook installation for that repository.

For an already prepared Muse checkout, select --vcs muse --muse-python /absolute/path/to/muse-venv/bin/python. An uninitialized mixed checkout requires an explicit choice. An existing Git binding remains Git even if Muse metadata appears later. init and sync never change its authority. See adoption and rollback before changing modes.

Daily use

From an initialized repository:

./.overseer/bin/ok status
./.overseer/bin/ok next

status --json is useful for automation. A dirty repository is reported but does not by itself invalidate NEXT. A changed branch, a later authoritative commit, altered prompt, wrong identity, or changed runtime does invalidate it. Exit codes are 0 for success, 1 when status can report identity but NEXT is invalid, and 2 for refusal or usage errors.

Muse freshness uses its own branch and revision, regardless of a nearby Git HEAD. Publication is always not_checked_offline on these local commands; a valid local NEXT says nothing about MuseHub acceptance or GitHub delivery. Muse dirty state compares regular working files with the branch snapshot and reports a nonempty shared stage as dirty. R1 does not certify executable modes, symlinks, or a separate per-worktree Muse staging index.

Use the expectation options when resuming a previously read handoff:

./.overseer/bin/ok next \
  --repo-id UUID-FROM-STATUS \
  --branch BRANCH-FROM-STATUS \
  --lane product \
  --model 'GPT-6 Astra' \
  --action-id EXPECTED-ACTION \
  --action-kind implement \
  --expect-next DIGEST-FROM-STATUS

Publish the next handoff

Store the new prompt in a regular UTF-8 file inside the consumer repository, then run the kit installation's writer. All context fields and the current raw NEXT digest are required:

/absolute/path/to/overseer-kit/cli/ok -C /absolute/path/to/project next-write \
  --repo-id UUID-FROM-STATUS \
  --branch CURRENT-BRANCH \
  --lane product \
  --model 'GPT-6 Astra' \
  --action-id TASK-1 \
  --action-kind implement \
  --expect-next DIGEST-FROM-STATUS \
  --prompt-file prompt.txt

Action kinds are plan, implement, review, maintain, and stop. Use stop when no executable task is queued. The writer compares the previous digest, locks cooperating writers briefly, writes a unique temporary file, flushes it, and replaces NEXT atomically. It changes no other consumer document.

Muse writers additionally require --vcs muse --base-head CURRENT-MUSE-REVISION. Use --base-head unborn before the first commit. Commit application work first, then publish ignored NEXT against the new revision. Git accepts the same explicit revision options; its legacy tracked-NEXT closing-commit exception remains supported.

Simple update notifications

Overseer deliberately does not check the internet in the background. The simplest notification system is GitHub's existing release watcher:

1. Open the repository on GitHub.
2. Select Watch → Custom → Releases.
3. GitHub will notify you when a maintainer publishes a new release.

This needs no Overseer server or OCI registry. Maintainers should increment VERSION, update CHANGELOG.md, tag the tested commit, and publish a GitHub Release only when a build is ready for users. A version in the source tree is not itself a published release; verify that the matching GitHub Release exists before updating. For the intended Muse-first release, accept the reviewed source in MuseHub first, then verify its GitHub mirror before tagging and announcing that same version. That restored publication procedure remains pending; this is the required order.

Users can also check manually, with no changes to their working files:

git -C /absolute/path/to/overseer-kit fetch --tags origin
git -C /absolute/path/to/overseer-kit status --short --branch
git -C /absolute/path/to/overseer-kit log --oneline HEAD..origin/main

Review the release notes before updating. After bounded v1 is released on main, a clean source installation can update explicitly:

git -C /absolute/path/to/overseer-kit pull --ff-only
/absolute/path/to/overseer-kit/cli/ok -C /absolute/path/to/project sync --dry-run
/absolute/path/to/overseer-kit/cli/ok -C /absolute/path/to/project sync

Run sync once for each initialized repository. A source change intentionally makes status/NEXT refuse with runtime_changed until that explicit sync updates the runtime pin. sync --dry-run shows the planned managed-file changes first. It preserves the repository UUID, NEXT, ROADMAP, HANDOVER, and application files.

Validation and limits

Bounded v1 passed architecture and completed-build review, clean dependency installation, current/previous rollback, 77 supported tests, and 32 checks in an authorized DINERO consumer pilot. That pilot preserved all existing consumer files and its preexisting uncommitted edit while keeping automatic hooks disabled.

Validation used Python 3.14.4 on Darwin arm64 and a fixed-path source installation. It does not establish packaged installation, other-platform compatibility, concurrent commands during source replacement, or automatic migration/rebinding. The trusted-host design protects against stale state and ordinary mistakes; it is not a security boundary against a malicious administrator or process with the same user account.

Historical pre-reset commands remain in cli/legacy_main.py for evidence but are outside the public v1 command surface. Historical test sources remain preserved; see test scope.

The Muse restoration audit records verified reuse, bridge defects, authority and handoff design, and the remaining milestones. Do not run the historical deploy script to publish this candidate. OCI remains excluded.