feat: add JUnit XML output format for CI integration

Enable `--report junit` to produce JUnit XML, natively consumed by
GitHub Actions, GitLab CI, and Jenkins test result viewers.

- internal/report/junit.go: XML struct types + WriteJUnitReport
- internal/report/junit_test.go: 10 test cases covering all paths
- mdproof.go: facade export
- cmd/mdproof/main.go: CLI wiring for --report junit and -o dispatch
- runbooks/06-output-formats-proof.md: add JUnit steps
- docs updates: README, SKILL.md, advanced-features.md

Author: runkids

README.md

@@ -128,7 +128,7 @@ mdproof sandbox api-proof.md     # auto-provisions a container
 **For AI Agents**
 - Markdown is native — no framework API to learn
 - Self-contained — one file = commands + assertions
-- JSON output — `--report json` for programmatic parsing
+- JSON / JUnit XML output — `--report json` or `--report junit` for programmatic parsing
 - Built-in skill — `skills/SKILL.md` teaches your agent the full syntax
 - Debuggable — agent reads step, sees output, fixes it
 

cmd/mdproof/main.go

@@ -30,16 +30,16 @@ func main() {
 		verbose     countFlag
 	)
 
-	flag.StringVar(&reportFmt, "report", "", "output format: json")
+	flag.StringVar(&reportFmt, "report", "", "output format: json, junit")
 	flag.BoolVar(&dryRun, "dry-run", false, "parse and classify only, don't execute")
 	flag.BoolVar(&showVersion, "version", false, "print version and exit")
 	flag.DurationVar(&timeout, "timeout", 0, "per-step timeout (default: 2m, or from mdproof.json)")
 	flag.StringVar(&cliBuild, "build", "", "command to run once before all runbooks")
 	flag.StringVar(&cliSetup, "setup", "", "command to run before each runbook")
 	flag.StringVar(&cliTeardown, "teardown", "", "command to run after each runbook")
 	flag.BoolVar(&failFast, "fail-fast", false, "stop after first failed step")
-	flag.StringVar(&outputFile, "output", "", "write JSON report to file")
-	flag.StringVar(&outputFile, "o", "", "write JSON report to file (shorthand)")
+	flag.StringVar(&outputFile, "output", "", "write report to file")
+	flag.StringVar(&outputFile, "o", "", "write report to file (shorthand)")
 	flag.Var(&verbose, "v", "verbosity level (-v or -v -v)")
 
 	var (
@@ -250,17 +250,22 @@ func main() {
 		}
 	}
 
-	// Write JSON report to file if --output is specified.
+	// Write report to file if --output is specified.
 	if outputFile != "" && len(reports) > 0 {
 		outF, err := os.Create(outputFile)
 		if err != nil {
 			fmt.Fprintf(os.Stderr, "error: cannot write output file: %v\n", err)
 			os.Exit(1)
 		}
-		if len(reports) == 1 {
-			mdproof.WriteJSONReport(outF, reports[0])
-		} else {
-			mdproof.WriteJSONReports(outF, reports)
+		switch reportFmt {
+		case "junit":
+			mdproof.WriteJUnitReport(outF, reports)
+		default:
+			if len(reports) == 1 {
+				mdproof.WriteJSONReport(outF, reports[0])
+			} else {
+				mdproof.WriteJSONReports(outF, reports)
+			}
 		}
 		if err := outF.Close(); err != nil {
 			fmt.Fprintf(os.Stderr, "error: close output file: %v\n", err)
@@ -368,7 +373,9 @@ func runAllAndReport(files []string, dryRun bool, timeout time.Duration, cfg mdp
 		}
 	}
 
-	if reportFmt != "json" && len(reports) > 0 {
+	if reportFmt == "junit" && len(reports) > 0 {
+		mdproof.WriteJUnitReport(os.Stdout, reports)
+	} else if reportFmt != "json" && len(reports) > 0 {
 		if len(reports) > 1 {
 			mdproof.WritePlainSummary(os.Stdout, reports, verbosity)
 		} else {

internal/report/junit.go

@@ -0,0 +1,149 @@
+package report
+
+import (
+	"encoding/xml"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/runkids/mdproof/internal/core"
+)
+
+type junitTestsuites struct {
+	XMLName    xml.Name         `xml:"testsuites"`
+	Tests      int              `xml:"tests,attr"`
+	Failures   int              `xml:"failures,attr"`
+	Errors     int              `xml:"errors,attr"`
+	Time       string           `xml:"time,attr"`
+	Testsuites []junitTestsuite `xml:"testsuite"`
+}
+
+type junitTestsuite struct {
+	XMLName   xml.Name        `xml:"testsuite"`
+	Name      string          `xml:"name,attr"`
+	Tests     int             `xml:"tests,attr"`
+	Failures  int             `xml:"failures,attr"`
+	Errors    int             `xml:"errors,attr"`
+	Skipped   int             `xml:"skipped,attr"`
+	Time      string          `xml:"time,attr"`
+	Testcases []junitTestcase `xml:"testcase"`
+}
+
+type junitTestcase struct {
+	XMLName   xml.Name      `xml:"testcase"`
+	Name      string        `xml:"name,attr"`
+	Classname string        `xml:"classname,attr"`
+	Time      string        `xml:"time,attr"`
+	Failure   *junitFailure `xml:"failure,omitempty"`
+	Skipped   *junitSkipped `xml:"skipped,omitempty"`
+	SystemOut string        `xml:"system-out,omitempty"`
+}
+
+type junitFailure struct {
+	Message string `xml:"message,attr"`
+	Type    string `xml:"type,attr"`
+	Body    string `xml:",chardata"`
+}
+
+type junitSkipped struct {
+	Message string `xml:"message,attr,omitempty"`
+}
+
+// WriteJUnitReport writes the reports as JUnit XML.
+func WriteJUnitReport(w io.Writer, reports []core.Report) error {
+	var totalTests, totalFailures int
+	var totalMs int64
+
+	suites := make([]junitTestsuite, 0, len(reports))
+	for _, r := range reports {
+		suite := junitTestsuite{
+			Name:     r.Runbook,
+			Tests:    r.Summary.Total,
+			Failures: r.Summary.Failed,
+			Skipped:  r.Summary.Skipped,
+			Time:     msToSeconds(r.DurationMs),
+		}
+
+		for _, sr := range r.Steps {
+			tc := junitTestcase{
+				Name:      sr.Step.Title,
+				Classname: r.Runbook,
+				Time:      msToSeconds(sr.DurationMs),
+			}
+
+			switch sr.Status {
+			case core.StatusFailed:
+				tc.Failure = buildFailure(sr)
+			case core.StatusSkipped:
+				tc.Skipped = &junitSkipped{}
+			}
+
+			if sr.Stdout != "" {
+				tc.SystemOut = sr.Stdout
+			}
+
+			suite.Testcases = append(suite.Testcases, tc)
+		}
+
+		totalTests += r.Summary.Total
+		totalFailures += r.Summary.Failed
+		totalMs += r.DurationMs
+		suites = append(suites, suite)
+	}
+
+	root := junitTestsuites{
+		Tests:      totalTests,
+		Failures:   totalFailures,
+		Time:       msToSeconds(totalMs),
+		Testsuites: suites,
+	}
+
+	io.WriteString(w, xml.Header)
+	out, err := xml.MarshalIndent(root, "", "  ")
+	if err != nil {
+		return err
+	}
+	_, err = w.Write(out)
+	if err != nil {
+		return err
+	}
+	_, err = io.WriteString(w, "\n")
+	return err
+}
+
+func buildFailure(sr core.StepResult) *junitFailure {
+	var msg, typ string
+	var details []string
+
+	for _, a := range sr.Assertions {
+		if !a.Matched {
+			if msg == "" {
+				msg = a.Pattern
+				typ = a.Type
+				if typ == "" {
+					typ = "AssertionError"
+				}
+			}
+			line := a.Pattern
+			if a.Detail != "" {
+				line += " (" + a.Detail + ")"
+			}
+			details = append(details, line)
+		}
+	}
+
+	if msg == "" {
+		msg = core.StepFailReason(sr)
+		typ = "AssertionError"
+	}
+
+	return &junitFailure{
+		Message: msg,
+		Type:    typ,
+		Body:    strings.Join(details, "\n"),
+	}
+}
+
+func msToSeconds(ms int64) string {
+	return fmt.Sprintf("%.3f", float64(ms)/1000)
+}