okstra 0.186.7 → 0.187.0

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

package/runtime/python/okstra_ctl/final_report_schema.py

@@ -4,7 +4,8 @@ This is a deliberately narrow JSON Schema implementation that supports
 exactly the keywords used by ``schemas/final-report-v2.0.schema.json``:
 
   type, required, properties, additionalProperties, enum, const, pattern,
-  minLength, minItems, maxItems, uniqueItems, items, minimum, maximum, $ref ($defs),
+  minLength, minItems, maxItems, uniqueItems, prefixItems, items, minimum, maximum,
+  boolean schemas, $ref ($defs),
   oneOf, allOf, if/then/else, contains, minContains, maxContains, not
 
 We do NOT depend on the ``jsonschema`` PyPI package because its
@@ -102,12 +103,32 @@ def _resolve_ref(ref: str, root: dict) -> dict:
     return node
 
 
+_BRANCH_ROOT_PREFIX = f"{_format_path(())}: "
+"""분기 probe 의 경로는 분기 루트 기준이라 `<root>:` 가 매 줄 반복된다.
+바깥 오류가 이미 실제 경로를 싣고 있으므로 안쪽에서는 뗀다."""
+
+_BRANCH_ERROR_LIMIT = 8
+"""분기 하나당 실을 오류 수. 나머지는 개수만 적는다 — 열세 개 짜리 목록도
+앞의 여덟이면 어느 블록을 안 썼는지 판정된다."""
+
+
 class _Validator:
     def __init__(self, root_schema: dict):
         self.root = root_schema
         self.errors: list[str] = []
 
-    def validate(self, instance: Any, schema: dict, path: tuple[str | int, ...]) -> None:
+    def validate(
+        self,
+        instance: Any,
+        schema: dict | bool,
+        path: tuple[str | int, ...],
+    ) -> None:
+        if schema is True:
+            return
+        if schema is False:
+            self._err(path, "value is not allowed by the false schema")
+            return
+
         # Handle $ref first — everything else is composed under the
         # resolved schema.
         if "$ref" in schema:
@@ -196,9 +217,14 @@ class _Validator:
             for previous in instance[:index]
         ):
             self._err(path, "array items are not unique")
+        prefix_items = schema.get("prefixItems") or []
+        for i, item_schema in enumerate(prefix_items[: len(instance)]):
+            self.validate(instance[i], item_schema, path + (i,))
+
         items = schema.get("items")
         if items is not None:
-            for i, value in enumerate(instance):
+            remaining_items = instance[len(prefix_items) :]
+            for i, value in enumerate(remaining_items, start=len(prefix_items)):
                 self.validate(value, items, path + (i,))
         contains = schema.get("contains")
         if contains is not None:
@@ -229,30 +255,78 @@ class _Validator:
             if else_schema is not None:
                 self.validate(instance, else_schema, path)
 
-    def _validate_one_of(self, instance: Any, branches: list[dict], path: tuple[str | int, ...]) -> None:
-        matches = sum(1 for b in branches if self._matches(instance, b))
-        if matches != 1:
+    def _validate_one_of(
+        self,
+        instance: Any,
+        branches: list[dict | bool],
+        path: tuple[str | int, ...],
+    ) -> None:
+        per_branch = [self._branch_errors(instance, branch) for branch in branches]
+        matches = sum(1 for errors in per_branch if not errors)
+        if matches == 1:
+            return
+        if matches == 0:
             self._err(
                 path,
-                f"oneOf matched {matches} branches (expected exactly 1); "
-                f"branches: {[self._summarise(b) for b in branches]}",
+                "oneOf matched no branch (expected exactly 1); "
+                + self._branch_diagnosis(per_branch),
             )
+            return
+        self._err(
+            path,
+            f"oneOf matched {matches} branches (expected exactly 1); "
+            f"branches: {[self._summarise(b) for b in branches]}",
+        )
+
+    @staticmethod
+    def _branch_diagnosis(per_branch: list[list[str]]) -> str:
+        """왜 각 분기가 안 맞았는지. 분기 스키마를 인라인하지 않는다.
 
-    def _validate_not(self, instance: Any, sub_schema: dict, path: tuple[str | int, ...]) -> None:
+        종전에는 `oneOf` 실패가 분기 스키마 두 개를 통째로 찍었다. 1,500자
+        한 줄이면서 **어느 필드가 빠졌는지는 말하지 않아서**, 읽는 사람이
+        narrative 의 키 목록을 뽑아 스키마의 `required` 와 손으로 대조해야
+        했다. 분기가 실제로 낸 오류가 그 대조의 답이므로 그것을 싣는다.
+        """
+        parts: list[str] = []
+        for index, errors in enumerate(per_branch, start=1):
+            shown = [
+                error[len(_BRANCH_ROOT_PREFIX):]
+                if error.startswith(_BRANCH_ROOT_PREFIX)
+                else error
+                for error in errors[:_BRANCH_ERROR_LIMIT]
+            ]
+            remainder = len(errors) - len(shown)
+            if remainder > 0:
+                shown.append(f"(+{remainder} more)")
+            parts.append(f"branch {index}: " + "; ".join(shown))
+        return " | ".join(parts)
+
+    def _branch_errors(self, instance: Any, schema: dict | bool) -> list[str]:
+        probe = _Validator(self.root)
+        probe.validate(instance, schema, ())
+        return probe.errors
+
+    def _validate_not(
+        self,
+        instance: Any,
+        sub_schema: dict | bool,
+        path: tuple[str | int, ...],
+    ) -> None:
         if self._matches(instance, sub_schema):
             self._err(path, f"value must NOT match {self._summarise(sub_schema)}")
 
-    def _matches(self, instance: Any, schema: dict) -> bool:
-        """Cheap 'does this validate' probe used by if/oneOf/contains.
+    def _matches(self, instance: Any, schema: dict | bool) -> bool:
+        """Cheap 'does this validate' probe used by if/contains.
         Returns True iff the sub-schema produces zero errors. Does not
-        mutate ``self.errors``.
+        mutate ``self.errors``. `oneOf` keeps the errors themselves
+        (`_branch_errors`) because it has to say why every branch failed.
         """
-        probe = _Validator(self.root)
-        probe.validate(instance, schema, ())
-        return not probe.errors
+        return not self._branch_errors(instance, schema)
 
     @staticmethod
-    def _summarise(schema: dict) -> str:
+    def _summarise(schema: dict | bool) -> str:
+        if isinstance(schema, bool):
+            return str(schema).lower()
         keys = sorted(k for k in schema if k not in ("description", "$comment"))
         return "{" + ", ".join(f"{k}={schema[k]!r}" for k in keys[:3]) + "}"
 

package/runtime/python/okstra_ctl/git_reconcile.py

@@ -273,12 +273,32 @@ def _items_as_json(items: List[StaleItem]) -> list:
              "suggested_commit": i.suggested_commit} for i in items]
 
 
+_CLI_EPILOG = r"""기본은 검사:
+stale 항목을 JSON 으로 출력하고, confirm 항목이 남으면 exit 2.
+patch-id 로 내용 동일성이 증명되는 항목(auto)은 --apply 로 일괄 보정되고,
+내용이 바뀐 항목(confirm)은 --stage/--use-ref 로만 보정된다.
+
+Usage:
+  okstra git-reconcile --plan-run-root <dir> --project-id <id> \
+    --task-group <g> --task-id <t> --work-category <c> \
+    [--apply] [--stage <N> --use-ref <ref>] [--reset-anchor <ref>] [--json]
+
+Exit codes:
+  0  stale 없음 또는 보정 완료
+  2  confirm 항목 잔존 (check: 확인 필요 / apply: 일부 미보정)
+  1  error (resolve 실패 등)
+"""
+_CLI_DESCRIPTION = "Okstra \ubc16 git \ud788\uc2a4\ud1a0\ub9ac \ubcc0\uacbd \ud6c4 \uae30\ub85d \ud654\ud574."
+
+
 def _parse_args(argv: Optional[list]):
     import argparse
 
     p = argparse.ArgumentParser(
-        prog="okstra git-reconcile",
-        epilog="exit codes: 0 = clean/applied, 2 = confirm items remain, 1 = error")
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra git-reconcile")
     p.add_argument("--project-root", default=".")
     p.add_argument("--plan-run-root", required=True,
                    help="consumers.jsonl 이 있는 runs/implementation-planning/ 경로")

package/runtime/python/okstra_ctl/handoff.py

@@ -422,10 +422,33 @@ def _parse_stages_csv(raw: str) -> List[int]:
     return out
 
 
+_CLI_EPILOG = r"""JSON 출력.
+
+Usage:
+  okstra handoff eligible --plan-run-root <dir> --approved-plan <md>
+  okstra handoff assemble --plan-run-root <dir> --approved-plan <md> \
+    --project-root <dir> --project-id <id> --task-group <g> --task-id <t> \
+    --work-category <c> --stages 2,3 --base <branch>
+  okstra handoff record-verified --plan-run-root <dir> --stage <N> \
+    --report-path <md> --data-json <json>
+  okstra handoff record-pr --plan-run-root <dir> --stages 2,3 \
+    --branch <b> --url <u>
+  okstra handoff local-checkout --project-root <dir> --project-id <id> \
+    --task-group <g> --task-id <t> [--stage <N>]
+
+Exit codes: 0 ok / 1 자격·전제 위반 / 2 stage 간 merge 충돌(conflicts 동봉)
+"""
+_CLI_DESCRIPTION = "Release-handoff stage-group \ubcf4\uc870 (\uc790\uaca9/\uc218\uc9d1/\uae30\ub85d)."
+
+
 def main(argv: Optional[list] = None) -> int:
     import argparse
 
-    p = argparse.ArgumentParser(prog="okstra handoff")
+    p = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra handoff")
     sub = p.add_subparsers(dest="cmd", required=True)
 
     def common(sp, *, plan=True):

package/runtime/python/okstra_ctl/ids.py

@@ -5,7 +5,9 @@ import hashlib as _hashlib
 import re as _re
 from typing import Dict
 
-from okstra_project.state import slugify as _slugify
+# leaf 규칙 모듈에서 바로 가져온다. state 를 거치면 okstra_ctl 패키지 __init__ 이
+# 상태 접근자 전체를 끌어와 okstra_project ↔ okstra_ctl 순환이 된다.
+from okstra_project.slug import slugify as _slugify
 
 # docker compose project name 길이 상한. compose 는 [a-z0-9][a-z0-9_-]* 만 허용한다.
 CONTAINER_PROJECT_NAME_MAX = 60
@@ -73,28 +75,16 @@ def _escape_segment_for_join(segment: str) -> str:
     return segment.replace("-", "--")
 
 
-def run_id_to_session_name(run_id: str) -> str:
-    """tmux 세션명으로 변환한다. 'okstra-' 접두사 + 세그먼트 escape 후 `-` 조인.
-    예: 'a/b-c/r01' → 'okstra-a-b--c-r01'. 세그먼트 내부 `-` 는 `--` 로
-    이스케이프되어, 슬래시 위치가 다른 두 runId 가 동일 세션명으로
-    충돌하지 않는다. 세그먼트는 fs-safe 슬러그로 강제 정규화해
-    `..` 같은 traversal 토큰이 세션명에 그대로 노출되지 않게 한다.
-    """
-    parts = [_escape_segment_for_join(_safe_fs_segment(seg))
-             for seg in run_id.split("/")]
-    return "okstra-" + "-".join(parts)
-
-
 def slugify_task_segment(value: str) -> str:
     """Match okstra.sh slugify_value for task directory segments."""
     return _re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
 
 
-def build_container_session_name(project_id: str, group: str, task_id: str) -> str:
-    """container detached tmux 세션명을 합친다 → 'okstra-container-<slug>'.
+def build_container_run_trace(project_id: str, group: str, task_id: str) -> str:
+    """container 배포의 `okstra.run-trace` 라벨값을 합친다 → 'okstra-container-<slug>'.
 
     세그먼트는 task_dir 가 쓰는 slugify_task_segment 와 동일 규칙으로 정규화해
-    세션명 slug 가 프로젝트 디스크 경로 slug 와 분기하지 않게 한다.
+    라벨 slug 가 프로젝트 디스크 경로 slug 와 분기하지 않게 한다.
     """
     seg = slugify_task_segment
     return f"okstra-container-{seg(project_id)}-{seg(group)}-{seg(task_id)}"