From 0c3ff156d9977708fdf923c330fab0a78cd3c694 Mon Sep 17 00:00:00 2001 From: Happy Mahlangu Date: Mon, 7 Sep 2026 14:41:10 +0200 Subject: [PATCH] docs(trace): document the header control field MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The header's control block (crates/flowproof-trace/schema/trace-v1.schema.json) copies the spec's control: block into every trace and is what `flowproof audit` reads to report control coverage, but the trace-format header section never mentioned it — a schema/doc drift CHARTER.md invariant 5 exists to prevent. Claude-Session: https://claude.ai/code/session_014DBCXghioodAVbbyuyCCWW --- docs/trace-format.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/trace-format.md b/docs/trace-format.md index 6196322..0156440 100644 --- a/docs/trace-format.md +++ b/docs/trace-format.md @@ -186,6 +186,12 @@ already follows. `browser` block (the same shape as the header-level one, which stays the single-surface spelling), applied identically at record and every replay so that surface keeps the shape it was recorded on. +- Optional `control` is the named security control this flow validates, + copied from the spec's `control:` block: `{"id": "...", "title"?: "...", + "description"?: "..."}`. `id` is the author-chosen dotted lowercase + identifier, stable across renames and re-records; `title`/`description` + are free text. Absent for flows without a `control:` block. `flowproof + audit` reads this to report which controls a repository's traces cover. ## Step line