[NOTICKET] refactor(knowledge-extraction): BriefContext -> DomainContext

The workstream diagram has always called this box "Domain Knowledge", while
the model and its fields described a short orientation card. Rename the entity
to match the intent before anything is persisted: once an expert has approved
rows keyed on these ids, changing the `b_` prefix is an id migration that loses
the approvals - the exact failure the deterministic-id scheme exists to prevent.

BriefContext -> DomainContext
brief_id -> domain_id (prefix b_ -> d_)
ExtractionResult.brief -> .domain
brief_context.json -> domain_context.json

Deliberately unchanged:
- `Branch = "summary"` and GUARDED_FIELDS["summary"]. The branch literal is
the measurement key in CallUsage.branch / RejectedField.branch; renaming it
would break comparability with the committed eval baseline.
- prompts/summary.txt. Editing prompt text needs the eval path, and the
rewrite belongs with the v3 schema change, not with a rename.

No field, prompt or guarding change - the shape is still v2's. Also gitignores
out/knowledge/ (CLI output: data, not code).

Verified: ruff clean on src/knowledge_extraction + src/knowledge_parsing,
`import main` OK, suite 541 passed / 7 skipped. No test references the renamed
symbols. One residual check: branches.py passes the structured-output schema
NAME on the wire, so "BriefContext" -> "DomainContext" alters the LLM request;
almost certainly inert, not yet confirmed by an eval run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitignore

@@ -63,3 +63,4 @@ docs/_archive/
 data/knowledge_cache/
 data/knowledge_runs/
 data/knowledge_docs/
+out/knowledge/

docs/knowledge/KNOWLEDGE_OUTPUT_CONTRACT.md

@@ -24,7 +24,7 @@ nothing consumes.
 
 | Change | Detail |
 |---|---|
-| **Ids on every entity** | `term_id`, `formula_id`, `brief_id`; `rule_id` re-specified. All deterministic and content-derived |
+| **Ids on every entity** | `term_id`, `formula_id`, `domain_id`; `rule_id` re-specified. All deterministic and content-derived |
 | **Glossary no longer restates formulas** | `formula_latex` removed → `defining_formula_id` reference |
 | **Rules link to formulas and terms** | `formula_ids[]`, `term_ids[]` |
 | **`rule_type` added** | `interpretation` \| `calculation` — see §2 for why |
@@ -52,7 +52,7 @@ None is model-generated; none is positional.
 term_id     = "t_" + sha256(doc_id + "|" + canonical)[:10]
 formula_id  = "f_" + sha256(doc_id + "|" + name_or_latex_or_chunk_id)[:10]
 rule_id     = "r_" + sha256(doc_id + "|" + chunk_id + "|" + char_start)[:10]
-brief_id    = "b_" + sha256(doc_id)[:10]
+domain_id   = "d_" + sha256(doc_id)[:10]
 ```
 
 Implemented in `src/knowledge_extraction/ids.py`. `term_id` is keyed on the **cluster canonical**,
@@ -80,7 +80,7 @@ registry, which belongs with persistence (DEV_PLAN §0.8 D2).
 | `glossary.json` | `GlossaryEntry[]` | Terms and their definitions |
 | `interpretation_pack.json` | `RuleEntry[]` | Rules of thumb — how to interpret data or behaviour |
 | `formulas.json` | `FormulaEntry[]` | Formulas, transcribed from the document |
-| `brief_context.json` | `BriefContext` | One orientation brief per document |
+| `domain_context.json` | `DomainContext` | One domain-context entry per document (renamed from `brief_context.json` / `BriefContext`, 2026-09-01) |
 
 Plus three derived/audit payloads: `review_queue.json`, `rejected.json`, `usage.json`.
 
@@ -340,11 +340,11 @@ consequence can.
 
 ---
 
-## 8 · `brief_context.json` → `BriefContext` — 5 fields *(single object)*
+## 8 · `domain_context.json` → `DomainContext` — 5 fields *(single object)*
 
 ```json
 {
-  "brief_id": "b_2ef60a8c19",
+  "domain_id": "d_2ef60a8c19",
   "title": "Standard Parameter Produksi & ECA",
   "purpose": "Standard Parameter ini merupakan pedoman dalam perhitungan parameter produksi yang meliputi Qty, PA, UA, PTY, serta Equipment Capacity Analysis (ECA)...",
   "key_parameters": ["Qty", "PA", "UA", "PTY", "ECA", "Grouping (Composite)"],
@@ -360,7 +360,7 @@ consequence can.
 
 | Field | Type | Req |
 |---|---|---|
-| `brief_id` | string | ✅ **New in v2** |
+| `domain_id` | string | ✅ **New in v2** |
 | `title` | string \| null | — |
 | `purpose` | string \| null | — |
 | `key_parameters` | string[] | ✅ Default `[]` |

src/knowledge_extraction/__init__.py

@@ -22,10 +22,10 @@ Calibrated constants and why: KNOWLEDGE_PIPELINE_CALIBRATION.md
 from .adapter import parsed_doc_from_artifact
 from .models import (
     AbbrevPair,
-    BriefContext,
     CallUsage,
     Chunk,
     ClusterResult,
+    DomainContext,
     FilterResult,
     FormulaEntry,
     GlossaryEntry,
@@ -40,7 +40,7 @@ from .service import ExtractionResult, build_clusters, estimate_cost, extract_al
 
 __all__ = [
     "AbbrevPair",
-    "BriefContext",
+    "DomainContext",
     "CallUsage",
     "Chunk",
     "ClusterResult",

src/knowledge_extraction/cli.py

@@ -221,8 +221,8 @@ def main(argv: list[str] | None = None) -> int:
     _dump(args.out_dir / "formulas.json", result.formulas)
     _dump(args.out_dir / "review_queue.json", result.review_queue)
     _dump(args.out_dir / "rejected.json", [r.model_dump(mode="json") for r in result.rejected])
-    if result.brief:
-        _dump(args.out_dir / "brief_context.json", result.brief)
+    if result.domain:
+        _dump(args.out_dir / "domain_context.json", result.domain)
     _dump(args.out_dir / "usage.json", [u.model_dump(mode="json") for u in result.usages])
     print(f"[write ] {args.out_dir}")
     return 0

src/knowledge_extraction/extract/branches.py

@@ -13,11 +13,11 @@ response must not abort a corpus-scale run that has already paid for parsing.
 from __future__ import annotations
 
 from ...middlewares.logging import get_logger
-from ..ids import brief_id, formula_id, rule_id, term_id
+from ..ids import domain_id, formula_id, rule_id, term_id
 from ..models import (
-    BriefContext,
     CallUsage,
     Chunk,
+    DomainContext,
     FormulaEntry,
     FormulaVariable,
     GlossaryEntry,
@@ -207,7 +207,7 @@ def extract_formula(
 
 def extract_summary(
     chunks: list[Chunk], extractor, doc_id: str
-) -> tuple[BriefContext | None, CallUsage]:
+) -> tuple[DomainContext | None, CallUsage]:
     """Whole-document summary — the quiet cost risk. Few calls, but a large
     share of all input tokens, because summarisation cannot be filtered: it
     needs the whole document.
@@ -218,7 +218,7 @@ def extract_summary(
     """
     user = evidence_block(chunks)
     result = extractor.complete(
-        "summary", load_prompt("summary"), user, schema_for("summary"), "BriefContext"
+        "summary", load_prompt("summary"), user, schema_for("summary"), "DomainContext"
     )
     try:
         draft = SummaryDraft.model_validate(result.data)
@@ -227,8 +227,8 @@ def extract_summary(
         return None, result.usage
 
     return (
-        BriefContext(
-            brief_id=brief_id(doc_id),
+        DomainContext(
+            domain_id=domain_id(doc_id),
             title=draft.title,
             purpose=draft.purpose,
             key_parameters=draft.key_parameters,

src/knowledge_extraction/extract/schemas.py

@@ -7,7 +7,7 @@ invitation to fabricate**, so the request schema is narrower than the stored one
 
 v2 narrowed it further, and every removal has a reason of that kind:
 
-- **ids and links** (`term_id`, `formula_id`, `rule_id`, `brief_id`,
+- **ids and links** (`term_id`, `formula_id`, `rule_id`, `domain_id`,
   `defining_formula_id`, `formula_ids`, `term_ids`, `variables[].term_id`) are
   minted deterministically. A model cannot produce a stable identifier — it has
   no memory of what it emitted last run — and `rule_id` being model-written was

src/knowledge_extraction/ids.py

@@ -71,6 +71,13 @@ def rule_id(doc_id: str, chunk_id: str, char_start: int) -> str:
     return f"r_{_digest(doc_id, chunk_id, str(char_start))}"
 
 
-def brief_id(doc_id: str) -> str:
-    """One orientation brief per document, so the document identifies it."""
-    return f"b_{_digest(doc_id)}"
+def domain_id(doc_id: str) -> str:
+    """One domain-context entry per document, so the document identifies it.
+
+    Prefix moved `b_` → `d_` with the `BriefContext` → `DomainContext` rename
+    (2026-09-01). Free to do then because nothing was persisted yet; once an
+    expert has approved rows keyed on these, changing a prefix is an id
+    migration that loses the approvals — the same failure the whole scheme
+    exists to prevent.
+    """
+    return f"d_{_digest(doc_id)}"

src/knowledge_extraction/models.py

@@ -308,17 +308,25 @@ class FormulaEntry(BaseModel):
     latex_verification: LatexVerification | None = None
 
 
-class BriefContext(BaseModel):
-    """Whole-document orientation brief. The only branch that cannot be
+class DomainContext(BaseModel):
+    """Whole-document domain context. The only branch that cannot be
     span-checked — a plausible summary is indistinguishable from a correct one,
     which is why it belongs on the larger model tier when one is available.
 
+    Renamed from `BriefContext` 2026-09-01. The name was the smaller half of the
+    problem: the workstream diagram has always called this box *Domain
+    Knowledge*, while the fields describe a short orientation card. The shape
+    below is still v2's — the v3 proposal that closes the gap (deriving the
+    document outline and subdomain coverage, and turning `purpose` from a
+    generated summary into a span-guarded verbatim quote) is
+    `docs/knowledge/KNOWLEDGE_DOMAIN_CONTEXT_V3.md`, and is NOT implemented.
+
     `summary_md` and `scope` were dropped in v2 for that same reason: the
     longest unverifiable prose on the least verifiable branch bought the least,
     and `scope` overlapped `purpose`. What remains is what a reviewer needs to
     orient before working the queue."""
 
-    brief_id: str
+    domain_id: str
     title: str | None = None
     purpose: str | None = None
     key_parameters: list[str] = Field(default_factory=list)

src/knowledge_extraction/service.py

@@ -53,7 +53,7 @@ class ExtractionResult:
         self.glossary: list[dict] = []
         self.rules: list[dict] = []
         self.formulas: list[dict] = []
-        self.brief: dict | None = None
+        self.domain: dict | None = None
         self.review_queue: list[dict] = []
         self.rejected: list[RejectedField] = []
         self.usages: list[CallUsage] = []
@@ -248,4 +248,4 @@ def _run_summary(doc, extractor, out) -> None:
         return
     # Summary prose is NOT span-checked — it cannot be. Only its provenance is
     # carried, and the branch belongs on a larger tier for exactly that reason.
-    out.brief = entry.model_dump(mode="json")
+    out.domain = entry.model_dump(mode="json")

src/knowledge_parsing/README.md

@@ -147,7 +147,7 @@ All kept off the nearly-full `C:` drive:
 
 **The file name is currently a primary key, not a label.** `doc_id` is the file
 name stem; `chunk_id` is built from `doc_id`; and `term_id`, `formula_id`,
-`rule_id` and `brief_id` are all digests of `doc_id` (`knowledge_extraction/ids.py`).
+`rule_id` and `domain_id` are all digests of `doc_id` (`knowledge_extraction/ids.py`).
 Renaming a file after ingestion therefore changes every identifier derived from
 it, and an expert's approve/reject decisions are keyed to those identifiers.