Metadata-Version: 2.4
Name: orgops
Version: 0.1.0b1
Summary: Local-first operating-contract validation for checked-out repositories.
Author-email: Sagi Timinsky <info@orgops.org>
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9
Requires-Dist: pyyaml>=5.4
Requires-Dist: pydantic<3,>=2
Requires-Dist: eval-type-backport>=0.3; python_version < "3.10"
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: templating
Requires-Dist: jinja2<4.0.0,>=3.0.0; extra == "templating"
Provides-Extra: dev
Requires-Dist: pytest==9.0.3; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: packaging>=24; extra == "dev"
Requires-Dist: twine; extra == "dev"

# 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

```bash
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:

```text
<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:

```bash
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:

```bash
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

```yaml
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:

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

## Contract Templates

`minimal` and `small-team` are editable starting points:

```bash
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

```bash
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.
