Post-processor

What it is

The post-processor is an internal Python module that takes the StrictDoc .sdoc graph and the test runners’ raw output, joins them together, and produces:

• The browseable Requirements Traceability Matrix (RTM) — StrictDoc’s own HTML, augmented with per-requirement test-result badges that deep-link into the Allure dashboard
• The review-state classification (reviewed / unreviewed / suspect-native / suspect-inherited / change-in-progress / inactive) for every requirement and test, propagating suspect state through typed-link graph edges
• A pre-merge gate (--fail-on-suspect) that fails CI when a regulated artefact has drifted from its last approved content without a covering change record

It is a regulated tool in its own right — its output is what a future auditor reads to follow the chain from a deployed binary back to every approval.

Why we chose to build it (vs. off-the-shelf)

• No commercial RTM tool matches our specific input mix (StrictDoc + JUnit XML + Allure JSON + change records) without expensive bespoke integration
• Drift detection is the key regulated property and we want full control over the hash semantics, the propagation graph, and the gate behaviour
• Output is plain HTML over StrictDoc’s native exports — we extend, we don’t replace; if StrictDoc’s HTML changes, we adapt, but we never inherit a vendor’s RTM model
• The code is small (~1300 lines), focused, and unit-testable

Where it lives

• Module: tools/post_processor/rtm.py (CLI entry point + every subroutine)
• Local preview server: tools/post_processor/serve.py (small wrapper that boots Python’s http.server against the rendered RTM artefact for review)
• CI invocation: .github/workflows/pr_branch_tests.yml — the system-and-rtm job runs the post-processor with and without --fail-on-suspect
• Local invocation: see How to operate it below

How to operate it

After running the test suites and StrictDoc export:

# 1. Export StrictDoc HTML
uv run strictdoc export regulatory-docs/ --output-dir regulatory-docs/output

# 2. Run the post-processor (renders the RTM with badges + Allure dashboard)
uv run python -m tools.post_processor.rtm

# 3. Run the suspect-state gate (returns non-zero on unauthorised drift)
uv run python -m tools.post_processor.rtm --no-allure --fail-on-suspect

To browse the result locally:

uv run python tools/post_processor/serve.py --dir regulatory-docs/output/html

Then open http://localhost:8000. The Mermaid graph diagrams, badge colours, and Allure deep-links all render in the browser; opening the static index.html directly via file:// will not work (Allure requires HTTP).

Useful flags

Flag	What it does
--no-allure	Skip Allure dashboard generation. Useful for CI gate-only runs and CI environments that don’t have allure CLI installed.
--fail-on-suspect	Exit non-zero when any regulated artefact is in suspect-native or suspect-inherited state. Used as the merge gate.
--print-hash <UID>	Print the canonical content hash for a single requirement. Debug aid for matching against an existing REVIEWED_HASH.
--changes-dir <path>	Override the default changes/ directory location.

Versioning / update policy

The post-processor is regulated software in its own right — bugs in it can produce wrong audit conclusions. Update policy:

• Source-controlled in this repo; every change goes through the same gated PR process (CODEOWNERS path: tools/post_processor/** → @DougYoungberg)
• Hash semantics are pinned by the REVIEWABLE_FIELDS tuple in tools/post_processor/rtm.py — any change to that tuple invalidates every stored REVIEWED_HASH. Treat as a major-version event: every regulated artefact must be re-reviewed and re-stamped
• Tool qualification: a Computer Software Assurance (CSA) package for the post-processor is a deliverable on the regulated roadmap, outlined in the skill file. Status: pending.

External documentation

The post-processor is internal; this page is its canonical documentation. The closest external reference is StrictDoc’s own exporter documentation, which describes the HTML the post-processor builds on top of.

For the regulated context the post-processor operates in — review-state semantics, typed-link propagation, change-record states — see the skill file, particularly §8.