Metadata-Version: 2.5
Name: hyodo
Version: 4.19.7
Summary: Open, model-agnostic evidence and verification for AI-assisted systems. Reuse your checks; missing evidence stays UNOBSERVED; scores never authorize.
Project-URL: Homepage, https://github.com/lofibrainwav/HyoDo
Project-URL: Documentation, https://github.com/lofibrainwav/HyoDo#readme
Project-URL: Repository, https://github.com/lofibrainwav/HyoDo
Project-URL: Issues, https://github.com/lofibrainwav/HyoDo/issues
Project-URL: Changelog, https://github.com/lofibrainwav/HyoDo/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/lofibrainwav/HyoDo/blob/main/SECURITY.md
Author: AFO Kingdom
License-Expression: MIT
License-File: LICENSE
Keywords: ai,automation,claude,claude-code,cli,code-quality,code-review,codex,gemini,grok,hygook-v5,llm,model-agnostic,trinity-score
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: jsonschema<5,>=4.18
Requires-Dist: referencing>=0.28.4
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli>=1.2.0; python_version < '3.11'
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: cyclonedx-bom<9,>=7.0; extra == 'dev'
Requires-Dist: httpx<1,>=0.27; extra == 'dev'
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mcp<3,>=1.27; extra == 'dev'
Requires-Dist: pip>=25.0; extra == 'dev'
Requires-Dist: pyright>=1.1; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=7.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=1.27; extra == 'mcp'
Provides-Extra: mutation
Requires-Dist: cosmic-ray==8.7.0; extra == 'mutation'
Requires-Dist: mutmut==3.7.0; extra == 'mutation'
Description-Content-Type: text/markdown

# HyoDo

**See which checks ran on AI-assisted work, what they found, and what remains
unknown.**

HyoDo is an open-source Python tool that runs on your computer. It reuses the
tests and linters your project already has, reports their results, and marks
missing evidence `UNOBSERVED`. That means there is not enough evidence to say
whether a check passed or failed. HyoDo helps people review work; it does not
approve merges or deployments.

[![CI](https://github.com/lofibrainwav/HyoDo/actions/workflows/ci.yml/badge.svg)](https://github.com/lofibrainwav/HyoDo/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/hyodo)](https://pypi.org/project/hyodo/)
[![Python](https://img.shields.io/pypi/pyversions/hyodo)](https://pypi.org/project/hyodo/)
[![License](https://img.shields.io/github/license/lofibrainwav/HyoDo)](./LICENSE)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/lofibrainwav/HyoDo/badge)](https://scorecard.dev/viewer/?uri=github.com/lofibrainwav/HyoDo)

## Why HyoDo exists

HyoDo helps you inspect AI-assisted work: which project checks ran, what they
found, and what remains unknown. Its guiding idea, Hyo (孝), is that technology
should respect people's time and choices, and carry its share of the burden
instead of passing it back to them. HyoDo records evidence; people decide what
to do with it.

AI coding tools can move quickly, but a normal green check does not always
answer:

- Did the check actually run?
- Did the agent touch only approved tools and paths?
- Was missing or unreadable evidence treated as a pass?

HyoDo makes those boundaries explicit with local evidence, policy decisions,
and fail-closed exit contracts.

## 30-second start

```bash
pipx install hyodo
cd your-project
hyodo safe --strict
hyodo init
hyodo check
```

`safe` works immediately in any repository. `init` is optional: it detects
tools you already use and writes `.hyodo/gates.toml`; `check` then runs those
gates. No detected tooling means no invented green check. See
[`docs/GATES_SYNTAX.md`](./docs/GATES_SYNTAX.md) for every `gates.toml` field.

Commit `.hyodo/gates.toml` and `.hyodo/policy.toml` (team-shared policy); keep
the rest of `.hyodo/` out of version control — see
[what to commit](docs/CONNECT.md#what-to-commit) for the `.gitignore` split.

## What it does

| Need | HyoDo surface |
| --- | --- |
| Early-warning safety scan | `hyodo safe` |
| Reuse existing project checks | `hyodo init` → `hyodo check` |
| Agent action audit trail | `hyodo event record` |
| Tool / path / step policy | `hyodo policy check` |
| Schema / eval / evidence report | `hyodo schema`, `eval`, `report` |
| Local evidence panel | `hyodo dashboard --open` |
| Optional MCP adapter | `hyodo mcp stdio` / `serve` |

## Boundaries and current status

HyoDo provides local checks and evidence contracts; it does not grant execution
authority or turn missing evidence into a pass. `hyodo safe` is an early-warning
scan, not a full security audit, and callers must enforce DENY decisions. The
package stores evidence digests and receipts, not captured payloads. See the
[product boundary](./docs/PRODUCT_BOUNDARY.md), [measured state snapshot](./docs/CURRENT_STATE.md),
and [security model](./SECURITY.md) for the authoritative details.
The legacy HyoDo Integrity Score command is advisory only. It retains a
five-input geometric-mean method for compatibility; `HYOGOOK V5` is its
internal name.
HyoDo's replacement evaluation model is being updated; it does not define the
six reference values as one canonical score. The current package does not yet
provide a general per-axis evaluator. Current source status may differ from
the latest published package.

## Use your existing CI

```yaml
- uses: actions/setup-python@v5
  with:
    python-version: "3.12"
- run: pip install hyodo
- run: hyodo safe --strict --json
```

```yaml
- uses: lofibrainwav/HyoDo/.github/actions/hyodo@vX.Y.Z
```

`init` detects existing test and lint tooling. Empty or malformed gate
configuration exits **2**, not **0**. See the [gate configuration reference](./docs/GATES_SYNTAX.md).

## Hooks and SARIF

Pin a signed release containing the hooks (`v4.11.0` predates them):

```yaml
- repo: https://github.com/lofibrainwav/HyoDo
  rev: vX.Y.Z
  hooks: [{id: hyodo-check}, {id: hyodo-safe-strict}]
```

`hyodo report --format sarif` writes a SARIF 2.1.0 visibility report.
Measured DENY and unreadable-ledger conditions become alerts; `hyodo check`
remains the fail-closed gate for missing or unmeasured quality evidence.

## Optional agent evidence

```bash
hyodo event validate --file step.json
hyodo event record --file step.json --root . --policy .hyodo/policy.toml
hyodo policy check --file step.json --config .hyodo/policy.toml
hyodo schema check --schema agent.schema.json --payload step.json --json
```

Default event storage is digest-only. See
[`examples/fde-evidence-spine/`](./examples/fde-evidence-spine/) for a demo
event and [`examples/host-policies/`](./examples/host-policies/) for a
dual-host `allowed_tools` list (not a Cursor hook). Policy trust:
[docs/POLICY_TRUST.md](docs/POLICY_TRUST.md).

## Optional MCP

```bash
pip install 'hyodo[mcp]'
hyodo mcp stdio --root .                       # local stdio
hyodo mcp serve --bind tailscale --bind-ip 100.99.88.77 \
  --token "$HYODO_MCP_TOKEN" --root .          # private-network connector
```

The MCP adapter uses the same CLI contracts rather than a second engine.
`mcp.hyodo.app` is contract-only, not this path.

## Install and support

Python **3.10+**: `pipx install hyodo` or `pip install -U hyodo`.

- Docs index: [`docs/README.md`](./docs/README.md)
- Command contracts and first-run steps: [`QUICK_START.md`](./QUICK_START.md)
- Node.js: [`docs/onboarding-nodejs.md`](./docs/onboarding-nodejs.md)
- Security: [`SECURITY.md`](./SECURITY.md);
  Issues: [GitHub Issues](https://github.com/lofibrainwav/HyoDo/issues)
- Contributing: [`CONTRIBUTING.md`](./CONTRIBUTING.md);
  Changelog: [`CHANGELOG.md`](./CHANGELOG.md)

## License

MIT. See [`LICENSE`](./LICENSE).
