okstra 0.189.0 → 0.189.2

package/runtime/python/okstra_ctl/group_context.py

@@ -0,0 +1,223 @@
+"""task-group 맥락 문서 — 그룹의 모든 task 가 공유하는 배경을 워커 입력에 싣는다.
+
+`.okstra/briefs/<task-group>/group-context.md` 한 파일이 그룹이 존재하는 이유,
+성과 척도, 그룹 전체 금지선, 티켓 간 관계를 담는다. 브리프는 티켓 하나의 범위를
+말하므로 그룹 단위의 "왜" 는 어느 브리프에도 없다(2026-09-04 실측, fontsninja
+`cache` 그룹: 브리프 15개 중 가용성 사고를 말한 것이 0개였고 option-selection 이
+분모를 페이지당 요청 수로 바꿔 판단했다).
+
+세 소비자가 이 모듈 하나를 쓴다.
+
+- `okstra group-context init` — 템플릿에서 뼈대를 쓴다(있으면 거절).
+- `validators/validate-brief.py` — 프론트매터 `type: group-context` 를 만나면
+  `validate_group_context` 로 검사한다.
+- prepare(`run.py`) — 파일이 있으면 같은 검사를 통과해야 진행하고, 통과하면
+  `instruction-set/task-group-context.md` 로 복사해 analysis packet 에 싣는다.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import re
+import sys
+from pathlib import Path
+
+from .brief_frontmatter import read_brief_frontmatter
+from .ids import slugify_task_segment
+from .paths import find_asset_root
+
+GROUP_CONTEXT_FILENAME = "group-context.md"
+GROUP_CONTEXT_TYPE = "group-context"
+GROUP_CONTEXT_GENERATOR = "okstra-brief-gen"
+INSTRUCTION_SET_FILENAME = "task-group-context.md"
+REQUIRED_FRONTMATTER_KEYS = ("type", "task-group", "created", "generator")
+SECTIONS = (
+    "Why This Group Exists",
+    "Definition of Better",
+    "Group-Wide Constraints",
+    "Ticket Relations",
+)
+# 나머지 두 절은 `_(none)_` 이 허용된다 — 금지선이나 관계가 없는 그룹도 있다.
+MUST_BE_FILLED = SECTIONS[:2]
+TEMPLATE_RELATIVE = ("templates", "reports", "group-context.template.md")
+
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+_NONE_MARKERS = {"_(none)_", ""}
+
+
+def briefs_root(project_root: Path) -> Path:
+    return Path(project_root) / ".okstra" / "briefs"
+
+
+def group_context_file(project_root: Path, task_group: str) -> Path:
+    """그룹 맥락 문서의 정본 경로. 디렉터리는 브리프와 같은 slug 를 쓴다."""
+    return briefs_root(project_root) / slugify_task_segment(task_group) / GROUP_CONTEXT_FILENAME
+
+
+def is_group_context_file(path: Path) -> bool:
+    return path.name == GROUP_CONTEXT_FILENAME
+
+
+def validate_group_context(path: Path, root: Path) -> list[str]:
+    """결함 목록. 비어 있으면 통과. 결함마다 사람이 고칠 자리를 이름한다."""
+    text = _HTML_COMMENT_RE.sub("", path.read_text(encoding="utf-8"))
+    errors: list[str] = []
+    frontmatter = read_brief_frontmatter(path)
+    if not frontmatter:
+        return ["frontmatter: missing or malformed (a `---` block must open line 1)"]
+    missing = [key for key in REQUIRED_FRONTMATTER_KEYS if key not in frontmatter]
+    if missing:
+        errors.append(f"frontmatter missing keys: {missing}")
+    if frontmatter.get("type") != GROUP_CONTEXT_TYPE:
+        errors.append(
+            f"frontmatter type must be {GROUP_CONTEXT_TYPE!r}, got {frontmatter.get('type')!r}"
+        )
+    if frontmatter.get("generator") != GROUP_CONTEXT_GENERATOR:
+        errors.append(
+            f"frontmatter generator must be {GROUP_CONTEXT_GENERATOR!r}, "
+            f"got {frontmatter.get('generator')!r}"
+        )
+    errors.extend(_path_errors(path, root, frontmatter.get("task-group", "")))
+    errors.extend(_section_errors(text))
+    return errors
+
+
+def _path_errors(path: Path, root: Path, task_group: str) -> list[str]:
+    errors: list[str] = []
+    if path.name != GROUP_CONTEXT_FILENAME:
+        errors.append(f"file must be named {GROUP_CONTEXT_FILENAME!r}, got {path.name!r}")
+    try:
+        relative = path.resolve().relative_to(Path(root).resolve())
+    except ValueError:
+        return errors + [f"file is not under the briefs root {root}"]
+    if len(relative.parts) != 2:
+        errors.append(
+            "file must sit directly under its task-group directory "
+            f"(`<briefs>/<task-group>/{GROUP_CONTEXT_FILENAME}`), got {relative}"
+        )
+        return errors
+    expected = slugify_task_segment(task_group)
+    if task_group and relative.parts[0] != expected:
+        errors.append(
+            f"task-group directory segment {relative.parts[0]!r} does not match the "
+            f"slugified frontmatter task-group {expected!r}"
+        )
+    return errors
+
+
+def _section_errors(text: str) -> list[str]:
+    bodies = _section_bodies(text)
+    errors: list[str] = []
+    for heading in SECTIONS:
+        if heading not in bodies:
+            errors.append(f"missing section `## {heading}`")
+            continue
+        lines = [line.strip() for line in bodies[heading].splitlines() if line.strip()]
+        placeholders = [line for line in lines if _is_template_placeholder(line)]
+        if placeholders:
+            errors.append(
+                f"section `## {heading}` still carries a template placeholder "
+                f"({placeholders[0][:40]}...); fill it or delete the file"
+            )
+            continue
+        if heading in MUST_BE_FILLED and all(line in _NONE_MARKERS for line in lines):
+            errors.append(f"section `## {heading}` must be filled; `_(none)_` is not accepted here")
+    return errors
+
+
+def _section_bodies(text: str) -> dict[str, str]:
+    """`## ` 제목 → 본문. `## ` 만 절을 닫는다(validate-brief `section_body` 와 같은 규칙)."""
+    bodies: dict[str, str] = {}
+    current: str | None = None
+    buffer: list[str] = []
+    for line in text.splitlines():
+        if line.startswith("## "):
+            if current is not None:
+                bodies[current] = "\n".join(buffer)
+            current = line[3:].strip()
+            buffer = []
+        elif current is not None:
+            buffer.append(line)
+    if current is not None:
+        bodies[current] = "\n".join(buffer)
+    return bodies
+
+
+def _is_template_placeholder(line: str) -> bool:
+    bare = line.lstrip("-").strip()
+    return bare.startswith("<") and bare.endswith(">")
+
+
+def render_skeleton(task_group: str, created: str) -> str:
+    root = find_asset_root(TEMPLATE_RELATIVE)
+    if root is None:
+        raise FileNotFoundError(
+            "group-context template not found in any okstra asset root: "
+            + "/".join(TEMPLATE_RELATIVE)
+        )
+    template = root.joinpath(*TEMPLATE_RELATIVE).read_text(encoding="utf-8")
+    slug = slugify_task_segment(task_group)
+    return template.replace("<task-group>", slug).replace("<YYYY-MM-DD>", created)
+
+
+def init_group_context(project_root: Path, task_group: str, *, today: dt.date) -> Path:
+    """뼈대를 쓴다. 이미 있으면 `FileExistsError` — 채운 문서를 덮어쓰지 않는다."""
+    target = group_context_file(project_root, task_group)
+    if target.exists():
+        raise FileExistsError(str(target))
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(render_skeleton(task_group, today.isoformat()), encoding="utf-8")
+    return target
+
+
+def _init_command(args: argparse.Namespace) -> int:
+    project_root = Path(args.project_root).resolve()
+    try:
+        target = init_group_context(project_root, args.task_group, today=dt.date.today())
+    except FileExistsError as exc:
+        print(
+            f"group-context: already exists: {exc}\n"
+            "Edit that file instead; delete it first if you want a fresh skeleton.",
+            file=sys.stderr,
+        )
+        return 2
+    print(f"group context skeleton: {target}")
+    print("Fill these sections (one `<...>` placeholder line each):")
+    for heading in SECTIONS:
+        note = "required" if heading in MUST_BE_FILLED else "`_(none)_` allowed"
+        print(f"  - ## {heading}  ({note})")
+    print(
+        "Validate with: python3 ~/.okstra/lib/validators/validate-brief.py "
+        f"{target} --briefs-root {briefs_root(project_root)}"
+    )
+    print(
+        "Every run of task-group "
+        f"`{slugify_task_segment(args.task_group)}` refuses to prepare while a placeholder "
+        "line remains; delete the file if the group needs no context."
+    )
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okstra group-context",
+        description=(
+            "Create the task-group context skeleton beside the group's briefs "
+            "(`.okstra/briefs/<task-group>/group-context.md`)."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    init = sub.add_parser("init", help="write the skeleton from the template; refuses an existing file")
+    init.add_argument("--project-root", required=True, help="project root that holds `.okstra/`")
+    init.add_argument("--task-group", required=True, help="task-group name; slugified for the directory")
+    init.set_defaults(func=_init_command)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/runtime/python/okstra_ctl/implementation_options.py

@@ -244,14 +244,49 @@ def _validate_option_feasibility(
         errors.append(f"{option_id} safetyBlockers must be empty")
     if require_valid and option.get("unresolvedFeasibilityFacts"):
         errors.append(f"{option_id} unresolvedFeasibilityFacts must be empty")
+    copied = _copied_votes(votes)
+    for first, second in copied:
+        errors.append(
+            f"{option_id} feasibilityVotes for {first} and {second} are identical; "
+            "each vote carries that analyser's own rationale and counterevidence"
+        )
     return (
         all_participated
         and feasible >= MIN_FEASIBLE_VOTES
         and not option.get("safetyBlockers")
         and not option.get("unresolvedFeasibilityFacts")
+        and not copied
     )
 
 
+def _copied_votes(votes: Sequence[object]) -> list[tuple[str, str]]:
+    """Pairs of analysers whose votes share one rationale and counterevidence.
+
+    A vote is that analyser's own finding. The writer synthesizes the row from
+    each result, and a run (2026-09-04, dev-10626) shipped three votes whose
+    sentences matched to the letter — one worker's text copied under the other
+    two names — so the votes said nothing a single vote did not. `uncertain`
+    votes are exempt: two analysers that never evaluated a candidate say so in
+    the same words legitimately.
+    """
+    seen: dict[tuple[str, str], str] = {}
+    copied: list[tuple[str, str]] = []
+    for vote in votes:
+        if not isinstance(vote, Mapping) or vote.get("verdict") == "uncertain":
+            continue
+        key = (
+            str(vote.get("rationale") or "").strip(),
+            str(vote.get("counterevidence") or "").strip(),
+        )
+        if not any(key):
+            continue
+        worker = str(vote.get("worker") or "?")
+        first = seen.setdefault(key, worker)
+        if first != worker:
+            copied.append((first, worker))
+    return copied
+
+
 def _validate_candidate(
     option: Mapping[str, object],
     original_ids: Sequence[str],

package/runtime/python/okstra_ctl/model_io/renderers.py

@@ -20,6 +20,7 @@ from ..fixed_text import line as _line, scalar as _value
 from ..json_boundary import JsonBoundaryError, load_owned_object
 from ..paths import okstra_home
 from ..recap import assemble_recap
+from ..timeline_runs import current_run_facts
 from ..worker_artifacts import worker_provider_id
 from .lines import (
     _assignment_line,
@@ -51,7 +52,7 @@ from .references import (
 )
 
 
-def _latest_timeline_run(manifest_path: Path) -> Mapping[str, Any]:
+def _latest_timeline_run(project_root: Path, manifest_path: Path) -> Mapping[str, Any]:
     timeline_path = manifest_path.parent / "history" / "timeline.json"
     if not timeline_path.is_file():
         return {}
@@ -59,10 +60,11 @@ def _latest_timeline_run(manifest_path: Path) -> Mapping[str, Any]:
     runs = timeline.get("runs")
     if not isinstance(runs, list):
         return {}
-    return next(
+    latest = next(
         (run for run in reversed(runs) if isinstance(run, Mapping)),
-        {},
+        None,
     )
+    return current_run_facts(project_root, latest) if latest is not None else {}
 
 
 def _overview_rows(
@@ -79,15 +81,18 @@ def _overview_rows(
             project_root, manifest_path, expected_task_key=task_key, artifact="task catalog"
         )
         manifest = load_owned_object(manifest_path, artifact="task manifest")
-        latest_run = _latest_timeline_run(manifest_path)
+        latest_run = _latest_timeline_run(project_root, manifest_path)
         _, group, _ = parse_task_key(task_key)
         workflow = _mapping(manifest, "workflow")
         next_phase = _mapping(workflow, "nextRecommendedPhase")
+        # task 단위 현재 사실은 task-manifest 가 권위다(validate-run 이 run 종료
+        # 시 거기에 쓴다). timeline 의 마지막 run 은 task-manifest 에 그 필드가
+        # 없을 때의 폴백이고, 그 값도 run-manifest 로 덮어쓴 현재 사실이다.
         row = {
             "taskKey": task_key,
             "taskGroup": manifest.get("taskGroup") or task.get("taskGroup") or group,
             "taskType": manifest.get("taskType") or latest_run.get("taskType"),
-            "latestRunStatus": latest_run.get("status") or manifest.get("latestRunStatus"),
+            "latestRunStatus": manifest.get("latestRunStatus") or latest_run.get("status"),
             "updatedAt": manifest.get("updatedAt") or task.get("updatedAt") or latest_run.get("runTimestamp"),
             "latestRunManifestPath": pointer.get("latestRunManifestPath"),
             "workCategory": manifest.get("workCategory"),
@@ -98,7 +103,7 @@ def _overview_rows(
             "nextPhaseStatus": next_phase.get("status"),
             "nextPhaseRationale": next_phase.get("rationale"),
             "awaitingApproval": workflow.get("awaitingApproval"),
-            "latestReportRecordPath": latest_run.get("reportRecordPath") or manifest.get("latestReportRecordPath"),
+            "latestReportRecordPath": manifest.get("latestReportRecordPath") or latest_run.get("reportRecordPath"),
             "latestResumeCommandPath": latest_run.get("resumeCommandPath") or manifest.get("latestResumeCommandPath"),
             "workStatus": manifest.get("workStatus"),
             "lastRun": latest_run.get("runTimestamp"),
@@ -336,7 +341,7 @@ def render_history_input(
         )
     manifest, runs = _selected_task_data(project_root, task_ref)
     blocks: list[str] = []
-    for index, run in enumerate(runs, 1):
+    for index, run in enumerate((current_run_facts(project_root, run) for run in runs), 1):
         blocks.append(
             f"\n## Run {index}\n\n"
             + _line("Run timestamp", run.get("runTimestamp"))

package/runtime/python/okstra_ctl/recap.py

@@ -22,6 +22,7 @@ from okstra_project import read_task_key
 from okstra_ctl.run_context import dir_flock
 from okstra_ctl.final_report_paths import timeline_report_record_rel
 from okstra_ctl.task_target import resolve_task_root, project_rel
+from okstra_ctl.timeline_runs import current_run_facts
 
 NOTE_KINDS = ("verification-evidence", "decision-draft", "analysis-note")
 
@@ -97,7 +98,12 @@ def rerun_readiness(project_root: Path, runs: list[dict]) -> dict | None:
 
 
 def assemble_recap(task_root: Path, project_root: Path) -> dict:
-    runs = _load_timeline(task_root)
+    # timeline 항목의 status / workflowSnapshot / reportRecordPath 는 준비 시점
+    # 값이다. 각 run 의 종료 상태는 그 run 의 run-manifest 에서 덮어쓴다.
+    runs = [
+        current_run_facts(project_root, run) if isinstance(run, dict) else run
+        for run in _load_timeline(task_root)
+    ]
     transitions = []
     prev_phase = ""
     latest_states: dict = {}

package/runtime/python/okstra_ctl/render.py

@@ -1962,6 +1962,19 @@ def _initialize_report_ledgers(ctx: Mapping[str, Any], manifest: Mapping[str, An
             "activeClarifications": [],
             "carriedDecisions": [],
         })
+        # 이월 결정은 여기서 심는다. 리드가 손으로 carry 하던 동안 대부분의
+        # run 이 빈 채로 갔고, 리포트는 행 없는 C-NNN 을 인용했다.
+        response_value = str(ctx.get("CLARIFICATION_RESPONSE_PATH") or "")
+        if response_value:
+            from .approval_decisions import seed_carried_decisions
+
+            seed_carried_decisions(
+                approval_path,
+                Path(response_value),
+                source_run_ref=str(
+                    ctx.get("CLARIFICATION_RESPONSE_RELATIVE_PATH") or response_value
+                ),
+            )
     activity_value = str(ctx.get("LEAD_EVENTS_PATH") or "")
     activity_path = Path(activity_value)
     if activity_value and not activity_path.is_file():

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

@@ -199,6 +199,49 @@ 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 anchor_index(data: dict, omitted_fields: tuple[str, ...] = ()) -> dict[str, str]:
     """Map every row a reader can reach to the anchor name that lands on it.
 
@@ -211,15 +254,28 @@ def anchor_index(data: dict, omitted_fields: tuple[str, ...] = ()) -> dict[str,
     It stops there. `summary` is the AI-facing digest and
     `analysisCommon.scope` describes the analysis target rather than listing
     rows; neither renders, so a link to one would land nowhere.
+
+    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
+    an element id with the clarification of that number — so they carry that
+    name here, and a legacy row whose id a clarification already owns keeps
+    pointing at the clarification.
     """
-    found = _own_section_ids(data, omitted_fields) | set(
-        evidence_index(data, omitted_fields)
-    )
-    return {
+    found = (
+        _own_section_ids(data, omitted_fields)
+        - _shared_task_block_ids(data, omitted_fields)
+    ) | set(evidence_index(data, omitted_fields))
+    index = {
         row_id: f"id-{row_id}"
         for row_id in sorted(found)
         if isinstance(row_id, str) and _anchorable(row_id)
     }
+    for block in ("consensus", "differences"):
+        for row in _dig(data, ("crossVerification", block)):
+            row_id = row.get("id") if isinstance(row, dict) else None
+            if isinstance(row_id, str) and _anchorable(row_id) and row_id not in index:
+                index[row_id] = f"id-xv-{row_id}"
+    return index
 
 
 def analysis_review_ids(data: dict) -> tuple[str, ...]:

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

@@ -0,0 +1,137 @@
+"""Rows and links for the ids a report cites but does not define.
+
+The human HTML renders from ``data.json``, and every id the record defines
+gets an anchor there. Two id families are cited on almost every page and
+defined on none of them:
+
+* the brief's end-state ids (``EB-001``, ``PB-001``, ``EO-001``) — the
+  denominator of every requirement-coverage table. The sentence behind each
+  id exists only in the task brief; no phase repeats it.
+* the clarification ids a previous run settled (``C-005``) — the record points
+  at that run through ``clarificationCarryIn.sourceFile`` and cites the ids
+  in its prose, but only the lead's ``carriedDecisions`` put a row for them
+  in this record, and a run that carried none leaves the ids as dead text.
+
+Both homes are okstra-owned files inside the same task directory, so the
+renderer follows the two pointers the run pinned — ``taskBriefPath`` is
+always ``<task>/instruction-set/task-brief.md`` (``path_hints.py``), and the
+carry-in record is named by the report itself — and only to give a cited id
+a place to land. Neither read is a precondition: a missing or unreadable file
+yields no rows and no links, never a render failure.
+"""
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Container
+from pathlib import 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
+
+_USER_RESPONSE_RE = re.compile(r"^user-response-(?P<task_type>.+)-(?P<seq>\d{3,})\.md$")
+
+
+def _task_dir(data_path: Path) -> Path | None:
+    """The task directory a report lives under, or None outside the layout.
+
+    A report sits at ``<task>/runs/<type>/reports/`` — or one level deeper
+    for an implementation stage, ``runs/implementation/stage-<N>/reports/`` —
+    so the nearest ``runs`` ancestor names the task directory either way.
+    """
+    for parent in data_path.resolve().parents:
+        if parent.name == "runs":
+            return parent.parent
+    return None
+
+
+def _project_root(data_path: Path) -> Path | None:
+    """The project root, or None when the report is not under ``.okstra/``.
+
+    Every okstra-owned artifact lives under ``<PROJECT_ROOT>/.okstra/``, and a
+    carry-in ``sourceFile`` is recorded relative to that root.
+    """
+    for parent in data_path.resolve().parents:
+        if parent.name == ".okstra":
+            return parent.parent
+    return None
+
+
+def brief_end_states(data_path: Path) -> list[dict[str, str]]:
+    """The brief's end-state rows, in brief order, as template-ready dicts."""
+    task_dir = _task_dir(data_path)
+    if task_dir is None:
+        return []
+    brief = task_dir / "instruction-set" / "task-brief.md"
+    return [
+        {"id": row.id, "section": row.section, "statement": row.statement}
+        for row in brief_end_state_rows(brief)
+    ]
+
+
+def _carry_in_record(source: Path) -> Path | None:
+    """The report record a carry-in pointer resolves to.
+
+    The pointer names either the prior run's record itself or the
+    user-responses sidecar exported from that run's page; the sidecar sits in
+    ``runs/<type>/user-responses/`` beside the run's ``reports/`` directory
+    and carries the run's task type and seq in its name.
+    """
+    if source.name.endswith(".data.json"):
+        return source
+    match = _USER_RESPONSE_RE.match(source.name)
+    if match is None or source.parent.name != "user-responses":
+        return None
+    task_type, seq = match.group("task_type"), match.group("seq")
+    return source.parent.parent / "reports" / f"final-report-{task_type}-{seq}.data.json"
+
+
+def _clarification_ids(record: Path) -> list[str]:
+    """The clarification ids the carry-in record defines, or none.
+
+    The record is read through the owned-JSON boundary like every report
+    record; a record that fails it is a record this page cannot link into,
+    not a reason to refuse this page.
+    """
+    try:
+        payload = load_owned_object(record, artifact="carry-in report record")
+    except JsonBoundaryError:
+        return []
+    rows = payload.get("clarificationItems")
+    if not isinstance(rows, list):
+        return []
+    return [
+        row["id"]
+        for row in rows
+        if isinstance(row, dict) and isinstance(row.get("id"), str) and row["id"]
+    ]
+
+
+def carry_in_links(
+    data: dict, data_path: Path, *, exclude: Container[str] = ()
+) -> dict[str, str]:
+    """Map each clarification id the carry-in record defines to its anchor
+    on that record's HTML page, as an href relative to this report's page.
+
+    ``exclude`` names the ids this document already anchors — a row the lead
+    did carry keeps its in-page link, and the prior run's page is only for
+    the ids this page has no row for.
+    """
+    carry_in = data.get("clarificationCarryIn")
+    source_value = carry_in.get("sourceFile") if isinstance(carry_in, dict) else None
+    if not isinstance(source_value, str) or not source_value.strip():
+        return {}
+    root = _project_root(data_path)
+    if root is None:
+        return {}
+    record = _carry_in_record(root / source_value.strip())
+    if record is None or not record.is_file():
+        return {}
+    page = html_view_path(record)
+    href = Path(os.path.relpath(page, data_path.resolve().parent)).as_posix()
+    return {
+        cid: f"{href}#id-{cid}"
+        for cid in _clarification_ids(record)
+        if cid not in exclude
+    }