generated from coulomb/repo-seed
150 lines
4.7 KiB
Markdown
150 lines
4.7 KiB
Markdown
---
|
|
id: GUIDE-BOARD-WP-0007
|
|
type: workplan
|
|
title: "Report And Export Maturity"
|
|
repo: guide-board
|
|
domain: markitect
|
|
status: completed
|
|
owner: codex
|
|
planning_priority: medium
|
|
planning_order: 7
|
|
created: "2026-05-15"
|
|
updated: "2026-05-16"
|
|
state_hub_workstream_id: "ef9351d2-e99c-470e-aeec-f17aa51eae14"
|
|
---
|
|
|
|
# GUIDE-BOARD-WP-0007: Report And Export Maturity
|
|
|
|
## Purpose
|
|
|
|
Improve guide-board's human and machine-readable reporting so assessment output
|
|
is easier to review, compare, and hand off. The current JSON assessment package
|
|
and Markdown report are useful baselines. The next layer should support
|
|
extension report fragments, portable export formats, and stronger trend and gate
|
|
summaries.
|
|
|
|
## Background
|
|
|
|
Real assessment consumers need different report surfaces. Engineers need concise
|
|
run feedback, product teams need readiness summaries, compliance reviewers need
|
|
traceable evidence and boundaries, and external systems may need portable JSON
|
|
or later OSCAL-style interchange. This workplan keeps those surfaces derived
|
|
from the same evidence package.
|
|
|
|
## Boundary
|
|
|
|
This workplan owns generic report and export mechanics. It does not implement
|
|
authority-specific final submission formats unless they can be represented as
|
|
extension-provided fragments or exporters.
|
|
|
|
## D7.1 - Report Fragment Plug-in Contract
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0007-T001
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "bf3fe163-b06d-4c2e-9b45-31721864e1f2"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Define how extensions declare Markdown or structured report fragments.
|
|
- Load fragments safely from extension roots and include them in run reports
|
|
without allowing arbitrary file access.
|
|
- Give fragments access to the assessment package, evidence, mappings, policy
|
|
summary, and source lock data.
|
|
- Add a fixture fragment and tests.
|
|
|
|
Progress:
|
|
|
|
- Added Markdown file and Python module report fragment descriptors.
|
|
- Loaded fragment paths safely from extension roots.
|
|
- Added fragment context for assessment package, evidence, findings, mappings,
|
|
policy summary, and source lock data.
|
|
- Added an SDK fixture Python report fragment and focused tests.
|
|
|
|
## D7.2 - Portable Export Formats
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0007-T002
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "fda51e62-98aa-408e-a057-4db40fe7c644"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Add one or more portable export outputs derived from the assessment package.
|
|
- Start with a stable JSON export manifest before considering OSCAL or other
|
|
external interchange formats.
|
|
- Preserve certification boundary and source lock references in each export.
|
|
- Document which exports are generic and which must remain extension-owned.
|
|
|
|
Progress:
|
|
|
|
- Added `docs/schemas/export-manifest.schema.json`.
|
|
- Wrote `exports/export-manifest.json` for each run.
|
|
- Included source package refs, source lock refs, summaries, policy summaries,
|
|
mapping summaries, report fragments, counts, and certification boundary.
|
|
- Documented the generic export boundary; authority-specific formats remain
|
|
extension-owned.
|
|
|
|
## D7.3 - Trend And Gate Report Improvements
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0007-T003
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "33c3089a-9d5e-4605-89c4-a1e070bc12ad"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Improve retained trend and gate outputs for human review.
|
|
- Surface status changes, unexpected finding deltas, mapping target changes, and
|
|
unresolved review items.
|
|
- Keep machine-readable gate summaries stable for automation.
|
|
- Add CLI report helpers or Markdown summaries where useful.
|
|
|
|
Progress:
|
|
|
|
- Added trend status-change details, unresolved review deltas, mapping target
|
|
deltas, and compact summary text.
|
|
- Kept existing gate summary shape stable while improving trend inputs for
|
|
human review.
|
|
- Added assertions for the richer trend output.
|
|
|
|
## D7.4 - Golden Fixtures And Documentation
|
|
|
|
```task
|
|
id: GUIDE-BOARD-WP-0007-T004
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "66669f68-6728-4484-9ec9-267ffe025027"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Add golden fixture outputs for reports and exports.
|
|
- Document report fragment and export authoring in the extension SDK.
|
|
- Update assessment operations with report/export retrieval examples.
|
|
- Ensure report text remains clear about preparation evidence versus formal
|
|
certification.
|
|
|
|
Progress:
|
|
|
|
- Added golden fixture expectations for report fragment text and export manifest
|
|
top-level shape.
|
|
- Updated extension SDK, assessment operations, architecture, service, container,
|
|
and README docs.
|
|
- Kept report and export boundary language tied to preparation evidence, not
|
|
formal certification.
|
|
|
|
## Definition Of Done
|
|
|
|
- Extensions can contribute report fragments through a documented contract.
|
|
- The core emits portable export artifacts derived from the assessment package.
|
|
- Trend and gate summaries are more useful to humans without breaking
|
|
automation.
|
|
- Golden fixtures guard report and export shape.
|