enhancement: make Markdown report suitable for direct use as CI Step Summary

[marcusburghardt]

Summary

CI workflows that consume complyctl scan --format pretty currently duplicate the report logic with custom Python scripts to produce a GitHub Actions Step Summary (see reusable_compliance.yml). This creates two different representations of the same compliance data -- one in the Markdown report artifact, another in the Step Summary -- which diverge over time and double the maintenance surface.

The goal is to make the complyctl Markdown report the single source of truth so CI consumers can use it directly as the Step Summary:

- name: Publish report to GitHub Step Summary
  run: |
    for f in report-*.md; do
      [ -f "$f" ] || continue
      cat "$f" >> "$GITHUB_STEP_SUMMARY"
    done

This would replace ~55 lines of custom Python and eliminate the pip install pyyaml dependency in the workflow.

Current behavior (v1.0.0-beta.0 -- used by org-infra)

The report generated by --format pretty has these issues when used as a Step Summary:

1. No at-a-glance summary: Goes straight from the heading into per-control sections. No pass/fail counts or overall verdict visible without scrolling.
2. Raw evaluation log YAML: The full Gemara evaluation log is embedded as an unscrollable fenced code block (~130 lines), dominating the report. This data is also uploaded as a separate artifact, so it clutters the human-readable view without adding value.
3. Verbose when all controls pass: Each control repeats the same structure with "Passed" and "X of X repositories passed" with no visual differentiation.

Current state on main

Recent changes in internal/output/markdown.go already address some of these:

Improvement	Status on main
Summary metadata table (Policy, Target, Tool, Result, Date)	Implemented in writeSummary()
Pass/fail counts table	Implemented in writeSummary() via computeSummaryCounts()
Controls table (## Controls)	Implemented in writeControlsTable()
Findings section with collapsible evidence	Implemented in writeFindings()
Evaluation log in <details> block	Implemented in writeEvaluationLog()

Remaining improvements

1. Verify Step Summary rendering

Validate that the current main report renders correctly as a GitHub Actions Step Summary. Specifically:

• <details>/<summary> blocks render as collapsible sections
• Markdown tables render properly
• Report length is reasonable for the Summary tab (not truncated by GitHub's limits)

2. Add status indicators for scanability

The current CI Step Summary uses emoji indicators for quick visual scanning. Consider adding result indicators to the Controls table or the summary section so the report is scannable at a glance without needing the custom Python layer. The existing writeFindings() groups by severity, but a concise pass/fail indicator per control in the table would improve readability.

Code references

File	Function	Role
internal/output/markdown.go	Write()	Top-level report orchestrator
internal/output/markdown.go	writeSummary()	Metadata + counts table
internal/output/markdown.go	writeControlsTable()	Per-control results table
internal/output/markdown.go	writeFindings()	Non-passing results with evidence
internal/output/markdown.go	writeEvaluationLog()	Collapsible YAML embedding
cmd/complyctl/cli/scan.go	writePrettyReport()	Entry point for --format pretty

Downstream impact

Once the report is Step-Summary-ready, complytime/org-infra will:

1. Update the complyctl version in reusable_compliance.yml (currently pinned to v1.0.0-beta.0)
2. Replace the custom Python summary generation (~55 lines + pip install pyyaml) with a simple cat report-*.md >> $GITHUB_STEP_SUMMARY
3. Remove the Install YAML parser step

Related

• enhancement: group and reorder complyctl doctor output for readability #692 -- group and reorder complyctl doctor output for readability (similar UX improvement pattern)
• org-infra#reusable_compliance.yml -- downstream consumer