Date: 2026-07-16 Status: accepted Deciders: Thibault Souris (maintainer) Method: decision-loop — the audit's timing finding ("OSCAL-at-green is ahead of the standardization curve: be the implementation people cite, not the one standardized around"), challenge on overclaim, durable position
Context
runward emits OSCAL at the gate: the decision → ADR → conformance manifest → OSCAL component-definition chain, with deterministic UUIDs, derivation rules for implementation-status, a versioned regime lens (ADR-0022) and an evidence seal (ADR-0021). The audit's point is about timing: gate-level, machine-readable audit evidence for agentic delivery has no reference practice yet. Whoever writes the referenceable document first becomes the citation; whoever waits gets standardized around. Today that mapping exists only as implementation (renderOscal) and scattered ADR prose — correct, tested byte-for-byte, and impossible to cite.
Decision
- Publish the mapping as a mini-spec:
docs/spec/runward-oscal-mapping.md, version 1.0, self-contained and implementation-independent — the document a GRC vendor, an auditor or another toolmaker can read without runward's source: the evidence chain, the component-definition shape, the ASI-controls-as-implemented-requirements structure, the implementation-status derivation rules (planned/partial/implemented), the deterministic UUID scheme (seed grammar included), the regime-lens stamp, the byte-identity conditions, and theevidence-lock.jsonv1 format. - Version it like a port (ADR-0011): additive within a major, breaking changes bump the major and keep the old text in place — a published spec is never rewritten under its readers.
- Make citation mechanical: a
CITATION.cffat the repository root (the spec and the tool citable in one gesture), and the spec linked from the README and the compliance docs. - Anti-overclaim guardrails carried into the spec itself: it describes supporting evidence assembled at the gate, states its own scope (never a compliance claim, never a certification), and the honest ingestion boundary (ADR-0022's dated evaluation).
Alternatives discarded
- Submit to a standards body instead. Years-long, and the point is field citation now; a mini-spec can feed a standards process later — the reverse is not true.
- Auto-generate the spec from the code. Couples the document's stability to refactors; a spec's value is that it holds still while implementations move. It is checked against the golden test instead (the reference output is the conformance suite).
- Keep it as ADR prose. ADRs record decisions for maintainers; a citable spec addresses outsiders. Different reader, different document.
Consequences
- Positive. "Feeds your GRC tool" gains a document to point at; third parties can implement or critique the mapping without reading TypeScript; the timing advantage becomes an artifact instead of a hope.
- Negative, accepted. A published spec is a commitment surface: the derivation rules and UUID scheme become hard to change casually (that is the point); spec/implementation drift becomes a new defect class — mitigated by citing the golden fixture as the normative example.
- On other boundaries.
docs/spec/is born;CITATION.cffat the root; README anddocs/compliance/README.mdlink the spec; the golden OSCAL fixture is promoted to normative example.
Reevaluation trigger (mandatory, dated)
Reopen if the mapping needs a breaking change (major bump, old text preserved), or if an external standard emerges that covers this ground — then the spec's job becomes a documented crosswalk to it, not competition with it.
Trigger set on: 2026-07-16 · Watched via: external citations/issues referencing the spec, and the OSCAL/GRC standards landscape at each release review.