hyodo 4.4.0

Local AI agent guardrails for FDE and CI — evidence spine, policy DENY, fail-closed quality gates

HyoDo

Local AI agent guardrails for FDE work and CI — audit evidence, policy DENY, fail-closed quality gates.

Not a pre-commit clone. HyoDo helps Forward Deployed Engineers and AI-assisted teams prove what ran, block unauthorized tools, and absorb your existing tests/linters without replacing them.

Review signals never grant automatic approval. Unobserved is never green.

Why HyoDo (vs pre-commit alone)

Need	HyoDo
Agent step audit trail	event record → .hyodo/agent-events.jsonl
Tool / path / step policy	policy check (ALLOW / DENY; missing = exit 2)
Keep existing CI tools	BYOG init absorbs pytest/ruff/npm/go/…
Fake-green resistance	fail-closed score + SKIP ≠ PASS
Air-gapped / on-prem	loopback dashboard, offline-safe design

pre-commit + ruff is still excellent for hooks. HyoDo adds agent evidence + policy gates + honest measurement for FDE deployment defense.

Start here (any repository)

pipx install hyodo
cd your-project
hyodo safe                 # early-warning scan, no setup
hyodo safe --strict        # exit 1 on high-severity findings
hyodo safe --json          # machine-readable findings for CI

# GitHub Actions
- run: pipx install hyodo
- run: hyodo safe --strict --json

hyodo safe is an early-warning scanner, not a full security audit.

Bring your own gates (optional)

hyodo init                 # detect tools → write .hyodo/gates.toml
hyodo check                # run absorbed gates
hyodo dashboard --open     # local evidence panel (127.0.0.1)

init reads tooling you already own (pytest/ruff/mypy/pyright, npm scripts, go.mod, Cargo.toml, Makefile targets). It does not reinvent them. Empty detection → commented starter (no guessing). Malformed or zero executed gates → exit 2 (not a pass).

Agent evidence spine (opt-in FDE)

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

Default storage is digest-only. DENY is recorded for audit; the caller must stop the agent — HyoDo is a gate, not a runtime interceptor. Examples: examples/fde-evidence-spine/.

Engineering map (branding kept, terms first)

DevSecOps label	Pillar	Measured by
Static types	Truth (眞 / 진)	Command gate (typechecker)
Tests + safety	Goodness (善 / 선)	Tests + safe
Lint / format	Beauty (美 / 미)	Command gate (linter)
Public surface	Benevolence (仁 / 인)	Native AST scan
Data privacy	Hyo (孝 / 효)	Native consent/data scan
Audit trail	Yeong (永 / 영)	.hyodo/history.jsonl

Command gates are absorbed tools. AST / ledger pillars are never shell-faked. Missing sources show Not measured. Fail-closed geometric mean (HYOGOOK V5 formula, philosophy V6 labels): any pillar at 0 collapses the review signal. Detail: PHILOSOPHY.md.

Local instrument panel

hyodo dashboard --open
# → http://127.0.0.1:8768

Loopback only; 15s poll of /api/evidence; no composite invention. Measure again now is token-protected.

Install

Python 3.10+. pip install -U hyodo or pipx install hyodo. See Quick Start.

Commands

Command	Purpose
hyodo safe	Safety findings (early warning)
hyodo init	Write .hyodo/gates.toml (BYOG)
hyodo check	Absorbed gates or checkout preset
hyodo event …	Agent event validate / record
hyodo policy check	Agent policy ALLOW / DENY
hyodo score …	Optional review signal
hyodo dashboard	Local evidence panel

safe: 0 findings · 1 high+--strict · 2 bad path. check: 0 all executed PASS · 1 FAIL · 2 none/malformed. event/policy: 0 ok/ALLOW · 1 invalid/DENY · 2 unobserved.

Scope

Surface	Status
hyodo/ package and CLI	Public release surface
tests/ and CI workflows	Release verification

Model-agnostic ≠ language-agnostic. Export PDF audit packs and full runtime interceptors are roadmap items — not claimed shipped.

For contributors

git clone https://github.com/lofibrainwav/HyoDo.git && cd HyoDo
python -m venv .venv && source .venv/bin/activate
python -m pip install -e ".[dev]" && ./.venv/bin/hyodo check

Documentation

• Quick Start · Philosophy
• Security surface
• FDE spine examples
• Changelog · Roadmap

License

HyoDo is available under the MIT License.