[DOCS]: Add portable regression receipt example to results-and-reporting

[sumit1kr]

Closes #63

Adds a "Portable Regression Receipt" section to docs/usage/results-and-reporting.md
showing how to use existing report.metadata and result.metadata fields to produce
a stable, diffable CI artifact tied to JsonFileReportSink.

No new Python types introduced — docs only.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds documentation describing a "Portable Regression Receipt" pattern for CI gating using JsonFileReportSink, including a sample JSON artifact illustrating run-level and scenario-level metadata.

Changes:

• Adds a new section to docs/usage/results-and-reporting.md explaining how to use report.metadata and result.metadata for stable regression artifacts.
• Provides an example JSON receipt with sample fields.

[sumit1kr]

@microsoft-github-policy-service agree

[gitrishiom]

@sumit1kr

Apologies for the slow response, and thanks for taking this on.

I agree with the docs-only direction here. I also agree with keeping the broader runtime-evidence / production-receipt idea from #63 out of scope for this PR; this section works best as test-time CI evidence using RAMPART’s existing reporting surfaces.

One small thing I noticed while re-checking the current sink behavior: TestRunReport has metadata, but JsonFileReportSink._serialize_report() does not currently include report.metadata in the emitted JSON. It serializes the aggregate fields, population_summary, by_harm_category, and each result’s metadata.

Could you update the docs example to mirror the current JsonFileReportSink output shape and put the stable receipt fields under result.metadata / the relevant by_harm_category result entry?

If maintainers would rather support run-level metadata in the built-in JSON output, then the alternate path would be a tiny serialization + test change for report.metadata, but my preference is to keep this PR docs-only and avoid scope creep.

Once that small alignment is made, I’m happy to take another pass on the diff. Thanks again for moving this forward.

[sumit1kr]

@gitrishiom Updated — moved the receipt fields under result.metadata (nested inside the relevant by_harm_category entry) to match the current JsonFileReportSink output shape, and added a note clarifying that report.metadata isn't currently serialized. Pushed as a follow-up commit. Ready for another pass whenever you get a chance — thanks for the detailed review!

@spencrr tagging again since this is ready for maintainer review/approval whenever you have bandwidth.

[gitrishiom]

Thanks, this addresses the concern.

The example now matches the current JsonFileReportSink output shape, and the note about report.metadata not being serialized is helpful. From my side, this looks aligned with the docs-only scope for #63.

I’ll leave final review/approval to @spencrr . Thanks again for the quick update.