okstra 0.189.2 → 0.189.4

package/runtime/python/okstra_ctl/report_html/common.py

@@ -1,6 +1,9 @@
 """Common data transformations that carry no task-specific section order."""
 from __future__ import annotations
 
+import re
+from collections.abc import Iterator
+
 
 # 본문이 인용하지만 전용 섹션이 없는 행만 대장에 넣는다. 키 이름만으로
 # 블록을 고르면 `evidence.primary` 의 내용과 다른 블록의 출처 칸이 섞인다.
@@ -13,8 +16,8 @@ from __future__ import annotations
 #
 # `endStateCoverage` is deliberately absent. Its rows hold an id pair
 # (`EB-001` covered by `R-001`) rather than a statement, so the ledger rendered
-# them as an id with no body, and the requirement-coverage table already names
-# every one of them in its Source column.
+# them as an id with no body. Those ids anchor in the end-state section the
+# base template renders from the brief and this coverage table together.
 #
 # The kind each row carries is a vocabulary key, not the words the reader sees:
 # the labels live in the i18n `ledgerKind` table so they arrive in the reader's
@@ -30,6 +33,11 @@ _LEDGER_BLOCKS = (
     (("followUpTasks",), "title", "reason", "", "follow-up"),
 )
 
+# The keys a row's identity may sit under. `agentActivity` numbers its rows
+# `activityId`; a supersession entry names the answer it overturns by
+# `clarificationId` and has no id of its own.
+_ROW_ID_KEYS = ("id", "activityId", "clarificationId")
+
 
 def _dig(data: dict, path: tuple[str, ...]) -> list:
     node: object = data
@@ -63,34 +71,17 @@ def _ledger_row(
     }
 
 
-def _own_section_ids(data: dict, omitted_fields: tuple[str, ...] = ()) -> set[str]:
-    """Ids a section of the report already renders and anchors.
-
-    The ledger is the fallback home for a cited row, so it must not claim an id
-    that has one — two elements with the same anchor send half the links to the
-    wrong place. `crossVerification.consensus` numbers its rows `CV-001`, a
-    namespace of its own, so a `C-NNN` in the report has exactly one home.
-
-    `omitted_fields` names task-block fields the HTML template does not render,
-    so their ids do not count as anchored.
-    """
-    from ..report_contract import TASK_TYPE_DATA_PROPERTY
-
-    found: set[str] = set()
-    _collect_ids(data.get("clarificationItems", []), found)
-    _collect_ids(data.get("agentActivity", []), found)
-    property_name = TASK_TYPE_DATA_PROPERTY.get(data.get("header", {}).get("taskType", ""))
-    if property_name:
-        block = data.get(property_name, {})
-        if omitted_fields and isinstance(block, dict):
-            block = {
-                key: value for key, value in block.items() if key not in omitted_fields
-            }
-        _collect_ids(block, found)
-    return found
+def _row_id(row: object) -> str | None:
+    if not isinstance(row, dict):
+        return None
+    for key in _ROW_ID_KEYS:
+        value = row.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
 
 
-_OMITTED_TEXT_KEYS = (
+_ROW_TEXT_KEYS = (
     "subject",
     "check",
     "item",
@@ -100,47 +91,136 @@ _OMITTED_TEXT_KEYS = (
     "summary",
     "need",
     "title",
+    "commitment",
+    "condition",
 )
 
 
-def _omitted_row_text(row: dict) -> str:
-    """생략된 행에서 독자가 읽을 한 줄을 고른다."""
-    for key in _OMITTED_TEXT_KEYS:
+def _row_text(row: dict) -> str:
+    """전용 섹션이 없는 행에서 독자가 읽을 한 줄을 고른다."""
+    for key in _ROW_TEXT_KEYS:
         value = row.get(key)
         if isinstance(value, str) and value.strip():
             return value.strip()
     return ""
 
 
-def _collect_row_dicts(value: object, rows: dict[str, dict]) -> None:
+def _task_block(data: dict) -> dict:
+    from ..report_contract import TASK_TYPE_DATA_PROPERTY
+
+    property_name = TASK_TYPE_DATA_PROPERTY.get(
+        (data.get("header") or {}).get("taskType", "")
+    )
+    block = data.get(property_name) if property_name else None
+    return block if isinstance(block, dict) else {}
+
+
+def rows_at(data: dict, path: str) -> list[dict]:
+    """Every row dict at a dotted path from the record root.
+
+    A list along the way is walked implicitly — `implementationPlanning.
+    optionCandidates.fileStructure` reaches the file rows of every candidate —
+    so a template's `{% for %}` nesting and this path read the same rows.
+    """
+    nodes: list[object] = [data]
+    for part in path.split("."):
+        next_nodes: list[object] = []
+        for node in nodes:
+            if not isinstance(node, dict):
+                continue
+            value = node.get(part)
+            if isinstance(value, list):
+                next_nodes.extend(value)
+            elif isinstance(value, dict):
+                next_nodes.append(value)
+        nodes = next_nodes
+    return [node for node in nodes if isinstance(node, dict)]
+
+
+def scoped_anchor_map(data: dict, path: str) -> dict[str, dict[str, str]]:
+    """`{parent id: {child id: anchor}}` for rows that repeat under every parent.
+
+    A direction's scope commitments are numbered `IC-001` … inside each
+    direction, so the same id sits in every ranked option. One page-global
+    `#id-IC-001` would land on whichever card came first; instead each card
+    anchors its own rows as `id-<parent>-<child>` and links the ids its prose
+    cites to those.
+    """
+    parent_path, _, child_key = path.rpartition(".")
+    out: dict[str, dict[str, str]] = {}
+    for parent in rows_at(data, parent_path):
+        parent_id = _row_id(parent)
+        children = parent.get(child_key)
+        if not parent_id or not _anchorable(parent_id) or not isinstance(children, list):
+            continue
+        for child in children:
+            child_id = _row_id(child)
+            if child_id and _anchorable(child_id):
+                out.setdefault(parent_id, {})[child_id] = f"id-{parent_id}-{child_id}"
+    return out
+
+
+def _scoped_ids(data: dict, scoped_fields: tuple[str, ...]) -> set[str]:
+    found: set[str] = set()
+    for path in scoped_fields:
+        for children in scoped_anchor_map(data, path).values():
+            found.update(children)
+    return found
+
+
+def _own_section_ids(data: dict, anchored_fields: tuple[str, ...]) -> set[str]:
+    """Ids a section of the report renders under a page-global anchor.
+
+    The clarification articles and the base template's activity table anchor
+    their rows on every page; the task template anchors the rows of the
+    fields its view declares. The ledger is the fallback home for a cited row,
+    so it must not claim an id that has one — two elements with the same
+    anchor send half the links to the wrong place.
+    """
+    found: set[str] = set()
+    _collect_ids(data.get("clarificationItems", []), found)
+    _collect_ids(data.get("agentActivity", []), found)
+    for path in anchored_fields:
+        for row in rows_at(data, path):
+            row_id = _row_id(row)
+            if row_id:
+                found.add(row_id)
+    return found
+
+
+def _task_block_rows(value: object) -> Iterator[dict]:
+    """Every dict carrying a row id anywhere in the task block, document order."""
     if isinstance(value, dict):
-        row_id = value.get("id") or value.get("activityId") or value.get("clarificationId")
-        if isinstance(row_id, str) and row_id:
-            rows.setdefault(row_id, value)
+        if _row_id(value):
+            yield value
         for nested in value.values():
-            _collect_row_dicts(nested, rows)
+            yield from _task_block_rows(nested)
     elif isinstance(value, list):
         for nested in value:
-            _collect_row_dicts(nested, rows)
+            yield from _task_block_rows(nested)
 
 
-def _omitted_rows(data: dict, omitted_fields: tuple[str, ...]) -> dict[str, dict]:
-    from ..report_contract import TASK_TYPE_DATA_PROPERTY
+def _unanchored_rows(
+    data: dict, owned: set[str], scoped: set[str]
+) -> dict[str, dict]:
+    """Task-block rows no section anchors, keyed by id, first occurrence wins.
 
-    property_name = TASK_TYPE_DATA_PROPERTY.get(
-        (data.get("header") or {}).get("taskType", "")
-    )
-    block = data.get(property_name) if property_name else None
-    if not isinstance(block, dict):
-        return {}
+    Their ids are still cited by prose — a validation check, a rollback step,
+    a candidate's commitment — so the ledger gives each a line to land on.
+    """
     rows: dict[str, dict] = {}
-    for field in omitted_fields:
-        _collect_row_dicts(block.get(field), rows)
+    for row in _task_block_rows(_task_block(data)):
+        row_id = _row_id(row)
+        if row_id in owned or row_id in scoped or row_id in rows:
+            continue
+        rows[row_id] = row
     return rows
 
 
 def evidence_index(
-    data: dict, omitted_fields: tuple[str, ...] = ()
+    data: dict,
+    anchored_fields: tuple[str, ...] = (),
+    scoped_fields: tuple[str, ...] = (),
 ) -> dict[str, object]:
     """The rows the ledger carries, keyed by id.
 
@@ -148,11 +228,12 @@ def evidence_index(
     ledger exists so a cited id resolves to something the reader can read, and
     an id above a blank line resolves to nothing.
 
-    `omitted_fields` are task-block arrays the HTML template does not render
-    as their own section. Their rows still have to land somewhere, because
-    prose cites them — without a ledger entry the id in the body is dead text.
+    `anchored_fields` and `scoped_fields` are the view's declarations of what
+    its template anchors (see `HumanReportView`). Every other task-block row
+    with an id lands here, so a citation of it resolves to its own text.
     """
-    owned = _own_section_ids(data, omitted_fields)
+    owned = _own_section_ids(data, anchored_fields)
+    scoped = _scoped_ids(data, scoped_fields)
     rows: dict[str, object] = {}
     for path, text_key, source_key, confidence_key, kind in _LEDGER_BLOCKS:
         for row in _dig(data, path):
@@ -164,26 +245,103 @@ def evidence_index(
             entry = _ledger_row(row, text_key, source_key, confidence_key, kind)
             if entry["text"]:
                 rows[row_id] = entry
-    for row_id, row in _omitted_rows(data, omitted_fields).items():
+    for row_id, row in _unanchored_rows(data, owned, scoped).items():
+        if row_id in rows:
+            continue
+        text = _row_text(row)
+        if not text:
+            continue
+        rows[row_id] = {
+            "id": row_id,
+            "kind": "record-row",
+            "text": text,
+            "codeEvidence": row.get("currentCodeEvidence") or [],
+            "source": "",
+            "confidence": "",
+        }
+    for row_id, row in _cited_summary_rows(data).items():
         if row_id in owned or row_id in rows:
             continue
-        text = _omitted_row_text(row)
+        text = _joined(row.get("summary"))
         if not text:
             continue
         rows[row_id] = {
             "id": row_id,
-            "kind": "plan-item",
+            "kind": "summary-point",
             "text": text,
             "codeEvidence": [],
-            "source": "",
+            "source": _joined(row.get("source")),
             "confidence": "",
         }
     return rows
 
 
+_SUMMARY_ID_RE = re.compile(r"\bP-\d{3,}\b")
+_FINDING_ID_RE = re.compile(r"\b(F-\d{3,})\b")
+
+
+def _cited_summary_rows(data: dict) -> dict[str, dict]:
+    """`summary[]` rows some other field of the record cites by id.
+
+    The summary is the AI-facing digest and does not render, but a writer
+    who names `P-005` in prose sends the reader after it — 2026-09-05 audit:
+    requirements-discovery and release-handoff pages carried such bare ids. A
+    cited row lands in the ledger; an uncited one stays out, so the ledger does
+    not duplicate the digest.
+    """
+    rows = {
+        row["id"]: row
+        for row in data.get("summary") or []
+        if isinstance(row, dict) and isinstance(row.get("id"), str) and row["id"]
+    }
+    if not rows:
+        return {}
+    cited: set[str] = set()
+
+    def walk(node: object) -> None:
+        if isinstance(node, dict):
+            for value in node.values():
+                walk(value)
+        elif isinstance(node, list):
+            for value in node:
+                walk(value)
+        elif isinstance(node, str):
+            cited.update(match for match in _SUMMARY_ID_RE.findall(node) if match in rows)
+
+    walk({key: value for key, value in data.items() if key != "summary"})
+    return {row_id: row for row_id, row in rows.items() if row_id in cited}
+
+
+def worker_finding_links(data: dict) -> dict[str, str]:
+    """`F-NNN` → the promoted evidence row whose `sourceItems` cite it.
+
+    A worker numbers its own findings `F-001` …; the record promotes the ones
+    the workers agreed on into `evidence.primary[]`, each naming its sources as
+    `<worker>:F-NNN`. Prose keeps citing the worker number — 15 to 20 times a
+    report in the 2026-09-05 audit — so when exactly one evidence row carries
+    that number, the citation links there. A number two rows share, or none
+    does, stays plain text: a guess would send the reader to the wrong row.
+    """
+    homes: dict[str, set[str]] = {}
+    for row in _dig(data, ("evidence", "primary")):
+        if not isinstance(row, dict):
+            continue
+        row_id = row.get("id")
+        if not isinstance(row_id, str) or not _anchorable(row_id):
+            continue
+        for item in row.get("sourceItems") or []:
+            for finding in _FINDING_ID_RE.findall(str(item)):
+                homes.setdefault(finding, set()).add(row_id)
+    return {
+        finding: f"#id-{next(iter(rows))}"
+        for finding, rows in homes.items()
+        if len(rows) == 1
+    }
+
+
 def _collect_ids(value: object, found: set[str]) -> None:
     if isinstance(value, dict):
-        for key in ("id", "activityId", "clarificationId"):
+        for key in _ROW_ID_KEYS:
             row_id = value.get(key)
             if isinstance(row_id, str) and row_id:
                 found.add(row_id)
@@ -199,61 +357,35 @@ def _anchorable(row_id: str) -> bool:
     return bool(row_id) and " " not in row_id and "/" not in row_id
 
 
-def _count_ids(value: object, counts: dict[str, int]) -> None:
-    if isinstance(value, dict):
-        for key in ("id", "activityId", "clarificationId"):
-            row_id = value.get(key)
-            if isinstance(row_id, str) and row_id:
-                counts[row_id] = counts.get(row_id, 0) + 1
-        for nested in value.values():
-            _count_ids(nested, counts)
-    elif isinstance(value, list):
-        for nested in value:
-            _count_ids(nested, counts)
-
-
-def _shared_task_block_ids(data: dict, omitted_fields: tuple[str, ...]) -> set[str]:
-    """Ids several rows of the task block carry, so no single row owns them.
-
-    A direction's scope commitments are numbered `IC-001` … inside each
-    direction, and its planning invariants `PI-001` … likewise; the same id
-    sits in every ranked option and every audited candidate. A link to
-    `#id-IC-001` would land on whichever card came first, so the id stays
-    plain text. A clarification id the block repeats (a requirements report
-    lists `C-001` under two unresolved requirements) is not affected: the
-    clarification article is its one home and keeps the anchor.
-    """
-    from ..report_contract import TASK_TYPE_DATA_PROPERTY
-
-    property_name = TASK_TYPE_DATA_PROPERTY.get(
-        (data.get("header") or {}).get("taskType", "")
-    )
-    block = data.get(property_name) if property_name else None
-    if not isinstance(block, dict):
-        return set()
-    counts: dict[str, int] = {}
-    _count_ids(
-        {key: value for key, value in block.items() if key not in omitted_fields},
-        counts,
-    )
-    owned_elsewhere: set[str] = set()
-    _collect_ids(data.get("clarificationItems", []), owned_elsewhere)
-    _collect_ids(data.get("agentActivity", []), owned_elsewhere)
-    return {row_id for row_id, n in counts.items() if n > 1} - owned_elsewhere
+def end_state_ids(data: dict) -> list[str]:
+    """The end-state ids this run judged, in `endStateCoverage` order."""
+    out: list[str] = []
+    for row in data.get("endStateCoverage") or []:
+        row_id = _row_id(row)
+        if row_id and _anchorable(row_id) and row_id not in out:
+            out.append(row_id)
+    return out
 
 
-def anchor_index(data: dict, omitted_fields: tuple[str, ...] = ()) -> dict[str, str]:
+def anchor_index(
+    data: dict,
+    anchored_fields: tuple[str, ...] = (),
+    scoped_fields: tuple[str, ...] = (),
+) -> dict[str, str]:
     """Map every row a reader can reach to the anchor name that lands on it.
 
     Prose cites ids across section boundaries — a hotspot names a
     cross-verification finding, a quality row names a difference — so the
-    target set spans the whole reader-facing report: the task's own sections,
-    the clarifications, and every block the ledger takes in, including rows
-    whose section the template left out.
+    target set spans the whole reader-facing report: the sections the view
+    declares anchored, the clarifications, the activity table, the end-state
+    section, and every row the ledger takes in.
 
-    It stops there. `summary` is the AI-facing digest and
+    It stops there. `summary` is the AI-facing digest and does not render —
+    only a summary row some other field cites reaches the ledger — and
     `analysisCommon.scope` describes the analysis target rather than listing
-    rows; neither renders, so a link to one would land nowhere.
+    rows, so a link to it would land nowhere. Rows under a
+    scoped field anchor inside their parent's card (`scoped_anchor_map`) and
+    take no page-global name.
 
     Cross-check rows are anchored `id-xv-<id>` by the base template — the
     prefix keeps a legacy consensus row still numbered `C-NNN` from sharing
@@ -262,9 +394,10 @@ def anchor_index(data: dict, omitted_fields: tuple[str, ...] = ()) -> dict[str,
     pointing at the clarification.
     """
     found = (
-        _own_section_ids(data, omitted_fields)
-        - _shared_task_block_ids(data, omitted_fields)
-    ) | set(evidence_index(data, omitted_fields))
+        _own_section_ids(data, anchored_fields)
+        | set(evidence_index(data, anchored_fields, scoped_fields))
+        | set(end_state_ids(data))
+    )
     index = {
         row_id: f"id-{row_id}"
         for row_id in sorted(found)
@@ -281,10 +414,5 @@ def anchor_index(data: dict, omitted_fields: tuple[str, ...] = ()) -> dict[str,
 def analysis_review_ids(data: dict) -> tuple[str, ...]:
     found: set[str] = set()
     _collect_ids(data.get("analysisCommon", {}), found)
-    task_type = data.get("header", {}).get("taskType", "")
-    from ..report_contract import TASK_TYPE_DATA_PROPERTY
-
-    property_name = TASK_TYPE_DATA_PROPERTY.get(task_type)
-    if property_name:
-        _collect_ids(data.get(property_name, {}), found)
+    _collect_ids(_task_block(data), found)
     return tuple(sorted(found))

package/runtime/python/okstra_ctl/report_html/context_links.py

@@ -26,6 +26,7 @@ import re
 from collections.abc import Container
 from pathlib import Path
 
+from ..final_report_paths import final_report_data_path
 from ..json_boundary import JsonBoundaryError, load_owned_object
 from ..report_view_artifacts import html_view_path
 from ..scope_provenance import brief_end_state_rows
@@ -80,6 +81,9 @@ def _carry_in_record(source: Path) -> Path | None:
     """
     if source.name.endswith(".data.json"):
         return source
+    if source.name.startswith("final-report-") and source.name.endswith(".md"):
+        # 승인 계획은 열람본(`.md`)으로 가리킨다; 레코드는 그 형제다.
+        return final_report_data_path(source)
     match = _USER_RESPONSE_RE.match(source.name)
     if match is None or source.parent.name != "user-responses":
         return None
@@ -135,3 +139,120 @@ def carry_in_links(
         for cid in _clarification_ids(record)
         if cid not in exclude
     }
+
+
+# The brief headings `scope_provenance.brief_end_state_rows` records as `section`;
+# a coverage-only row gets the heading its id family belongs to.
+_END_STATE_SECTIONS = {"EB": "Expected Behavior", "PB": "Preserved Behavior", "EO": "Expected Outcome"}
+
+
+def end_state_table(brief_rows: list[dict[str, str]], data: dict) -> list[dict[str, object]]:
+    """The end-state section's rows: the brief's statements joined with this
+    run's `endStateCoverage` verdicts.
+
+    Brief order first, then ids the coverage table judges that the brief (or a
+    task with no brief file) did not list, so every `EB`/`PB`/`EO` the record
+    cites has a row here whether or not the brief was readable. A row without
+    a brief statement carries the coverage rationale as its text.
+    """
+    coverage: dict[str, dict] = {}
+    for row in data.get("endStateCoverage") or []:
+        if isinstance(row, dict) and isinstance(row.get("id"), str) and row["id"]:
+            coverage.setdefault(row["id"], row)
+    out: list[dict[str, object]] = []
+    seen: set[str] = set()
+    for row in brief_rows:
+        seen.add(row["id"])
+        out.append({**row, "coverage": coverage.get(row["id"])})
+    for row_id, row in coverage.items():
+        if row_id in seen:
+            continue
+        out.append({
+            "id": row_id,
+            "section": _END_STATE_SECTIONS.get(row_id.split("-")[0], ""),
+            "statement": "",
+            "coverage": row,
+        })
+    return out
+
+
+def selected_direction_links(
+    data: dict, data_path: Path, *, exclude: Container[str] = ()
+) -> dict[str, str]:
+    """Map the planning report's selected direction id to its card on the
+    option-selection page it came from.
+
+    A plan built with `--selected-direction` names that report in
+    `implementationPlanning.selectedDirectionRef.sourceReport` (task-relative)
+    and cites the direction as `IO-NNN` throughout — four bare mentions on
+    the 2026-09-05 dev-10626 planning page. The link exists only when the
+    source record is on disk; a plan whose source moved keeps the id as text.
+    """
+    reference = (data.get("implementationPlanning") or {}).get("selectedDirectionRef")
+    if not isinstance(reference, dict):
+        return {}
+    option_id = reference.get("optionId")
+    source = reference.get("sourceReport")
+    if not (isinstance(option_id, str) and option_id and isinstance(source, str) and source.strip()):
+        return {}
+    if option_id in exclude:
+        return {}
+    task_dir = _task_dir(data_path)
+    if task_dir is None:
+        return {}
+    # `sourceReport` names the reading copy (`.md`); the record is its sibling.
+    pointer = task_dir / source.strip()
+    record = pointer if pointer.name.endswith(".data.json") else final_report_data_path(pointer)
+    if not record.is_file():
+        return {}
+    page = html_view_path(record)
+    href = Path(os.path.relpath(page, data_path.resolve().parent)).as_posix()
+    return {option_id: f"{href}#id-{option_id}"}
+
+
+def approved_plan_links(
+    data: dict, data_path: Path, *, exclude: Container[str] = ()
+) -> dict[str, str]:
+    """Map the ids of the approved plan an implementation report executed to
+    their anchors on that plan's page.
+
+    An implementation report cites the plan's checklist rows (`VC-NNN`), its
+    invariants (`PI-NNN`) and its steps throughout — the 2026-09-05 dev-10626
+    stage-1 page had eight such bare mentions — while defining none of them.
+    `implementation.approvedPlanReference.planFile` names the plan (project-
+    or task-relative, reading copy or record); when that record exists, every
+    id it defines that this page does not links to the plan's page.
+    """
+    reference = (data.get("implementation") or {}).get("approvedPlanReference")
+    plan_file = reference.get("planFile") if isinstance(reference, dict) else None
+    if not isinstance(plan_file, str) or not plan_file.strip():
+        return {}
+    pointer = Path(plan_file.strip())
+    if not pointer.name.endswith(".data.json"):
+        pointer = final_report_data_path(pointer)
+    task_dir = _task_dir(data_path)
+    project_root = _project_root(data_path)
+    record = next(
+        (
+            root / pointer
+            for root in (project_root, task_dir)
+            if root is not None and (root / pointer).is_file()
+        ),
+        None,
+    )
+    if record is None:
+        return {}
+    try:
+        plan = load_owned_object(record, artifact="approved plan record")
+    except JsonBoundaryError:
+        return {}
+    from .common import anchor_index
+    from .view_models.implementation_planning import ANCHORED_FIELDS
+
+    page = html_view_path(record)
+    href = Path(os.path.relpath(page, data_path.resolve().parent)).as_posix()
+    return {
+        row_id: f"{href}#{anchor}"
+        for row_id, anchor in anchor_index(plan, ANCHORED_FIELDS).items()
+        if row_id not in exclude
+    }

package/runtime/python/okstra_ctl/report_html/models.py

@@ -66,11 +66,17 @@ class HumanReportView:
     template_name: str
     context: dict[str, object]
     figures: tuple[FigureModel, ...]
-    # Task-block fields this template leaves out of the HTML. Their rows still
-    # exist in the data and the markdown, so prose keeps citing their ids — but
-    # an anchor to a row this document never renders scrolls nowhere, which
-    # reads as a broken report rather than as a deliberate omission.
-    omitted_fields: tuple[str, ...] = ()
+    # Record fields (dotted paths from the record root, list steps implicit)
+    # whose rows this template anchors as `id-<row id>`. The anchor index is
+    # built from this declaration, not from a guess about the template: an id
+    # the record defines outside these paths lands in the evidence ledger, so
+    # a citation still resolves, and an id declared here without an anchor in
+    # the rendered page is what the index tests fail on.
+    anchored_fields: tuple[str, ...] = ()
+    # Fields whose rows repeat under every parent row (a direction's scope
+    # commitments). They anchor as `id-<parent>-<row>` inside the parent's
+    # card (`common.scoped_anchor_map`) and never take a page-global anchor.
+    scoped_anchor_fields: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True)