rune/docs/structural-contract.md

Structural Contract — henxels Adoption (#138)

The repo's shape is machine-checkable. henxels.yaml (repo root) holds the contract; henxels sync renders it into the AGENTS.md digest agents read; henxels check --all --plain enforces it (exit 0 = green, 1 = red) and runs as a CI lint-job step.

What the contract governs

Henxel	Scope	Rule
Canaries registered in CI	./src/rune/canary_*.py	Custom statement ci_runs_all_canaries (in henxels_checks.py): every canary on disk must appear in .gitea/workflows/ci.yml
No secrets	whole repo	no_secrets — no credentials in tracked files
Plans	./plans	markdown only, kebab-case filenames
Docs	./docs/*	.md/.yaml only, except docs/v1/** and docs/wiki/**
File-size debt	./src/rune	max_lines: 1200, except the documented debt list below

Warnings (non-blocking): near-duplicate file detection (the shared/ vs src/rune/ copies and backups/ snapshots are pre-existing debt the warning correctly keeps visible).

Debt table

Known violations, explicitly excepted in henxels.yaml instead of silently ignored. Each entry lists the finding that forced the exception.

File / spot	Rule	Finding	Disposition
src/rune/rune_tui.py	max_lines 1200	4231 lines (drafted exception)	except-listed; split is future work
src/rune/rune_operator.py	max_lines 1200	1265 lines (drafted exception)	except-listed; split is future work
src/rune/local_tool_runtime.py	max_lines 1200	506 lines — drafted as pre-emptive headroom, not currently over budget	except-listed (as drafted)
src/rune/memory_store.py	max_lines 1200	2171 lines (live finding)	except-listed; split is future work
src/rune/curator.py	max_lines 1200	1597 lines (live finding)	except-listed; split is future work
src/rune/tool_executor.py	max_lines 1200	1523 lines (live finding)	except-listed; split is future work
src/rune/warm_router.py	max_lines 1200	1292 lines (live finding)	except-listed; split is future work
tests/test_gitea_provision.py	no_secrets	flagged as hardcoded credential — actually synthetic fixture tokens (plaintext-transport-test-secret etc.) whose purpose is asserting tokens never leak	except-listed (false positive)
src/rune/canary_native.py	canary gate	tui_validator's import allowlist drifted from rune_tui.py (from __future__ import annotations, bare import rune) — 2 false-failures; validator fix is issue #139, not here	canary tolerates exactly those 2 messages (prints ⚠ known false-failure, #139, does not count them); any other TUI error still fails the canary

How to add a rule

1. Prefer a built-in: henxels catalogue lists every statement (built-ins and this repo's custom ones).
2. Add a henxel to henxels.yaml. Custom statements live in henxels_checks.py (auto-loaded; a .henxels/ folder of check modules also works). Custom statements REQUIRE an in: scope — without one they never fire.
3. Run henxels check --all --plain locally; fix findings cheaply or add an explicit except: and a row to the debt table above.
4. henxels sync to refresh AGENTS.md and commit both together.
5. The contract must be green at birth: never merge a rule that fails on master.

Why no git hooks

Subagents work in throwaway worktrees (/mnt/workdrive/rune and siblings) and commit there; a pre-commit hook would either miss those commits or block the agent mid-flight. Enforcement is CI-only: the lint job runs henxels check --all --plain on every push/PR, so the gate is the merge, not the commit.