Governance Audit Reference

This page documents the stable operator-facing contract for agentxchain audit.

Use audit when you want the governance report for the live governed project or coordinator workspace you are standing in right now. Use agentxchain report when you already have an export artifact and need the verification-first derived summary from that artifact. Use Export Schema Reference when you need the raw transport contract instead of the derived audit/report surface.

CLI Surface

agentxchain audit [--format text|json|markdown|html]

Flag	Default	Meaning
--format <format>	text	Output text, json, markdown, or html

Boundary

• audit reads live repo state from the current directory
• it supports governed projects (agentxchain.json) and coordinator workspaces (agentxchain-multi.json)
• governed project detection takes priority when both are present
• it does not accept --input; offline artifact inspection belongs to report

Internally, audit builds the same export artifact that agentxchain export would build, then runs the same verifier-backed report builder that powers agentxchain report. That means the rendered output uses the same report contract as agentxchain report; the difference is the source boundary, not the report shape.

Exit Codes

Exit code	Meaning
0	Audit report rendered successfully
1	Built export artifact failed self-verification
2	Command or input error

Output Contract

audit reuses the existing governance report output formats:

• text for local terminal inspection
• markdown for paste-ready audit records
• json for machine-readable derived reporting
• html for portable, self-contained audit records with inline styles

For governed projects the json payload keeps subject.kind = "governed_run". For coordinator workspaces it keeps subject.kind = "coordinator_workspace". The input field carries the resolved live project/workspace path instead of an export artifact filename.

Because audit reuses the same report builder as report, blocked governed runs keep the same additive operator fields, and blocked coordinator workspaces keep the same ordered recovery surface for pending_gate, repo_run_id_mismatch, and multi resync drift cases:

• subject.run.next_actions — ordered operator commands derived from runtime guidance plus blocked-state recovery
• subject.run.recovery_summary.runtime_guidance[] — runtime-aware blocker classification when AgentXchain can prove a config/runtime ownership cause

For coordinator workspaces, that shared report contract also keeps the repo-status truth boundary explicit: summary.repo_run_statuses remains raw coordinator snapshot metadata only, while subject.run.repo_status_counts and subject.run.repo_status_drifts use authority-first child repo status when a nested child export or repo-local state is readable. Coordinator linkage labels like linked / initialized remain metadata only and must not become primary repo-status truth.

That same boundary applies when the freshly built coordinator export is partial. If a child repo export fails and the built artifact records repos.<repoId>.ok === false, audit still renders coordinator-level evidence plus subject.run.repo_ok_count / subject.run.repo_error_count export-health totals, but it must not invent child drill-down sections for the failed repo. The repo row and error remain visible; turn timelines, decisions, gate outcomes, hook activity, and recovery details stay absent because no nested child export exists to summarize.

html follows the same repo-detail contract as the other human-readable audit formats. Successful child repos keep the available per-repo drill-down sections when the nested child export includes them, including Approval Policy, Governance Events, Timeout Events, Hook Activity, Recovery, and Continuity. Failed child repos stay row-only plus error even in HTML; the renderer must not fabricate <h4> child sections for a repo whose export build failed.

That is not an HTML-only promise. text, markdown, and html all keep the failed repo row visible without fabricated child sections, and all three keep the successful child repo drill-down sections that the nested child export actually contains, including Approval Policy, Governance Events, Timeout Events, Hook Activity, Recovery, and Continuity.

Completed coordinator workspaces follow the same terminal contract as report: if child repo drift remains visible after the coordinator is already completed, audit keeps subject.run.run_id_mismatches and subject.run.repo_status_drifts visible, populates subject.run.terminal_observability_note, and omits subject.run.next_actions. Text and markdown output render Terminal drift note: ..., while HTML output renders the same terminal drift note as visible report metadata instead of implying recovery work still exists.

See Governance Report Reference for the full subject contract and human-readable section semantics.

Examples

# Fast local audit for the current governed repo
agentxchain audit

# Paste-ready markdown for a PR or release note
agentxchain audit --format markdown

# Structured JSON for automation
agentxchain audit --format json

# Portable HTML for a stakeholder or compliance review
agentxchain audit --format html > governance-audit.html

# Artifact-first workflow when you need a portable bundle
agentxchain export --format json > governance-export.json
agentxchain report --input governance-export.json --format markdown