okstra 0.186.7 → 0.188.0

package/runtime/python/okstra_ctl/execution_identity.py

@@ -6,7 +6,7 @@ import json
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 from .domain.provider import HostModelBinding, ServedModelAttestation
 from .domain.worker_exec import WorkerWriteCapability
@@ -116,9 +116,6 @@ class Invocation:
     dispatch_kind: str
     round: int
     input_digest: str
-    write_policy: Mapping[str, Any]
-    write_policy_digest: str
-    write_enforcement: Mapping[str, Any]
 
     def to_payload(self) -> dict[str, Any]:
         return {
@@ -131,14 +128,19 @@ class Invocation:
             "dispatchKind": self.dispatch_kind,
             "round": self.round,
             "inputDigest": self.input_digest,
-            "writePolicy": dict(self.write_policy),
-            "writePolicyDigest": self.write_policy_digest,
-            "writeEnforcement": dict(self.write_enforcement),
         }
 
 
 @dataclass(frozen=True)
 class Attempt:
+    """One dispatch of a logical invocation, with the write contract it ran under.
+
+    쓰기 계약이 invocation 이 아니라 여기 있는 이유: 계약의 artifactPolicy 는 그
+    시도가 실제로 쓰는 프롬프트 파생 파일(`...-attempt-2.log` 등)을 이름으로
+    담는다. attempt 마다 다른 값이므로 attempt-불변인 invocation 행에 두면 같은
+    invocationRef 의 2회차가 `invocationRef drift` 로 거절된다.
+    """
+
     invocation_ref: str
     attempt: int
     started_at: str
@@ -148,6 +150,9 @@ class Attempt:
     error_path: str | None
     change_summary: Mapping[str, Any]
     evidence_seal_ref: str | None
+    write_policy: Mapping[str, Any]
+    write_policy_digest: str
+    write_enforcement: Mapping[str, Any]
 
     def to_payload(self) -> dict[str, Any]:
         return {
@@ -160,6 +165,9 @@ class Attempt:
             "errorPath": self.error_path,
             "changeSummary": dict(self.change_summary),
             "evidenceSealRef": self.evidence_seal_ref,
+            "writePolicy": dict(self.write_policy),
+            "writePolicyDigest": self.write_policy_digest,
+            "writeEnforcement": dict(self.write_enforcement),
         }
 
 
@@ -528,3 +536,88 @@ def _required_index_text(
 def _optional_text(value: object) -> str | None:
     text = str(value or "").strip()
     return text or None
+
+
+# ---- 무거운 모듈에서 옮겨 온 값 타입 ------------------------------------
+# 아래 둘은 dispatch_state(2,092줄) 와 mutation_recovery 안에 있었다. 값 하나가
+# 필요한 모듈이 그 모듈 전체를 끌어오게 되어, 반대 방향은 함수 본문 지연
+# import 로 밀려나 순환이 됐다. 원래 소유 모듈이 이름을 재노출한다.
+
+def build_dispatch_id(invocation_id: str, attempt: int) -> str:
+    """The only place Python assembles a dispatch id.
+
+    Two generators drifted: this module pinned the attempt to 1 while
+    `dispatch_core` used the real one, so a re-dispatch took the first attempt's
+    id, team-state kept the same row twice, and `validate-run` failed that run
+    with `agent dispatch ID is duplicated`.
+
+    Prose mirrors of this shape live outside Python, where no guard reaches
+    them: `prompts/lead/convergence.md`, `prompts/lead/report-writer.md`,
+    `prompts/lead/plan-body-verification.md` and the five
+    `adapters/hosts/*/relay.md` each spell an `--dispatch-id` argument out for
+    the lead. They agree with this function only because
+    `record_verified_agent_dispatch` records the first attempt and no other;
+    changing that convention has to change them too.
+    """
+    return f"{invocation_id}:attempt-{attempt}"
+
+
+@dataclass(frozen=True)
+class MutationRecoveryDecision:
+    recovery_ref: str
+    source_invocation_ref: str
+    source_attempt_ref: str
+    source_evidence_seal_ref: str | None
+    original_baseline_digest: str
+    terminal_source_diff_digest: str
+    terminal_git_chain_digest: str
+    verifier_role_execution_ref: str | None
+    verifier_invocation_ref: str | None
+    recovered_evidence_refs: tuple[Mapping[str, Any], ...]
+    recovered_out_of_plan_edits: tuple[Mapping[str, Any], ...]
+    unmet_obligations: tuple[str, ...]
+    decision: Literal["carry-forward", "reject", "cleanup-confirmed"]
+    reason: str = ""
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "recoveryRef": self.recovery_ref,
+            "sourceInvocationRef": self.source_invocation_ref,
+            "sourceAttemptRef": self.source_attempt_ref,
+            "sourceEvidenceSealRef": self.source_evidence_seal_ref,
+            "originalBaselineDigest": self.original_baseline_digest,
+            "terminalSourceDiffDigest": self.terminal_source_diff_digest,
+            "terminalGitChainDigest": self.terminal_git_chain_digest,
+            "verifierRoleExecutionRef": self.verifier_role_execution_ref,
+            "verifierInvocationRef": self.verifier_invocation_ref,
+            "recoveredEvidenceRefs": [dict(row) for row in self.recovered_evidence_refs],
+            "recoveredOutOfPlanEdits": [
+                dict(row) for row in self.recovered_out_of_plan_edits
+            ],
+            "unmetObligations": list(self.unmet_obligations),
+            "decision": self.decision,
+            "reason": self.reason,
+        }
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> "MutationRecoveryDecision":
+        return cls(
+            recovery_ref=str(payload["recoveryRef"]),
+            source_invocation_ref=str(payload["sourceInvocationRef"]),
+            source_attempt_ref=str(payload["sourceAttemptRef"]),
+            source_evidence_seal_ref=payload.get("sourceEvidenceSealRef"),
+            original_baseline_digest=str(payload.get("originalBaselineDigest") or ""),
+            terminal_source_diff_digest=str(
+                payload.get("terminalSourceDiffDigest") or ""
+            ),
+            terminal_git_chain_digest=str(payload.get("terminalGitChainDigest") or ""),
+            verifier_role_execution_ref=payload.get("verifierRoleExecutionRef"),
+            verifier_invocation_ref=payload.get("verifierInvocationRef"),
+            recovered_evidence_refs=tuple(payload.get("recoveredEvidenceRefs") or ()),
+            recovered_out_of_plan_edits=tuple(
+                payload.get("recoveredOutOfPlanEdits") or ()
+            ),
+            unmet_obligations=tuple(payload.get("unmetObligations") or ()),
+            decision=str(payload["decision"]),
+            reason=str(payload.get("reason") or ""),
+        )

package/runtime/python/okstra_ctl/execution_manifest.py

@@ -4,7 +4,8 @@ from __future__ import annotations
 import json
 import os
 import tempfile
-from collections.abc import Mapping, Sequence
+from collections.abc import Mapping, MutableMapping, Sequence
+from dataclasses import replace
 from functools import lru_cache
 from pathlib import Path
 from typing import Any, Callable
@@ -13,6 +14,7 @@ from .domain.provider import HostModelBinding, ServedModelAttestation
 from .domain.worker_exec import WorkerWriteCapability
 from .execution_identity import (
     Attempt,
+    build_dispatch_id,
     EXECUTION_IDENTITY_VERSION,
     ExecutionManifest,
     ExecutionManifestError,
@@ -62,10 +64,50 @@ def read_execution_manifest_view(
     surface = read_identity_surface(path, surface="run-manifest")
     if surface.legacy:
         return synthesize_v1_execution_view(surface.payload), surface.payload
+    hoist_legacy_attempt_write_contract(surface.payload)
     validate_execution_manifest_payload(surface.payload)
     return _execution_manifest_from_payload(surface.payload), surface.payload
 
 
+WRITE_CONTRACT_KEYS = ("writePolicy", "writePolicyDigest", "writeEnforcement")
+
+
+def hoist_legacy_attempt_write_contract(payload: Any) -> None:
+    """쓰기 계약이 invocation 에 실린 매니페스트를 attempt 소유로 옮긴다.
+
+    계약은 attempt 마다 다르다(`execution_identity.Attempt` 참고). 그 이전에
+    쓰인 매니페스트는 계약을 invocation 행에 담고 attempt 행에는 안 담으므로,
+    새 검증기가 보면 attempt 가 계약 없는 행이 된다 — 진행 중인 태스크가 전부
+    그 상태다. 여기서 옮겨 두면 다음 쓰기에서 파일 자체가 새 모양이 된다.
+
+    이 함수는 옮기기만 하고 값은 만들지 않는다. attempt 가 없는 invocation 의
+    계약은 버린다 — 그 값을 읽는 소비자는 없고, 디스패치가 attempt 를 열 때
+    다시 계산한다. 진행 중인 태스크가 모두 끝나면 통째로 지울 수 있다.
+    """
+    if not isinstance(payload, MutableMapping):
+        return
+    invocations = payload.get("invocations")
+    attempts = payload.get("attempts")
+    if not isinstance(invocations, list):
+        return
+    carried: dict[str, dict[str, Any]] = {}
+    for row in invocations:
+        if not isinstance(row, MutableMapping) or "writePolicy" not in row:
+            continue
+        contract = {key: row.pop(key) for key in WRITE_CONTRACT_KEYS if key in row}
+        ref = row.get("invocationRef")
+        if isinstance(ref, str):
+            carried[ref] = contract
+    if not carried or not isinstance(attempts, list):
+        return
+    for row in attempts:
+        if not isinstance(row, MutableMapping) or "writePolicy" in row:
+            continue
+        contract = carried.get(row.get("invocationRef"))
+        if contract:
+            row.update(contract)
+
+
 def write_execution_manifest(path: Path, manifest: ExecutionManifest) -> None:
     if manifest.legacy:
         raise ExecutionManifestError("cannot write a v1 memory view")
@@ -130,7 +172,7 @@ def _drift_detail(existing: Invocation, incoming: Invocation) -> str:
     before = existing.to_payload()
     after = incoming.to_payload()
     changed = sorted(
-        key for key in (*before, *after) if before.get(key) != after.get(key)
+        {key for key in (*before, *after) if before.get(key) != after.get(key)}
     )
     return ", ".join(changed) if changed else "(no field differs)"
 
@@ -349,10 +391,8 @@ def finish_attempt_mutation(
         if index is None:
             raise ExecutionManifestError("attempt to finish is unknown")
         existing = manifest.attempts[index]
-        closed = Attempt(
-            invocation_ref=invocation_ref,
-            attempt=attempt,
-            started_at=existing.started_at,
+        closed = replace(
+            existing,
             finished_at=finished_at,
             status=status,
             result_path=result_path,
@@ -422,7 +462,7 @@ def validate_execution_manifest_payload(payload: Mapping[str, Any]) -> None:
     invocations = _indexed_rows(payload["invocations"], "invocationRef")
     _validate_roles(payload, participants)
     _validate_invocations(participants, roles, invocations)
-    _validate_attempts(payload["attempts"], invocations)
+    _validate_attempts(payload["attempts"], invocations, participants, roles)
     _validate_seals_and_recoveries(payload)
 
 
@@ -613,10 +653,9 @@ def _validate_invocations(
         source = row.get("sourceInvocationRef")
         if source is not None and source not in invocations:
             raise ExecutionManifestError("invocation sourceInvocationRef is unknown")
-        _validate_invocation_write_contract(row, participants[participant_ref], roles[role_ref])
 
 
-def _validate_invocation_write_contract(
+def _validate_attempt_write_contract(
     row: Mapping[str, Any],
     participant: Mapping[str, Any],
     role: Mapping[str, Any],
@@ -624,21 +663,21 @@ def _validate_invocation_write_contract(
     policy = row.get("writePolicy")
     enforcement = row.get("writeEnforcement")
     if not isinstance(policy, Mapping) or not isinstance(enforcement, Mapping):
-        raise ExecutionManifestError("invocation write contract must be structured")
+        raise ExecutionManifestError("attempt write contract must be structured")
     try:
         validate_write_policy_payload(policy)
         validate_write_enforcement_payload(enforcement)
         expected_digest = write_policy_digest(policy)
     except WritePolicyError as exc:
-        raise ExecutionManifestError(f"invocation write contract: {exc}") from exc
+        raise ExecutionManifestError(f"attempt write contract: {exc}") from exc
     if row.get("writePolicyDigest") != expected_digest:
-        raise ExecutionManifestError("invocation writePolicyDigest does not match")
+        raise ExecutionManifestError("attempt writePolicyDigest does not match")
     source = policy.get("sourcePolicy")
     expected_mode = (
         "project-mutation" if role.get("role") == "implementer" else "source-readonly"
     )
     if not isinstance(source, Mapping) or source.get("mode") != expected_mode:
-        raise ExecutionManifestError("invocation sourcePolicy does not match role")
+        raise ExecutionManifestError("attempt sourcePolicy does not match role")
     git_policy = policy.get("gitPolicy")
     expected_git_mode = (
         "fast-forward-descendant-chain"
@@ -649,10 +688,10 @@ def _validate_invocation_write_contract(
         not isinstance(git_policy, Mapping)
         or git_policy.get("mode") != expected_git_mode
     ):
-        raise ExecutionManifestError("invocation gitPolicy does not match role")
+        raise ExecutionManifestError("attempt gitPolicy does not match role")
     if expected_mode == "source-readonly" and source.get("plannedPaths"):
         raise ExecutionManifestError(
-            "source-readonly invocation cannot declare planned paths"
+            "source-readonly attempt cannot declare planned paths"
         )
     _validate_enforcement_capability(enforcement, participant, role)
 
@@ -674,7 +713,7 @@ def _validate_enforcement_capability(
             )
         return
     if not isinstance(capability, Mapping):
-        raise ExecutionManifestError("worker invocation has no write capability")
+        raise ExecutionManifestError("worker attempt has no write capability")
     rank = {"none": 0, "directory-boundary": 1, "exact-path": 2}
     maximum = capability.get("maxBoundaryPrecision")
     actual = enforcement.get("boundaryPrecision")
@@ -685,6 +724,8 @@ def _validate_enforcement_capability(
 def _validate_attempts(
     rows: object,
     invocations: Mapping[str, Mapping[str, Any]],
+    participants: Mapping[str, Mapping[str, Any]],
+    roles: Mapping[str, Mapping[str, Any]],
 ) -> None:
     if not isinstance(rows, list):
         raise ExecutionManifestError("execution manifest attempts must be an array")
@@ -698,6 +739,12 @@ def _validate_attempts(
         attempt = row.get("attempt")
         if not isinstance(attempt, int) or attempt < 1:
             raise ExecutionManifestError("attempt number must be positive")
+        invocation = invocations[invocation_ref]
+        participant = participants.get(str(invocation.get("participantRef")))
+        role = roles.get(str(invocation.get("roleExecutionRef")))
+        if participant is None or role is None:
+            raise ExecutionManifestError("attempt references unknown execution identity")
+        _validate_attempt_write_contract(row, participant, role)
         attempts_by_invocation.setdefault(invocation_ref, []).append(attempt)
     for invocation_ref, values in attempts_by_invocation.items():
         if sorted(values) != list(range(1, len(values) + 1)):
@@ -710,7 +757,6 @@ def _validate_seals_and_recoveries(payload: Mapping[str, Any]) -> None:
     attempts = payload.get("attempts")
     if not isinstance(attempts, list):
         return
-    from .dispatch_state import build_dispatch_id
 
     attempt_refs = {
         build_dispatch_id(str(row.get("invocationRef")), int(row.get("attempt") or 0))
@@ -925,9 +971,6 @@ def _invocation_from_payload(row: Mapping[str, Any]) -> Invocation:
         dispatch_kind=str(row["dispatchKind"]),
         round=int(row["round"]),
         input_digest=str(row["inputDigest"]),
-        write_policy=dict(row["writePolicy"]),
-        write_policy_digest=str(row["writePolicyDigest"]),
-        write_enforcement=dict(row["writeEnforcement"]),
     )
 
 
@@ -942,6 +985,9 @@ def _attempt_from_payload(row: Mapping[str, Any]) -> Attempt:
         error_path=_optional_text(row.get("errorPath")),
         change_summary=dict(row["changeSummary"]),
         evidence_seal_ref=_optional_text(row.get("evidenceSealRef")),
+        write_policy=dict(row["writePolicy"]),
+        write_policy_digest=str(row["writePolicyDigest"]),
+        write_enforcement=dict(row["writeEnforcement"]),
     )
 
 
@@ -1223,6 +1269,7 @@ def _role_execution_index_from_runs(
         surface = read_identity_surface(resolved_path, surface="run-manifest")
         if surface.legacy:
             continue
+        hoist_legacy_attempt_write_contract(surface.payload)
         validate_execution_manifest_payload(surface.payload)
         run_ref = resolved_path.relative_to(resolved_reference_root).as_posix()
         rows.extend(

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -83,6 +83,10 @@ class MutationSnapshot:
 class MutationAuditResult:
     status: str
     changed_paths: tuple[str, ...]
+    # 추적되지 않는 채로 생기거나 바뀐 경로. 소스 변경이 아니라 명령이 남긴
+    # 산출물이라 판정을 막지 않는다 — 그래도 기록은 남긴다. 없던 일로 하면
+    # 워커가 워크트리에 무엇을 남겼는지 아무도 모른다.
+    untracked_paths: tuple[str, ...]
     source_changed: bool
     git_changed: bool
     attribution: str
@@ -96,6 +100,7 @@ class MutationAuditResult:
         return {
             "mutationStatus": self.status,
             "changedPaths": list(self.changed_paths),
+            "untrackedPaths": list(self.untracked_paths),
             "sourceChanged": self.source_changed,
             "gitChanged": self.git_changed,
             "attribution": self.attribution,
@@ -118,11 +123,13 @@ class ExecutionMutationAudit:
         rows = tuple(policies)
         root, artifact_root = _validate_batch(rows)
         generated = _generated_paths(rows)
-        file_digests = _content_snapshot(root, generated)
+        file_digests = _content_snapshot(root, generated | _ignored_paths(root))
         artifact_digests = (
             file_digests
             if artifact_root == root
-            else _content_snapshot(artifact_root, generated)
+            else _content_snapshot(
+                artifact_root, generated | _ignored_paths(artifact_root)
+            )
         )
         scratch_digests = _scratch_snapshot(rows)
         git_projection = _git_projection(root)
@@ -174,7 +181,9 @@ class ExecutionMutationAudit:
         scratch_changed = _changed_keys(
             before.scratch_digests, after.scratch_digests
         )
-        source_changes = _source_changes(changed, rows, before)
+        source_changes, untracked_changes = _split_tracked(
+            before.root, _source_changes(changed, rows, before)
+        )
         # Reported and, through `_retry_allowed`, load-bearing: a stat-cache
         # refresh must not read as "this worker touched Git" and must not
         # withhold the retry a worker that failed for another reason is owed.
@@ -203,6 +212,7 @@ class ExecutionMutationAudit:
         return MutationAuditResult(
             status=status,
             changed_paths=tuple(sorted(source_changes)),
+            untracked_paths=tuple(sorted(untracked_changes)),
             source_changed=bool(source_changes),
             git_changed=git_changed,
             attribution="batch-unattributed",
@@ -273,7 +283,9 @@ when a run produces the same evidence for it, not before.
 """
 
 
-def _content_snapshot(root: Path, generated: frozenset[str]) -> dict[str, str]:
+def _content_snapshot(root: Path, excluded: frozenset[str]) -> dict[str, str]:
+    """감사 대상 트리의 내용 다이제스트. `excluded` 는 정책이 선언한 생성
+    경로와 레포가 무시하는 경로를 합친 접두사 집합이다."""
     rows: dict[str, str] = {}
     for current, directories, filenames in os.walk(root, followlinks=False):
         current_path = Path(current)
@@ -284,7 +296,7 @@ def _content_snapshot(root: Path, generated: frozenset[str]) -> dict[str, str]:
             if (
                 name == ".git"
                 or name in _INSTALLED_DEPENDENCY_DIRS
-                or _excluded(relative_path, generated)
+                or _excluded(relative_path, excluded)
             ):
                 continue
             if path.is_symlink():
@@ -295,7 +307,7 @@ def _content_snapshot(root: Path, generated: frozenset[str]) -> dict[str, str]:
         for name in sorted(filenames):
             path = current_path / name
             relative = path.relative_to(root).as_posix()
-            if relative == ".git" or _excluded(Path(relative), generated):
+            if relative == ".git" or _excluded(Path(relative), excluded):
                 continue
             rows[relative] = _path_digest(path)
     return rows
@@ -327,9 +339,79 @@ def _path_digest(path: Path) -> str:
     return "sha256:" + hashlib.sha256(value).hexdigest()
 
 
-def _excluded(path: Path, generated: frozenset[str]) -> bool:
+def _excluded(path: Path, excluded: frozenset[str]) -> bool:
     relative = path.as_posix()
-    return any(relative == item or relative.startswith(item + "/") for item in generated)
+    return any(relative == item or relative.startswith(item + "/") for item in excluded)
+
+
+def _ignored_paths(root: Path) -> frozenset[str]:
+    """레포가 스스로 소스가 아니라고 선언한 경로.
+
+    감사는 워커가 *소스* 를 바꿨는지를 묻는다. `.gitignore` 는 그 레포에서
+    무엇이 소스가 아닌지에 대한 사람이 쓴 답이므로, 그 답을 여기서 다시 쓴다 —
+    okstra 가 파일 이름 목록을 따로 들고 있으면 레포마다 틀린다.
+
+    이 면제가 필요한 이유는 감사 창이 사람·OS 와 공유되기 때문이다. 실측
+    (2026-08-26, `fontsninja-nlpvibe` planning run 019~022): 완주한 워커의 결과가
+    버려진 10건 중 2건의 유발자가 Finder 가 쓴 `.DS_Store` 와 IDE 가 쓴
+    `.idea/workspace.xml` 이었다. 어느 쪽도 워커가 쓴 것이 아니고, 둘 다 그
+    레포의 무시 대상이다.
+
+    추적 중인 파일은 git 이 무시 대상으로 세지 않으므로 그대로 감사한다 —
+    나머지 8건처럼 사람이 추적 소스를 동시에 고친 경우는 이 면제가 가리지
+    않는다. git 이 없거나 레포가 아니면 빈 집합을 돌려 종전대로 전부 감사한다.
+    """
+    result = subprocess.run(
+        ["git", "-C", str(root), "ls-files", "-z", "--others", "--ignored",
+         "--exclude-standard", "--directory"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return frozenset()
+    # `--directory` 는 통째로 무시되는 디렉터리를 `name/` 한 줄로 접는다.
+    # `_excluded` 는 접두사로 대조하므로 그 꼬리 슬래시를 떼어 준다.
+    return frozenset(
+        entry.rstrip("/") for entry in result.stdout.split("\0") if entry
+    )
+
+
+def _tracked_paths(root: Path) -> frozenset[str] | None:
+    """이 레포가 추적 중인 파일. git 이 없거나 레포가 아니면 ``None``.
+
+    `source-readonly` 가 묻는 것은 워커가 **소스** 를 바꿨는가이다. 추적 중인
+    파일의 변경이 그 답이다. 추적되지 않는 새 파일은 소스의 변경이 아니라
+    명령이 남긴 산출물이고, 그 둘을 한 등급으로 묶으면 규칙을 만족시킬 수 있는
+    실물 조건이 없어진다 — 프로필은 검증자에게 승인 계획의 Tier 1 명령을 독립
+    재실행하라고 요구하는데, 실제 프로젝트의 그 명령들은 빌드 산출물과 평가
+    리포트를 쓴다. 실측(2026-08-26, `fontsninja-nlpvibe` final-verification
+    run 005): 계획대로 게이트를 돌린 검증자 셋이 전부
+    `readonly source changed [eval/reports/clip-baseline.{html,json}]` 로
+    버려졌다. 두 파일은 추적되지 않는 생성 산출물이고, 계획이 승인 시점에
+    적어 둔 명령이 만든 것이다.
+
+    ``None`` 은 "판정할 수 없음" 이다 — 그때는 좁히지 않고 종전대로 전부
+    소스 변경으로 본다. 추적 여부를 모르면서 면제하면 진짜 소스 변경을 놓친다.
+    """
+    result = subprocess.run(
+        ["git", "-C", str(root), "ls-files", "-z"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return None
+    return frozenset(entry for entry in result.stdout.split("\0") if entry)
+
+
+def _split_tracked(root: Path, changes: set[str]) -> tuple[set[str], set[str]]:
+    """``(추적 중인 소스 변경, 추적되지 않는 산출물)``."""
+    tracked = _tracked_paths(root)
+    if tracked is None:
+        return set(changes), set()
+    untracked = {path for path in changes if path not in tracked}
+    return changes - untracked, untracked
 
 
 def _generated_paths(policies: Sequence[WritePolicy]) -> frozenset[str]:

package/runtime/python/okstra_ctl/final_report_paths.py

@@ -119,3 +119,20 @@ def translation_sidecar_path(data_path: Path, lang: str) -> Path:
     overwrite it.
     """
     return data_path.with_name(f"{_stem(data_path)}.i18n.{lang}.json")
+
+
+def sidecar_source_rel(path: Path) -> str:
+    """사이드카 프론트매터가 `source-report` / `source-data` 에 적는 경로.
+
+    기준점은 **태스크 루트**다 (`runs/<task-type>/reports/...`). 사이드카를
+    읽는 쪽은 리포트를 태스크 루트에서 되짚으므로
+    (`implementation_direction._relative_source`), 다른 기준으로 적힌 값은
+    같은 파일을 가리켜도 대조에 실패한다.
+
+    HTML 열람본을 렌더할 때 넘기는 `--source-report` 와 CLI 가 직접 쓰는
+    사이드카가 이 함수 하나를 공유한다. 둘이 각자 계산하던 동안 HTML Export 는
+    프로젝트 루트 기준을 적었고, 그 사이드카는 방향 선택 게이트를 통과할 수
+    없었다.
+    """
+    indices = [index for index, part in enumerate(path.parts) if part == "runs"]
+    return Path(*path.parts[indices[-1]:]).as_posix() if indices else path.name