orgops 0.1.0b1

Local-first operating-contract validation for checked-out repositories.

OrgOps

OrgOps is a repository-native, local-first operating-contract validator exposed through the oo CLI. It builds a typed evidence graph from a checked-out repository and evaluates explicit expectations without a hosted catalog, account, or remote persistence.

Public v0.1 Commands

• oo validate PATH: evaluate an operating contract.
• oo inspect PATH: show normalized graph evidence and provenance.
• oo contract init [PATH]: create a starter contract.
• oo contract check [PATH]: validate and normalize contract syntax.
• oo contract schema: print the packaged JSON Schema.
• oo mcp: configure and diagnose local agent integration.

The interim topology, ownership, and assess commands are intentionally not part of the public v0.1 surface. Supported topology and ownership evidence is produced by the graph extractors used by inspect and validate.

Start

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

oo contract init --template minimal
oo contract check
oo inspect . --format json
oo validate .

Each repository has one contract:

<git-root>/.orgops/contract.yaml

oo validate . without that contract returns exit code 2 and an initialization hint. There is no hidden built-in baseline.

Agent Workflow

Connect an MCP-capable agent host with:

oo mcp connect --host codex
oo mcp status --host codex

oo mcp config and oo mcp connect emit the absolute path of the installed oo-mcp executable. The --host option is required for connection changes. This prevents an agent host from selecting a different installation through its own PATH.

For Codex, connect injects the configuration through codex mcp add. It does not silently replace a different existing orgops entry. Remove the configuration with:

oo mcp disconnect --host codex

Codex cannot reload MCP tools in an active agent session. After connecting, end that session and start a new one so Codex discovers the OrgOps tools. Claude, Cursor, and generic hosts currently receive manual configuration guidance from connect.

oo mcp status prints a human-readable table followed by YAML containing server readiness and an agent-access matrix. A healthy server does not imply that an agent can access it: connected is verified, not_connected is verified absent or different, unavailable means the host CLI is missing, and unverified means configuration is currently manual.

The MCP server exposes:

• get_contract: load normalized constraints, exceptions, digest, and agent workflow before planning changes.
• validate: evaluate the current repository after each meaningful implementation step.

Repository instructions should require agents to call get_contract before planning, treat its constraints as implementation requirements, and iterate with validate until the result is pass. The checked-in AGENTS.md defines that workflow for this repository. CI remains the final merge gate.

Contract Example

schema_version: v1

contract:
  id: example-repository
  version: 1.0.0
  owners: ["@platform-team"]

rules:
  - id: deny-kafka
    kind: technology.denied
    technology: kafka

  - id: services-require-owner
    kind: service.require-edge
    edge: OWNED_BY

exceptions:
  - id: legacy-worker-kafka
    rule: deny-kafka.v1
    subject: service:compose:compose.yaml:worker
    target: technology:kafka
    reason: Migration in progress
    expires: 2026-09-01

Contracts define expectations, not repository inventory. Services and technologies are discovered from repository declarations.

Evidence Graph

The in-memory graph contains typed repository, service, artifact, technology, owner, workflow, and deployment nodes. Edges are created only from explicit paths, selectors, references, or metadata. Name similarity and Git contribution history never establish service relationships.

Every graph fact has a stable repository-local ID and provenance. Missing relationships produce unknown; OrgOps does not guess.

Decisions And Exit Codes

Decisions are pass, fail, unknown, or excepted. An exact exception may convert one matching fail to excepted; it cannot suppress unknown or execution errors.

• 0: all decisions passed or were excepted
• 1: at least one failure or unknown
• 2: invalid or missing contract/input
• 3: graph construction or evaluation could not execute

JSON output is written before nonzero validation exits:

oo validate . --format json --output orgops-validation.json

Contract Templates

minimal and small-team are editable starting points:

oo contract init --list-templates
oo contract init --template small-team

Templates do not introduce hidden behavior. Validation uses only the explicit rules written into the resulting contract.

Development

python -m pytest orgops/commands orgops/mcp orgops/graph orgops/contracts orgops/validation
python -m build
python -m twine check dist/*.whl dist/*.tar.gz

Release

The public package release uses the OrgOps PyPI Package Publish workflow. Run the same workflow twice:

1. Dispatch with publish_target=testpypi.
2. Wait for the workflow to verify the exact TestPyPI wheel from a clean environment.
3. Dispatch with publish_target=pypi.
4. Wait for the workflow to verify the exact PyPI wheel from a clean environment.

Do not release oo-action@v1 until orgops==0.1.0 installs from real PyPI and the CLI plus MCP smoke commands pass outside the source checkout.