From 23db4b6dac1db4d2a26c9d49d23da7eff24d132e Mon Sep 17 00:00:00 2001
From: iamdoubz <>
Date: Mon, 6 Jul 2026 23:27:02 -0500
Subject: [PATCH] docs(data-model): align briefs/<id>.json schema (provenance +
 grounding + file-vs-IPC)

---
 docs/03-data-model.md | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/docs/03-data-model.md b/docs/03-data-model.md
index fdf9d4d..5875b19 100644
--- a/docs/03-data-model.md
+++ b/docs/03-data-model.md
@@ -267,13 +267,22 @@ label so re-diarization or renaming never requires rewriting every segment (FR-S
 ## `briefs/<brief_id>.json` (feature brief — ADR-0011)
 
 Agent-ready spec the MCP `get_feature_brief` tool returns. Designed to drop straight into a coding
-agent's context.
+agent's context. Written by `create_feature_brief` (M1); one file per brief under the meeting's
+`briefs/` folder, **sealed at rest with the vault** when unlocked (T8.8), exactly like
+`summary.json`. The `feature_briefs` table indexes it (id, meeting_id, title, target_repo, path,
+exposed) for `list_feature_briefs` and the MCP scope check — the file is the source of truth; the
+row is the index. The IPC `FeatureBrief` type (`04-api-contracts.md`) is the subset returned to the
+UI / MCP: everything below **except** the `schema`/provenance envelope (`generated_at`, `provider`,
+`model`, `source`).
 
 ```jsonc
 {
   "schema": 1,
   "id": "b7a1…",
   "meeting_id": "f1c2…",
+  "generated_at": 1751299200, // envelope: which model distilled this, and when
+  "provider": "ollama",
+  "model": "llama3",
   "title": "Bulk CSV export for the reporting view",
   "problem": "Customer can't get their data out for offline analysis.",
   "desired_outcome": "One-click CSV export of the current filtered report.",
@@ -282,15 +291,21 @@ agent's context.
     "Respects active filters and column order",
     "Streams large exports without blocking the UI",
   ],
-  "target_repo": "acme/reporting-web", // optional hint for the agent
+  "target_repo": "acme/reporting-web", // optional hint the user supplies at create time
   "context_excerpts": [
-    // minimal transcript quotes that ground the request
+    // verbatim transcript quotes that ground the request — NOT model paraphrase;
+    // the builder selects them from the real transcript (speaker = resolved display name)
     { "speaker": "Customer", "text": "We really need to pull this into our own spreadsheets." },
   ],
   "source": { "meeting_title": "Acme quarterly sync", "at": 1751299200 },
 }
 ```
 
+Field presence: `title`, `problem`, `desired_outcome` are always strings (the builder falls back to
+the meeting title / `""` on a sparse model reply); `acceptance_criteria` and `context_excerpts` may
+be empty arrays. Every `context_excerpts[].text` is a verbatim substring of a real transcript
+segment (the M1 grounding invariant, asserted by the golden-transcript test).
+
 ## `settings.json`
 
 ```jsonc