hyodo 3.1.7

Model-agnostic quality-gate kit for AI-assisted developers

HyoDo

A model-agnostic quality-gate kit for AI-assisted developers.

HyoDo helps developers review, score, and ship AI-assisted code with a repeatable quality workflow. Primary surface is the hyodo CLI and CI gates. Optional adapters cover Claude Code, Codex, Grok, Gemini CLI, Cursor, and other agent UIs so AI-generated changes can be inspected before they become trusted code.

Model-agnostic means independent of the AI model or agent UI. It does not mean language-agnostic or a universal gate for every repository. Full hyodo check gates currently target a HyoDo package checkout (pyproject.toml + hyodo/).

---

30-second proof

Proof point	What to inspect
Public package	hyodo/ Python package, pyproject.toml, and hyodo CLI entrypoint
Agent adapters	commands/ slash-command docs (Claude and compatible agents) plus plain CLI
Quality gates	.github/workflows/ci.yml and .github/workflows/smoke.yml
Safety posture	SECURITY.md, docs/SECURITY_SURFACE.md, .env.example, .env.minimal
Routing discipline	Tiered model routing is design intent only; no guaranteed savings claim

If you are reviewing HyoDo for a role, partnership, or technical screen, start with QUICK_START_SIMPLE.md, docs/PROVIDER_PROOF.md, docs/EXTERNAL_CLAIM_AUDIT.md, and the docs/ index. Claude-specific mapping is optional appendix only (docs/ANTHROPIC_PROOF.md).

Who is this for?

HyoDo is for developers and small teams who:

• use AI-assisted coding workflows (any major model vendor or local models);
• want a repeatable review checklist before trusting AI-generated changes;
• need fast local checks for linting, typing, tests, and safety;
• want to route simple tasks away from expensive model calls when possible;
• prefer CLI/CI-first workflows that optional agent UIs can wrap.

What problem does it solve?

AI-assisted development is fast, but speed without review creates risk. HyoDo turns review into a simple operating loop:

AI-assisted change
→ hyodo check   (or /check in an agent adapter)
→ hyodo score + hyodo safe
→ fix or escalate
→ ship with a visible quality trail

The goal is not blind automation. The goal is to make AI-assisted work easier to inspect, safer to merge, and cheaper to operate.

What HyoDo does not claim

• It does not replace human code review, tests, or security review.
• It does not guarantee a fixed cost-reduction percentage.
• It does not automatically approve risky changes just because a score is high.
• It does not paint “all gates passed” when no gates ran (unsupported trees exit 2).
• It does not require the optional philosophy layer to use the practical gates.
• It does not treat Dependabot alerts on optional/legacy afo_core as failures of the public hyodo package.

What is included?

• CLI-first quality loop — hyodo check, hyodo score, hyodo safe, hyodo trinity.
• Agent adapters — commands/ docs for slash-command UIs (Claude Code and compatible tools).
• HyoDo checkout gates — pyright, ruff, pytest (+ optional SBOM when present).
• Scoring utilities — Python package helpers for repeatable review signals.
• Tiered model routing (intent) — optional guidance to prefer FREE/STANDARD/PREMIUM paths by risk and complexity. Not a measured savings product.
• Public package CI — release blockers for the public hyodo package; extended afo_core checks are advisory.

Quick Start

Fastest: PyPI (public package)

pip install -U 'hyodo==3.1.7'
hyodo --version
hyodo safe --help
hyodo score --truth 0.9 --goodness 0.9 --beauty 0.9 --benevolence 0.9 --loyalty 0.9

Full hyodo check release gates need a clone of this repository (see below), not an empty project directory.

Recommended for development: clone, inspect, then run

git clone https://github.com/lofibrainwav/HyoDo.git ~/.hyodo
cd ~/.hyodo

# Optional: inspect the installer before running it
sed -n '1,220p' install_interactive.sh

# Interactive setup
./install_interactive.sh

One-line install for trusted environments

curl -sSL https://raw.githubusercontent.com/lofibrainwav/HyoDo/main/install_interactive.sh | bash

Run with the CLI (recommended, model-agnostic)

cd ~/.hyodo
pip install -e ".[dev]"
hyodo start
hyodo check          # HyoDo checkout only; requires pyproject.toml + hyodo/
hyodo score --truth 0.9 --goodness 0.9 --beauty 0.9 --benevolence 0.9 --loyalty 0.9
hyodo safe           # early warning (exit 0 even with findings)
hyodo safe --strict  # CI-friendly: exit 1 on high-severity findings

Optional: agent slash-command adapter

If you use Claude Code or another slash-command agent that can load commands/:

cd ~/.hyodo
# open your agent of choice, then:
/start
/check
/score
/safe

Requirements

Minimal setup

• Python 3.10+
• Git
• Terminal (any agent UI optional)

Full setup

• Python 3.10+
• Git
• Optional agent CLI (Claude Code, Codex, Grok, Gemini CLI, Cursor, etc.)
• Docker & Docker Compose when using extended local services
• Redis, PostgreSQL, Ollama, or the provided Docker setup only if you need extended modules

Configuration

Minimal configuration

cp .env.minimal .env
# Set provider keys only for the adapters you actually use

Full configuration

cp .env.example .env
# Fill in the services you plan to use

Keep secrets out of git history. Never commit .env files containing real credentials.

Basic Usage

hyodo check     # HyoDo checkout release gates (see exit contract below)
hyodo score     # Calculate review signal (not auto-approval)
hyodo safe      # Lightweight safety early-warning scan
hyodo safe --strict  # Exit 1 when high-severity findings exist
hyodo trinity "describe change"  # Structured review checklist

Score Interpretation

F Score	S Score	Status	Suggested Action
F ≥ 54	S ≥ 8	Excellent	Strong review signal — human approval still required
F ≥ 45	S ≥ 7	Good	Review recommended
F < 45	—	Needs Work	Improve before merge

Scores are decision support, not a replacement for human review. Public API: prefer is_strong_review_signal(); should_auto_approve() is deprecated (removal planned for 4.0.0) and still only returns a review signal.

Quality Gates

HyoDo checkout gates (hyodo check)

Runs only when the target path is a HyoDo package checkout (pyproject.toml and hyodo/ package directory). Otherwise the CLI reports UNSUPPORTED / skip-style outcomes and exits 2 — that is not a validation pass.

Gate 1: Pyright → type checking
Gate 2: Ruff → lint + format
Gate 3: pytest → public tests/
Gate 4: SBOM script (optional; SKIP when absent, never fake PASS)

Exit contract:

Result	Exit	Meaning
At least one gate executed and all PASS	0	All executed gates passed
Any executed gate FAIL	1	Fix and re-run
Path missing, or zero gates executed	2	Not a validation pass

hyodo safe is separate: default mode exits 0 after printing findings; --strict exits 1 on high severity findings (medium alone stays 0).

Tiered model routing (intent only)

HyoDo can help teams think in tiers so not every task goes to a premium model. This is routing guidance, not a cost-savings guarantee.

Tier	Use Case	Example providers (not exclusive)	Cost Profile
FREE / local	Read-only, search, lint, tests	Ollama, local open models	$0 where available
STANDARD	Simple edits, low-risk cleanup	Codex, Gemini, Grok, mid-tier APIs	Low-moderate
PREMIUM	Complex refactors, high-risk decisions	Claude, GPT, Gemini pro tiers, etc.	Higher

No public savings benchmark is linked. Do not claim fixed percentage reductions. If you need enterprise cost proof, measure your own workflows first.

Philosophy Layer: HYOGOOK V5

HyoDo also includes an optional philosophy-driven scoring model called HYOGOOK V5. It evaluates code through six review pillars and uses a geometric mean component so weak dimensions cannot be fully hidden by strong ones.

F = (T + G + In + B + C) + ⁵√(T × G × In × B × C)
S = ⁵√(T × G × In × B × C)

Percent labels below are review emphasis only — they are not used as weights in the F formula above.

Pillar	Review emphasis	Focus
Benevolence	25%	Developer experience, user serenity
Truth	22%	Technical accuracy, architecture
Goodness	18%	Security, stability, ethics
Loyalty	15%	SSOT compliance, project context
Beauty	15%	Clean code, UX, documentation
Eternity	Geometric	Harmony and sustainability

Range: F ∈ [6, 60], S ∈ [1, 10]

Model-agnostic means independent of the AI model or agent UI. It does not currently mean language-agnostic or a universal gate for every repository.

Legacy note: WEIGHTED_V1 used an older five-pillar label set. HyoDo v3.1.0 public docs use the HYOGOOK V5 six-pillar model.

Project Structure

hyodo/              # Public Python package (release surface)
commands/           # Optional agent slash-command adapters
docs/               # Architecture, proof maps, security surface
.github/workflows/  # CI/smoke gates for public package
afo_core/           # Extended/legacy modules (advisory, not public gate)

Documentation

Document	Purpose
QUICK_START_SIMPLE.md	3-minute quick start
docs/PROVIDER_PROOF.md	Model-agnostic proof map
docs/SECURITY_SURFACE.md	Public package vs afo_core security boundary
docs/EXTERNAL_CLAIM_AUDIT.md	Measured audit of external market claims
QUICK_START.md	Detailed guide
install_interactive.sh	Interactive installer (English, minimal-first)
docker-compose.minimal.yml	Optional extended Docker setup
SECURITY.md	Security policy
CHANGELOG.md	Release notes

Contributing

See CONTRIBUTING.md for guidelines.

All contributions are evaluated with practical quality gates first. The HYOGOOK V5 score can be used as an additional review signal, but passing tests, security checks, and human review remains required.

License

MIT License - see LICENSE

Links

• Documentation
• Roadmap
• Changelog
• Security Policy

---

HyoDo — safer AI-assisted development through visible quality gates.