Limits and Next Steps

Limits and Next Steps

Limits

The central limit is that these are checks and records, not a sandbox. Nothing here stops a process that ignores them, because the package runs only when a host calls it, and the host remains free to keep going after a CHECKPOINT_AND_STOP. That boundary follows from the design rather than from a missing feature; however, it means a reader should treat the package as the instrument panel of an unattended run and not as its brakes.

The repository also holds no evidence from a field run. Its evidence comes from tests and an offline tour, so it cannot yet say how many tokens or how much money it saves, how often the watchdog fires on good work, or whether the 0.70 and 0.88 budget lines and the 120-second default are the right numbers. They are design values, and no measured run stands behind them.

Area	Limit
Token figures	Estimates supplied by the caller. This package does not count tokens
Run loop	None. The host must call the budget and watchdog checks and act on the answers
Proof of progress	The host defines it. The watchdog trusts the timestamps it receives
Rule gate	evaluate-rules exits 0 on an empty context, even while it reports four unknowns
Fallback	choose_orchestrator() raises RuntimeError with no checkpoint; it does not return a result
Repeat hook	check-loop-hook warns and always allows the call
ContextLease	Compares exact path strings. Its read and byte limits are declared but not enforced
Capability config	handler: paths are imported and called, so treat that file as code
Concurrency	No file locking. Loop counters and checkpoints survive a crash mid-write, but concurrent writers can lose an update
Pool	Speaks Ollama only. Fields such as approved_task_types are descriptive, and model_allowed is the rule that is enforced
Platforms	Tested on Windows with Python 3.12. Not tested on Linux or macOS

Declarations with no code behind them

The README states that a declaration no code reads is an instruction, not a mechanism, and that standard applies to this repository as well. governance/models.py declares the statuses ALLOW_WITH_LIMITS and REQUIRE_HUMAN, the CircuitState enum, and the RunState and ProgressProof dataclasses. admit() returns neither status. A search of src and tests finds no use of REQUIRE_HUMAN, CircuitState, RunState, or ProgressProof, and ALLOW_WITH_LIMITS appears only in the set of admitted statuses in governance/cli.py and in one docstring. They should either gain behavior or go, because a reader of the enum would otherwise assume a human escalation path that does not exist.

Next steps

These are ordered by how much each one closes a gap between what the package says and what it does.

1. Make an empty rule context fail the gate. A decision with unknowns and no match should offer a non-zero exit, because missing data currently passes a shell gate while the text beside it says otherwise.
2. Resolve the unused declarations. Implement REQUIRE_HUMAN as a real admission outcome, or remove it along with the other unused names.
3. Add a thin example host. A small loop that calls admission, budget, watchdog, and checkpoint against a stubbed agent would turn the tour into one continuous run with a ledger to inspect.
4. Measure a real run. Recording tokens, stops, and false alarms from real agent sessions would test the default thresholds, which are currently reasoned rather than measured.
5. Improve the fingerprint. Adding a hash of the working tree to task_state would separate a stuck loop from a legitimate re-run, which is the condition for a blocking hook.
6. Run the suite on Linux and macOS. The path handling and the atomic replace have only been exercised on Windows.
7. Enforce ContextLease limits. The read and byte limits should either count something or leave the dataclass.

No dates are attached to these. The order matters more than the schedule, because the first two correct statements the package already makes about itself.