feat(cli): complete machine-readable output and exit-code contract (#171, #160, #150)

[dgenio]

Summary

Completes AgentFence's machine-readable output & exit-code contract across the CLI. check, explain, and audit summarize already supported --output json; this adds the same convention to the remaining subcommands so every gate a CI pipeline runs can be consumed structurally without parsing prose.

What changed (file by file):

• cmd/agentfence/main.go
  • Add JSON output and exit-code contract to policy test #171 — policy test --output text|json. JSON emits a per-case report ({id, tool, expect, got, pass, reason}) plus {total, passed, failed}. Text path (PASS/FAIL, --verbose) unchanged. Non-zero exit on any failure preserved in both modes.
  • Add an audit verify --json machine-readable verification result #160 — audit verify --output text|json. JSON emits one combined {chain, signatures?, anchor?} object with stable status enums (ok/no_chain/partial/corrupt/failed, etc.). The three report functions were refactored into compute*Result + printText helpers; the text output is byte-for-byte unchanged (existing strings.Contains tests stay green). The JSON object is emitted even on failure, and exit codes are identical to text mode.
  • Add an audit-log statistics exit/summary for CI gate transparency #150 — check --summary <file|->. Writes a compact JSON gate summary (total, parse_errors, by_decision, top_denied_tools, top_denied_reasons, fail_on, matched, failed, dry_run) independent of --output, before the --fail-on exit so the artifact exists even when the gate fails. - sends it to stderr to keep --output stdout clean.
  • Usage/help strings updated for the new flags.
• cmd/agentfence/main_test.go — 7 new tests: JSON shapes, exit codes, stdout-purity (no prose leak), unknown --output rejection, and gate-summary file + stderr destinations.
• README.md — CI section documents --summary and the policy test/audit verify JSON modes.
• CHANGELOG.md — [Unreleased] entry.

Why

These three issues are one surface — extending the existing --output json convention to the subcommands that lacked it, plus a CI gate summary — all in cmd/agentfence/main.go. They share a module, a category, and a test pass, so they ship cleaner together than separately (this was the recommended combined group from the triage).

Scope note (Mode B): the repo norm is one-concern-per-PR; bundling these three was explicitly requested. They are tightly cohesive (same file, same convention, no cross-dependencies).

How verified

• make ci (fmt-check + vet + test-race + coverage) — green; total coverage 81.1%.
• go test ./cmd/agentfence/ -run 'PolicyTest|AuditVerify|CheckGateSummary|CheckOutput' -v — all pass.
• Manual smoke against bundled examples:
  • policy test --output json → {total:21, passed:21, failed:0, cases:[…]}, exit 0.
  • audit verify --output json → {"chain":{"status":"no_chain","events":6,…}}.
  • check … --fail-on deny --summary - → JSON summary on stderr (matched:3, failed:true), exit 1.

Related issue

Fixes #171
Fixes #160
Fixes #150

Checklist

• Tests added or updated
• Documentation updated if needed
• CI passes (make ci locally; green)
• Issue number included

Tradeoffs / risks

• The audit verify refactor is the largest change; mitigated by keeping the text output byte-for-byte identical and covered by existing tests.
• New JSON shapes are public contracts going forward; field names were chosen to match the existing audit summarize style.

🤖 Generated with Claude Code

https://claude.ai/code/session_01E2YUNXPiwtyXJ6Javs4WxU

---

Generated by Claude Code

[Copilot]

Pull request overview

Completes AgentFence CLI’s machine-readable output and exit-code contract by extending --output json support to additional subcommands and adding a separate check --summary JSON artifact for CI gate reporting (without parsing human-oriented text).

Changes:

• Add check --summary <file|-> to emit a compact JSON gate summary independent of --output.
• Add policy test --output text|json with per-case results + totals, preserving failure exit semantics.
• Add audit verify --output text|json with a combined {chain, signatures?, anchor?} JSON report while keeping text output and exit-code behavior consistent.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
cmd/agentfence/main.go	Implements check --summary, policy test --output json, and audit verify --output json (plus helper result structs/functions).
cmd/agentfence/main_test.go	Adds tests covering JSON shapes, exit semantics, stdout purity, and summary destinations.
README.md	Documents check --summary and the new JSON modes for policy test / audit verify.
CHANGELOG.md	Adds [Unreleased] entries describing the new CLI contracts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.