Metadata-Version: 2.4
Name: project-supervisor
Version: 0.5.0
Summary: Project-neutral autonomous multi-agent supervision control plane
Author: ProjectSupervisor contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Smkzz/project-supervisor
Project-URL: Repository, https://github.com/Smkzz/project-supervisor
Project-URL: Issues, https://github.com/Smkzz/project-supervisor/issues
Project-URL: Changelog, https://github.com/Smkzz/project-supervisor/blob/main/CHANGELOG.md
Keywords: agent orchestration,developer tooling,supervision
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.12; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Dynamic: license-file

# Project Supervisor

Project Supervisor is the project-neutral control plane for autonomous
multi-agent software development. Projects provide a strict YAML adapter; the
supervisor provides atomic queueing, leases, worktree/evidence roots, shell-free
verification, recovery decisions, and typed handoff contracts.

This `0.5.0` release is the reusable control-plane foundation. It now has atomic
SQLite ownership transitions, lease heartbeat/expiry/release, bounded command
execution, evidence manifests, and structured handoffs. OS-agent launching,
independent-review orchestration, and project cutover remain deliberately
separate provider work.

## Install in any GitHub project

The package is designed to be installed into each consuming project rather than
copied into it:

```powershell
python -m pip install project-supervisor
project-supervisor init
# edit .project-supervisor.yaml and ensure its status_file exists
project-supervisor check
```

`init` creates `.project-supervisor.yaml` in the current project. Once present,
the adapter is discovered automatically from the project root or a child
directory. The explicit form remains available for scripts and CI:

```powershell
project-supervisor --project C:\path\to\project\.project-supervisor.yaml check
```

For a GitHub checkout before a PyPI release exists:

```powershell
python -m pip install "project-supervisor @ git+https://github.com/Smkzz/project-supervisor.git@main"
```

For stable automation, pin a release tag or PyPI version. The consumer templates in
`templates/project/` include a pinned requirements file, Dependabot config,
and a scheduled compatibility workflow. Dependabot opens a reviewable upgrade
PR whenever a new release is published; the workflow validates the installed
version. This is the automatic-update path for existing projects while keeping
their dependency state visible and reproducible.

The package repository includes GitHub Actions for test/build checks and PyPI
trusted publishing on `v*` tags. Publishing still requires a real GitHub remote,
the PyPI project name, and trusted-publisher configuration.

The complete repository/PyPI setup checklist is in
`docs/GITHUB_RELEASE_CHECKLIST.md`.

## Development gates

```powershell
python -m pip install ".[dev]"
python -m ruff check project_supervisor tests
python -m ruff format --check project_supervisor tests
python -m mypy project_supervisor
python -m pytest --cov=project_supervisor --cov-report=term-missing --cov-fail-under=75
python -m build
python -m twine check dist/*
python -m pip check
```

The release is intentionally tag-driven: the `vX.Y.Z` tag must match the
single-sourced package version before PyPI publishing is allowed.

## Adapter contract

```yaml
schemaVersion: 1
project:
  name: demo
  root: C:/path/to/project
  markers: [package.json]
  queue_file: .supervisor/queue.yaml
  status_file: STATUS.md
  state_db: .supervisor/state.sqlite3
  evidence_root: .supervisor/evidence
  worktree_root: .supervisor/worktrees
  job_id_pattern: 'JOB-[0-9]+'
  max_retries: 2
  capabilities:
    snapshot_read: true
    verification: true
    queue: true
    worker_launch: false
    independent_review: false
    hosted_gate: false
    publish: false
  verification_profiles:
    fast:
      commands:
        - argv: [python, -m, pytest, -q]
          cwd: .
          timeout_seconds: 300
          shell: false
          side_effects: read_only
  snapshot:
    sources:
      - path: orchestration/state.json
        format: json
        role: runtime
        optional: true
  worker_profiles: {}
  reviewer_profiles: {}
  protected_paths: [.git, .supervisor]
  agent_scopes:
    implementer: [src]
    verifier: []
    reviewer: [docs/reviews]
```

All configured paths are relative to the project root and are checked for
containment. Commands use explicit `argv`, relative `cwd`, bounded timeout,
optional non-secret environment values, `shell: false`, and an explicit
`side_effects` declaration (`read_only`, `control_plane`, `project`,
`external`, or `unknown`). The package does
not assume `backend`, `frontend`, Flutter, Node, or any other repository
layout. Capabilities are explicit so the supervisor can fail closed when a
project has not yet supplied a worker, reviewer, hosted-gate, or publish
integration.

## Inspect and verify a project

```powershell
python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml paths
python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml check
python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml snapshot
python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml verify --job-id JOB-1 --profile fast
python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml shadow-verify --profile fast
python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml coordinate --job-id JOB-1 --agent-id worker-1 --reviewer-id reviewer-1 --revision abcdef1
```

Verification writes a deterministic command manifest below the adapter's
contained evidence root. A failed command returns a non-zero exit code and is
never reported as a pass.

Shadow verification runs only commands explicitly declared `side_effects:
read_only`. It reports `accepted: false`, does not mutate queue, state,
worktrees, or evidence, and refuses delegated commands that may reconcile a
control plane or touch the project. Use ordinary `verify` only after accepting
the declared side effects. The `snapshot` command reads adapter-declared JSON
and Markdown sources into one normalized, provenance-hashed view.

## Queue lifecycle

```powershell
python -m project_supervisor.cli --project adapter.yaml queue-init
python -m project_supervisor.cli --project adapter.yaml queue-add --job-id JOB-1 --payload-json '{"goal":"run tests"}'
python -m project_supervisor.cli --project adapter.yaml queue-claim --job-id JOB-1 --agent-id agent-1
python -m project_supervisor.cli --project adapter.yaml queue-heartbeat --job-id JOB-1 --agent-id agent-1 --lease-token TOKEN
python -m project_supervisor.cli --project adapter.yaml queue-complete --job-id JOB-1 --agent-id agent-1 --lease-token TOKEN --event-id evt-1 --status completed --result-json '{"ok":true}'
```

Claims, completion, heartbeat, release, and expiry use SQLite write
transactions. A late or mismatched lease cannot complete another worker's job;
repeated completion with the same event ID is idempotent.

The typed gate API consumes concrete command results, evidence validation,
review handoffs, canary results, and approval records. The older boolean gate
function remains only as a compatibility shim and is not sufficient for
acceptance.

The provider interface supports Codex/local workers. The coordination API runs
one worker and then one distinct reviewer only when the adapter declares both
capabilities; it requires complete handoffs, safe changed paths, exact
revision/tree identity, and validated evidence before returning `APPROVED`.
Adapters provide those processes through `worker_profiles` and
`reviewer_profiles`; profile argv values are explicit, shell-free templates
with only `job_id`, `agent_id`, `revision`, `tree`, and `handoff_path` fields.
Each coordinate run writes `coordination.json` beside its evidence. It does not
claim a queue lease automatically; callers must claim a generic queue lease
first. The command extends that lease for its declared budget, then completes
or releases it according to the final coordination state.
The example adapters under `examples/` cover Flutter and Gomoku without
machine-specific roots, but intentionally leave worker/reviewer launch
capabilities disabled until each project has a reviewed integration provider.
