Capafy logo Capafy
Aan de slag
Agent Report Gate — Validate Agent Report YAML

Agent Report Gate — Validate Agent Report YAML

by: Shogun Labs
Check the YAML report a worker agent writes before a reviewer, dashboard, or scheduler trusts it. 13 checks with stable reason codes: parse errors, missing or placeholder fields, invalid status, completed_at without timezone / in the future / before assignment, 'did' longer than 3 lines, partial reports without target, actual and reason, free text outside block scalars, task_id mismatch. Human or JSON output, configurable contract, 14 tests. Read-only, local only.
#Techniek
Beoordeling
Meer beoordelingen nodig
Verkocht
0
Gebruikswijze
Downloaden

What you get

  • A gate that blocks broken, vague, or mis-timed agent reports before anyone trusts them
  • 13 checks with stable reason codes, human or JSON output, and clear exit codes
  • An instruction file for Claude Code plus good/bad example reports and 14 tests

What it does

In multi-agent setups, a worker writes report.yaml, and a reviewer, dashboard, or scheduler reads it. When the report is wrong, everything downstream is wrong too. The gate catches the common failures:

code what it catches
yaml_parse_error / not_a_mapping the file does not parse (often a colon or bracket in pasted output)
missing:<field> / placeholder:<field> required fields missing, or holding TBD, n/a, -, todo
invalid_status status outside the allowed list
completed_at_invalid not ISO-8601 with a timezone
completed_at_future the agent wrote an estimated finish time (beyond a 120 s skew)
completed_at_before_assigned finished before it was assigned
did_line_count did is not 1-3 non-empty lines
did_not_text did is a list or number
partial_missing:<field> a partial report without target, actual, and reason
shortfall_reason_not_text the "reason" is just a number
partial_but_target_met (warn) marked partial although actual >= target
bare_free_text:<field> (warn) free text not in a block scalar, so the next paste can break the file
binding_mismatch:<field> task_id / worker_id differ from what was assigned (--expect)

Inputs and outputs

Input: one report YAML file, an optional contract file, optional --expect key=value and --assigned-at.

Output: one line per finding (or JSON with --json) and an exit code.

exit meaning
0 pass (warnings allowed unless --strict)
1 fail
2 usage error (missing file, bad contract) 
python3 scripts/report_gate.py examples/report_good.yaml
python3 scripts/report_gate.py examples/report_bad.yaml --strict
python3 scripts/report_gate.py report.yaml --expect task_id=task_docs_refresh --json

From Python:

from report_gate import check_report, load_contract
findings = check_report(open("report.yaml").read(), load_contract(None), expect={"task_id": "t1"})

Contract

Every rule has a default. Override any of them in a YAML file (unknown keys are rejected so typos cannot silently disable a rule): required, statuses, did_max_lines, placeholders, partial_requires, partial_section, free_text_keys, future_skew_seconds.

Package contents

file purpose
SKILL.md instructions for Claude Code (or any coding agent)
scripts/report_gate.py the checker (CLI + importable functions)
examples/report_good.yaml a partial report that passes cleanly
examples/report_bad.yaml a report that triggers 4 errors and 3 warnings
examples/contract.yaml sample contract override
tests/test_report_gate.py 14 tests
LICENSE license terms

Review and safety disclosure

  • Read-only: the checker never modifies the report or any other file.
  • No network calls, credentials, background services, or installers.
  • It checks the shape and timing of a report, not whether the work described is true. Pair it with a review of the actual output.

View more