Remove the decorator
The function can still return bounded prices, but its required checks no longer produce evidence. Melampus reports the missing checks.
Claude stopped.
The contract held.
A pricing refactor breaks two approved rules. Melampus blocks the next action, Claude repairs the code, and fresh evidence lets the session continue.
Follow the recorded session ↓01 / INTENT
A price must stay within its approved bounds.
The owner reviews intent.py and the five scenario inputs. The agent edits pricing.py. A dedicated Melampus process watches that code and executes the scenario again when it changes.
IntegerOutput uses whole cents
≥ 0No negative price
≤ 10,000Approved ceiling, in cents
| Input · cents | Original | Seeded defect | Claude’s repair |
|---|---|---|---|
| -1 | 0 | -1 · fails | 0 |
| 0 | 0 | 0 | 0 |
| 1,200 | 1,200 | 1,200 | 1,200 |
| 10,000 | 10,000 | 10,000 | 10,000 |
| 12,000 | 10,000 | 12,000 · fails | 10,000 |
Outputs come from a post-run replay of saved source snapshots on these public fixtures. The SDK evidence records check results, not raw argument or result values.
02 / RECORDING
Watch the next action change.
- T+1.6shealthy
Baseline accepted
Five inputs exercise three approved rules: 15 evaluations pass.
- T+2.4sdrift
The harness removes both clamps
The supervisor detects two failed evaluations before any gate query.
- T+9.1sblocked
Claude’s shell action is denied
The real hook sends nonnegative and capped failures back to Claude.
- T+17.0shealthy
Claude repairs pricing.py
One Edit restores the bounds. Fresh execution passes all 15 evaluations.
- T+29.5shealthy
Completion is accepted
The Stop hook accepts the result. Five reviewed files remain unchanged.
THE FAILURE REACHED THE AGENT
“The hook blocked it as expected; not retrying.”
Claude’s recorded response after its harmless printf request was denied. The request was deliberately prompted to make the gate observable.
03 / REPAIROne implementation edit.
One implementation edit.
The same reviewed checks.
Actual pricing.py before and after Claude’s Edit. The instrumentation remains in place so the fresh implementation is checked again.
Loading source comparison. If offline, download drift.py and after.py from Evidence below.
Green means the checked claims passed.Claude also introduced
int(cents). These five integer inputs do not establish whether truncating floats or rejecting other types is acceptable. A passing report still needs a good contract and a review of semantic choices.Inspect the approved contract · intent.py
Source available in Evidence below.
Inspect the executed scenario · exercise.py
Source available in Evidence below.
04 / FAIL CLOSED
Missing evidence also stops progression.
After the live repair, the harness ran two additional controls. These were scripted checks, not actions taken by Claude.
Stop the supervisor
The gate reports that the local supervisor is unavailable. A previous healthy result does not authorize a new success claim.
05 / UNIT TESTSThe oracle is familiar.
The oracle is familiar.
The control point is different.
The runnable example makes two temporary edits and executes real pytest and Melampus processes. It distinguishes a test-coverage gap from the session behavior Melampus adds.
| Temporary edit | Smoke unit | Full boundary tests | Melampus | Next agent action |
|---|---|---|---|---|
| Return input unchanged | Pass | Fail | Drift | Blocked |
| Remove instrumentation | Pass | Pass | Incomplete | Blocked |
Good tests catch the same bad value
When the complete boundary suite runs, it catches the unclamped return. Melampus has no secret source of intent; both approaches depend on reviewed executable claims and representative inputs.
Evidence must stay attached and current
The supervisor reruns after watched edits, treats missing instrumentation as incomplete, and gives the synchronous agent hook a decision for the current revision.
Could hooks around pytest achieve similar control?Yes. A controller that runs the right tests after every relevant edit, detects missing or stale execution, preserves repair access, and blocks the agent on failure can provide similar protection. Melampus packages that loop around contracts attached to generated units; it complements the broader regression suite.
06 / TRY IT
Run the same example yourself.
Python 3.11+ and uv on macOS or Linux. The recorder creates a disposable copy; it does not change the repository’s example.
Get the demo implementation
This recording uses the first-release branch in the v0.1.0 release. Publication on PyPI is not required.
git clone https://github.com/melampus-org/melampus-python.git cd melampus-python uv sync --locked --all-extras
Try the protocol without a model request
This version seeds and repairs the defect with a script. It exercises the real supervisor and gate, but is not an AI repair demonstration.
uv run --locked python scripts/record_agent_demo.py --output demo-recordings/protocol
Compare unit tests and the agent gate
This makes two temporary edits, runs the smoke and boundary tests, queries a live Melampus session, then restores the source.
uv run --locked python examples/agent-session/compare_with_unit_tests.py
Record a real Claude Code repair
Install and sign in to Claude Code first. This makes a request with your own account and configured model. Use a new output directory for each run.
uv run --locked python scripts/record_agent_demo.py --live-claude --output demo-recordings/live
Review
run.json, the sanitized agent transcript, hook decisions, and source snapshots. Model behavior and timing can differ from this recording.Keep Melampus beside your own coding session
Open two terminals at the repository root. Review the sample’s contract, scenario, configuration and Claude hooks before enabling them.
TERMINAL A · SUPERVISORsource .venv/bin/activate cd examples/agent-session melampus session
TERMINAL B · YOUR AGENTsource .venv/bin/activate cd examples/agent-session melampus gate claude
Ask Claude to modify
pricing:pricewhile preservingPRICE.instrumentand the reviewed intent. If intent needs to change, have the owner review it and restart the session. See the agent-session guide for configuration and adapters.
07 / VALUE
Keep human review focused on intent.
The loop handles repeated feedback
- Re-executes the configured scenario when watched code changes.
- Returns specific failed claims to the coding agent.
- Blocks unrelated progression while allowing scoped repair.
- Keeps reviewed assertions separate from implementation edits.
The team still owns the specification
- Choose valuable predicates and representative scenarios.
- Check coverage of the paths that matter.
- Review meaningful behavior changes, including repair choices.
- Keep unit tests, CI, security checks and code review.
Tests with the same inputs and assertions can catch this same bug. Melampus adds the continuously running session loop, evidence freshness and agent action gating. It does not infer all business intent from prose or guarantee that generated code is correct.
08 / EVIDENCE
Inspect the run. Reproduce the result.
These downloads are embedded in this HTML. Sharing this file shares the recording, not the author’s AI session. Readers run their own copy with their own Claude account.
run.json↓hooks.jsonl↓agent-transcript.jsonl↓supervisor.log↓before.py↓drift.py↓after.py↓intent.py↓exercise.py↓fixture-results.json↓
Recorded 2026-09-29 with Melampus 0.1.0 and 2.1.284 (Claude Code). Temporary paths were replaced with <demo-project>. Published messages omit authentication metadata and hidden reasoning. Fonts and the syntax viewer use public CDNs; narrative, tables and evidence downloads remain available offline.