Governance Report Reference

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

This is not protocol v7. It is a derived reporting surface built on top of verified export artifacts. For the live-repo command that builds this report directly from the current governed project or coordinator workspace, use Governance Audit Reference. For the artifact contract itself, see Export Schema Reference. For the constitutional boundary, see Protocol Reference v7.

CLI Surface

agentxchain report [--input <path>|-] [--format text|json|markdown|html]

Flag	Default	Meaning
--input <path>	-	Read an export artifact from a file, or - for stdin
--format <format>	text	Output text, json, markdown, or html

The html format produces a self-contained, portable HTML file with inline CSS. It supports dark mode, print styles, and renders all governance surfaces (turns, decisions, gates, costs, delegations, repo decisions). For coordinator exports, HTML follows the same repo-detail contract as the other human-readable formats: successful child repos render available drill-down sections, while failed child repos keep only their repo row plus error. Ideal for sharing with compliance stakeholders or archiving.

report verifies the export artifact first. It does not read live repo state directly. If the artifact fails verification, the command fails closed and returns verifier-backed errors instead of a success summary.

Exit Codes

Exit code	Meaning
0	Export artifact verified and report rendered successfully
1	Export artifact was readable JSON but failed self-verification
2	Command or input error

Success JSON Shape

When --format json succeeds, the command emits:

Field	Type	Meaning
report_version	string	Current report contract version. Today: 0.1
overall	"pass"	Always "pass" on successful report generation
generated_at	string	ISO timestamp for report generation
input	string	Resolved file path or "stdin"
export_kind	string	agentxchain_run_export or agentxchain_coordinator_export
verification	object	Embedded verify export report proving the artifact passed validation
subject	object	Human-oriented derived summary for the verified artifact

verification

The embedded verification object mirrors the successful verify export --format json shape:

• overall
• schema_version
• export_kind
• file_count
• repo_count
• errors

On successful reports, verification.overall is always pass and errors is empty.

subject.kind = governed_run

Run-export reports carry:

Key	Meaning
subject.project	Project identity, optional goal, template, protocol mode, and governed config schema version
subject.run.run_id	Current run id or null
subject.run.status	Current run status
subject.run.phase	Current run phase
subject.run.blocked_on	Exported blocked-state string or null
subject.run.blocked_reason	Exported structured blocked-reason object or null
subject.run.active_turn_count	Count of active turns
subject.run.retained_turn_count	Count of retained turns
subject.run.active_turn_ids	Active turn ids
subject.run.retained_turn_ids	Retained turn ids
subject.run.active_roles	Sorted active role ids
subject.run.budget_status	spent_usd / remaining_usd when present
subject.run.cost_summary	Aggregated per-run cost breakdown (see below) or null when no turns exist
subject.run.dashboard_session	Export-time dashboard-daemon snapshot summary, or null for older artifacts that predate the field
subject.run.recent_event_summary	Recent-event digest derived from exported .agentxchain/events.jsonl
subject.run.delegation_summary	Delegation-chain audit summary derived from the verified export summary or accepted history fallback
subject.run.created_at / completed_at / duration_seconds	Run timing summary when available
subject.run.turns	Accepted-turn timeline derived from .agentxchain/history.jsonl
subject.run.decisions	Decision digest derived from .agentxchain/decision-ledger.jsonl (entries with id field)
subject.run.approval_policy_events	Approval-policy gate actions derived from .agentxchain/decision-ledger.jsonl (entries with type: "approval_policy"). Each entry includes gate_type, action, matched_rule, from_phase/to_phase, reason, gate_id, and timestamp.
subject.run.timeout_events	Timeout events derived from .agentxchain/decision-ledger.jsonl (entries whose type starts with timeout). Each entry includes type, scope, phase, limit_minutes, elapsed_minutes, exceeded_by_minutes, action, and timestamp.
subject.run.hook_summary	Hook execution totals and event breakdown
subject.run.gate_summary	Sorted gate outcomes derived from state.phase_gate_status
subject.run.intake_links	Linked intake intents whose target_run matches the exported run
subject.run.recovery_summary	Blocked-state recovery owner/action/detail when present
subject.run.next_actions	Ordered operator actions derived from blocked-state recovery and runtime-aware gate guidance
subject.run.continuity	Session checkpoint metadata from .agentxchain/session.json when present, or null
subject.run.workflow_kit_artifacts	Workflow-kit artifact status for the current phase, or null when workflow_kit is absent from config
subject.artifacts	Export-derived evidence counts and intake/coordinator presence flags

subject.artifacts includes:

• history_entries
• decision_entries
• hook_audit_entries
• notification_audit_entries
• dispatch_artifact_files
• staging_artifact_files
• intake_present
• coordinator_present

When the governed project config includes project.goal, the derived report preserves it at subject.project.goal. Human-readable text and markdown output also render Goal: <text> in the report header.

Cost Summary

subject.run.cost_summary aggregates per-turn cost data into a run-level breakdown. It is null when no history entries exist. Otherwise it contains:

Key	Type	Description
total_usd	number	Sum of all per-turn cost_usd values
total_input_tokens	number | null	Sum of input tokens across turns, or null if no turns report tokens
total_output_tokens	number | null	Sum of output tokens across turns, or null if no turns report tokens
turn_count	number	Total history entries
costed_turn_count	number	Turns with a finite cost_usd value
by_role	array	Per-role breakdown sorted alphabetically. Each entry: { role, usd, turns, input_tokens, output_tokens }
by_phase	array	Per-phase breakdown sorted alphabetically. Each entry: { phase, usd, turns }

Text, markdown, and html output render a dedicated Cost Summary section with role and phase breakdowns between the budget line and the turn timeline.

Dashboard Session

subject.run.dashboard_session captures the export-time snapshot of the repo-local dashboard daemon.

When present it has this shape:

Key	Type	Description
status	"running" | "pid_only" | "stale" | "not_running"	Snapshot status at export time
pid	number | null	PID when known
url	string | null	Dashboard URL when session metadata exists
started_at	string | null	Session start timestamp when known

Current exports always include this field. Older verified artifacts may surface null here because they predate the snapshot field. When the field is present, text, markdown, and html output render the dashboard snapshot near the top of the report.

Recent Event Summary

subject.run.recent_event_summary is the summary-level lifecycle evidence surface for governed runs. It does not replace agentxchain events; it tells operators whether the run has moved recently and what happened last.

When present it has this shape:

Key	Type	Description
window_minutes	number	Fixed recentness window used by the digest. Today: 15
freshness	"recent" | "quiet" | "unknown" | "no_events"	Whether the latest event is inside the recentness window
recent_count	number	Count of events with valid timestamps inside the recentness window
latest_event	object | null	Most recent parsed event, or null when no events were exported

latest_event includes:

• event_type
• timestamp
• phase
• status
• turn_id
• role_id
• repo_id
• summary

Text, markdown, and html output render this digest near the top of the report as Recent events plus Latest event.

Delegation Summary

subject.run.delegation_summary surfaces accepted delegation chains without forcing operators to parse raw history.jsonl.

It is null when history is unavailable. Otherwise it contains:

Key	Type	Description
total_delegations_issued	number	Total delegations issued across all parent turns
delegation_chains	array	Delegation chains grouped by parent turn

Each chain entry contains:

Key	Type	Description
parent_turn_id	string	Turn that issued the delegations
parent_role	string	Role that delegated
delegations	array	Individual delegation entries
review_turn_id	string | null	Review turn that accepted the child results, or null while pending
outcome	"completed" | "failed" | "mixed" | "pending"	Aggregated chain outcome

Each delegation entry contains:

Key	Type	Description
delegation_id	string	Delegation identifier
to_role	string	Delegated role
charter	string	Delegated task description
status	"completed" | "failed" | "pending"	Child outcome
child_turn_id	string | null	Child turn id, or null when not yet executed

When delegation chains exist, text, markdown, and html output render a dedicated Delegation Summary section before the turn timeline.

Recovery Summary

subject.run.recovery_summary now carries runtime-aware guidance when the last gate failure identifies a missing required file whose owner/runtime contract explains the real blocker.

When present, recovery_summary.runtime_guidance[] entries include:

Key	Type	Description
code	string	One of invalid_binding, review_only_remote_dead_end, proposal_apply_required, or tool_defined_proof_not_strong_enough
phase	string	Phase whose gate exposed the blocker
gate_id	string	Gate id associated with the blocker
role_id	string	Artifact owner role
artifact_path	string	Missing required artifact path
command	string	Operator action derived from the runtime contract
reason	string	Human-readable explanation of why that action is required

Next Actions

subject.run.next_actions is the ordered operator-action surface for governed run reports.

• Runtime-aware gate fixes come first (proposal apply, config repair, or MCP contract inspection).
• Generic blocked-state recovery (resume, step --resume, approval commands) comes after the runtime blocker is resolved.

subject.kind = coordinator_workspace

Coordinator-export reports carry:

Key	Meaning
subject.coordinator	Coordinator identity, schema version, repo count, workstream count
subject.run.super_run_id	Current coordinator run id or null
subject.run.status	Current coordinator status
subject.run.phase	Current coordinator phase
subject.run.blocked_reason	Coordinator blocked reason from state when present
subject.run.pending_gate	Current coordinator pending gate from state when present
subject.run.run_id_mismatches	Verified child repo run-id mismatches against coordinator state
subject.run.repo_status_drifts	Status disagreements between coordinator state and authority-first child repo status entries
subject.run.terminal_observability_note	Non-actionable terminal-drift note shown when the coordinator is already completed but child repo drift remains visible for audit
subject.run.recent_coordinator_events	Recent-event digest derived from coordinator lifecycle history
subject.run.recent_child_repo_events	Recent-event digest derived from aggregated child repo events
subject.run.next_actions	Ordered operator commands derived from verified coordinator state
subject.run.created_at / completed_at / duration_seconds	Coordinator timing summary derived from lifecycle history when available, with state fallback
subject.run.barrier_count	Number of coordinator barriers
subject.run.repo_status_counts	Status histogram derived from the same authority-first child repo status contract used by dashboard and multi-repo CLI surfaces
subject.run.repo_ok_count	Number of child repo exports that verified cleanly
subject.run.repo_error_count	Number of child repo exports that failed
subject.coordinator_timeline	Coordinator event narrative derived from .agentxchain/multirepo/history.jsonl
subject.barrier_summary	Current barrier snapshot derived from .agentxchain/multirepo/barriers.json. For named_decisions and interface_alignment barriers, each entry includes required_decision_ids_by_repo (the declared decision IDs per repo) and satisfied_decision_ids_by_repo (which decision IDs each repo has satisfied)
subject.barrier_ledger_timeline	Barrier transition history derived from .agentxchain/multirepo/barrier-ledger.jsonl
subject.decision_digest	Coordinator-level decision digest derived from .agentxchain/multirepo/decision-ledger.jsonl, populated by coordinator init, dispatch, gate, and recovery decisions
subject.approval_policy_events	Coordinator-level approval-policy gate actions derived from .agentxchain/multirepo/decision-ledger.jsonl
subject.timeout_events	Coordinator-level timeout events derived from .agentxchain/multirepo/decision-ledger.jsonl
subject.recovery_report	Recovery report summary extracted from .agentxchain/multirepo/RECOVERY_REPORT.md when present, or null when absent
subject.repos	Per-repo summary rows for paste-friendly reporting
subject.artifacts	Coordinator history and decision counts

subject.run.repo_status_counts and subject.run.repo_status_drifts do not reuse summary.repo_run_statuses as primary repo truth. That export field stays raw coordinator snapshot metadata only. When a nested child export or repo-local state is readable, report uses that child authority first for repo-status counts and drift. Coordinator linkage labels such as linked or initialized remain metadata only.

Partial coordinator exports stay reportable. subject.run.repo_ok_count and subject.run.repo_error_count preserve export health even when one or more child repos have ok: false, and the coordinator-level timeline, barrier, decision, and next-action surfaces remain readable from the verified coordinator artifact. What does not happen is fake child drill-down: a failed repo keeps its error row, but report omits turn timelines, decision lists, gate outcomes, hook activity, and recovery details because there is no embedded child export to summarize.

That repo-detail boundary applies across every human-readable report format, not just HTML. text, markdown, and html all keep the failed repo row visible without fabricated child sections, and all three still render the successful child repo drill-down sections that actually exist in the embedded export, including Approval Policy, Governance Events, Timeout Events, Hook Activity, Recovery, and Continuity.

Each subject.repos[] row includes:

• repo_id
• path
• ok
• status
• run_id
• phase
• project_id
• project_name
• error
• continuity

When ok is true, child-repo drill-down fields are also present:

• turns — turn timeline extracted from the child repo's embedded export (same shape as governed-run turns)
• decisions — decision digest from the child repo
• approval_policy_events — approval-policy gate actions from the child repo
• timeout_events — timeout events from the child repo
• hook_summary — hook execution summary (total, blocked, events) or null
• gate_summary — phase gate outcomes or []
• recovery_summary — blocked recovery context or null
• continuity — child session checkpoint metadata or null
• blocked_on — current blocked-on value or null

These fields are omitted for failed repos (ok: false). Text, markdown, and html formats render per-repo Turn Timeline, Decisions, Gate Outcomes, Hook Activity, and Recovery sections when the data is non-empty. For failed repos, human-readable formats keep the repo row and error visible while omitting those drill-down sections entirely. That is intentional degradation, not missing rendering. When a child repo export contains .agentxchain/session.json, text, markdown, and html also render per-repo Continuity sections with stale-checkpoint warnings when the checkpoint run id no longer matches the child export run id.

When subject.run.status = "completed" and either subject.run.run_id_mismatches or subject.run.repo_status_drifts is non-empty, the report keeps that child repo drift visible for audit but does not reopen recovery guidance. In that case subject.run.terminal_observability_note is populated, text and markdown render Terminal drift note: ..., HTML renders a Terminal drift note metadata row, and the report still omits Next Actions.

subject.run.repo_decisions

When .agentxchain/repo-decisions.jsonl exists in the export, subject.run.repo_decisions mirrors the verified export summary and stays non-null even when every repo decision has already been overridden.

Field	Type	Meaning
total	number	Total repo decisions recorded in .agentxchain/repo-decisions.jsonl
active_count	number	Currently binding repo decisions
overridden_count	number	Historical repo decisions that have been superseded
active	array	Active decision rows including id, category, statement, role, run_id, overrides, authority_level, and authority_source
overridden	array	Overridden decision rows including id, statement, overridden_by, overrides, role, authority_level, and authority_source
operator_summary	object	Compact first-glance significance block: active_categories, highest_active_authority_level, highest_active_authority_role, highest_active_authority_source, superseding_active_count, and overridden_with_successor_count

Text, markdown, and html outputs render a Repo Decisions section whenever this object is non-null. That is deliberate: overridden-only repo-decision history is still operator-relevant and must not disappear from the report.

subject.recovery_report

When .agentxchain/multirepo/RECOVERY_REPORT.md is present in the coordinator export, the report extracts its sections:

Field	Type	Meaning
present	true	Always true when the object is non-null
trigger	string | null	Content of ## Trigger section, or null if absent/placeholder
impact	string | null	Content of ## Impact section, or null if absent/placeholder
mitigation	string | null	Content of ## Mitigation section, or null if absent/placeholder
owner	string | null	Content of ## Owner section (optional), or null
exit_condition	string | null	Content of ## Exit Condition section (optional), or null

When the recovery report file is absent, subject.recovery_report is null and no Recovery Report section appears in text or markdown output.

Human-Readable Formats

text

Plain-text output is intended for terminal inspection. It includes:

• verification status
• project/workspace identity
• run/coordinator status and phase
• started/completed/duration timing when available
• turn or repo counts
• artifact evidence counts
• blocked-state or barrier information when present
• pending gate and next actions when coordinator state makes them deterministic
• turn timeline, coordinator timeline, decision digest, coordinator decisions, hook activity, gate outcomes, barrier summary, barrier transitions, and intake linkage when those surfaces exist
• repo-decision counts plus compact category/authority/lineage summary when repo-level cross-run decisions exist
• approval-policy and timeout event sections when those surfaces exist

markdown

markdown exists for copy-paste into pull requests, release notes, tickets, or audit records without manual reformatting. It uses the same verified report data as json, and now adds sectioned operator context when available:

• ## Turn Timeline
• ## Delegation Summary
• ## Repo Decisions
• ## Coordinator Timeline
• ## Decisions
• ## Hook Activity
• ## Gate Outcomes
• ## Next Actions
• ## Barrier Summary — includes a ### Decision Requirements subsection for named_decisions / interface_alignment barriers showing per-repo required and satisfied decision IDs
• ## Barrier Transitions
• ## Coordinator Decisions
• ## Approval Policy
• ## Timeout Events
• ## Recovery Report
• ## Intake Linkage
• ## Recovery
• ## Continuity
• ## Workflow Artifacts

Coordinator markdown output also uses #### Continuity inside each repo detail block when child checkpoints exist.

subject.run.workflow_kit_artifacts

When workflow_kit is present in the project config and the current phase declares artifacts, the report includes a workflow_kit_artifacts array:

Field	Type	Meaning
path	string	Artifact file path from config
required	boolean	Whether the artifact is required for phase gates
semantics	string | null	Semantic validator ID or null
owned_by	string | null	Resolved owner role
owner_resolution	"explicit" | "entry_role"	How ownership was resolved
exists	boolean	Whether the file is present in the export artifact

Artifacts are sorted by path. When workflow_kit is absent, this field is null. When the current phase has zero artifacts, it is [] and the section is omitted from text/markdown output.

Failure Shapes

Verification failure (exit 1)

When the input is valid JSON but the artifact fails self-verification:

Field	Type	Meaning
overall	"fail"	Report generation refused because the artifact is invalid
input	string	Resolved file path or "stdin"
message	string	Human-readable refusal message
verification	object	Embedded verifier report with errors explaining the mismatch

Command or input error (exit 2)

When the file cannot be read or the JSON cannot be parsed:

Field	Type	Meaning
overall	"error"	Command-level failure
input	string	Resolved file path or "stdin"
message	string	Human-readable error description

If you need artifact integrity proof, use verify export. If you need the raw artifact schema, use Export Schema Reference.