okstra 0.186.7 → 0.188.0

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
@@ -21,7 +22,7 @@ from __future__ import annotations
 import json
 import re
 from pathlib import Path
-from typing import Any
+from typing import Any, Mapping
 
 class SchemaError(ValueError):
     """Raised when a schema itself is malformed (e.g. a $ref points
@@ -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]) + "}"
 
@@ -260,6 +334,234 @@ class _Validator:
         self.errors.append(f"{_format_path(path)}: {message}")
 
 
+def verdict_token_rule(schema: Mapping[str, Any], task_type: str) -> tuple[str, ...]:
+    """이 task type 의 `finalVerdict.verdictToken` 에 스키마가 허용하는 값.
+
+    스키마는 `allOf` 의 if/then 가지로 세 묶음을 나눈다(분석형 enum,
+    final-verification enum, 나머지 `not-applicable` const). 작성기는 그 가지를
+    읽지 못해 `analysis-complete` 를 error-analysis 에 썼고(2026-09-02 실측),
+    조립이 아니라 HTML 렌더에서야 거절됐다. 여기서 뽑아 저작 계약에 싣는다.
+    가지가 없으면 빈 튜플이다 — 제약이 없다는 뜻이지 실패가 아니다.
+    """
+    def _walk(node: Any) -> tuple[str, ...]:
+        if isinstance(node, dict):
+            condition = node.get("if")
+            then = node.get("then")
+            if isinstance(condition, dict) and isinstance(then, dict):
+                header = (condition.get("properties") or {}).get("header") or {}
+                selector = (header.get("properties") or {}).get("taskType") or {}
+                allowed = selector.get("enum")
+                if allowed is None and "const" in selector:
+                    allowed = [selector["const"]]
+                if isinstance(allowed, list) and task_type in allowed:
+                    verdict = (then.get("properties") or {}).get("finalVerdict") or {}
+                    token = (verdict.get("properties") or {}).get("verdictToken") or {}
+                    if "const" in token:
+                        return (str(token["const"]),)
+                    if isinstance(token.get("enum"), list):
+                        return tuple(str(value) for value in token["enum"])
+            for value in node.values():
+                found = _walk(value)
+                if found:
+                    return found
+        elif isinstance(node, list):
+            for value in node:
+                found = _walk(value)
+                if found:
+                    return found
+        return ()
+
+    return _walk(dict(schema))
+
+
+def task_block_rules(schema: Mapping[str, Any], block_key: str) -> tuple[str, ...]:
+    """이 task type 의 데이터 블록(`properties[block_key]`)이 요구하는 모양을 한
+    객체당 한 줄의 저작 계약 문장으로 편다.
+
+    리드는 report-writer 지시문을 쓸 때 블록 안쪽의 필수 필드·식별자 패턴·
+    정수 필드·고정 길이 배열을 알 길이 프롬프트 경로에 없어 스키마 JSON 을
+    손으로 파싱했고, 그래도 놓친 만큼 같은 리포트를 다시 썼다(2026-09-03 실측,
+    dev-10626 implementation-option-selection: 네 회차). 여기서 뽑아 합성 묶음의
+    저작 계약에 싣는다. 블록이 없거나 객체가 아니면 빈 튜플이다.
+
+    경로는 스키마 키다(`rankedOptions[]` 는 `- Item N` 목록의 각 항목). 같은
+    정의(`$ref`)가 두 경로에 나오면 두 번째는 첫 경로를 가리킨다 — 랭킹 옵션과
+    감사 항목이 하위 구조 여섯 개를 공유한다.
+    """
+    root = dict(schema)
+    block = (root.get("properties") or {}).get(block_key)
+    if not isinstance(block, dict):
+        return ()
+    lines: list[str] = []
+    described: dict[str, str] = {}
+    _describe_object(root, block, block_key, lines, described)
+    return tuple(lines)
+
+
+def _resolved(root: dict, node: Any) -> tuple[dict, str | None]:
+    """`$ref` 를 풀고, allOf 가지의 properties/required 를 얕게 합친다.
+
+    반환값의 둘째는 이 노드가 가리킨 정의 이름 — 같은 정의를 두 경로에서
+    두 번 펴지 않기 위해 쓴다.
+    """
+    if not isinstance(node, dict):
+        return {}, None
+    ref_name: str | None = None
+    if "$ref" in node:
+        ref_name = str(node["$ref"]).rsplit("/", 1)[-1]
+        node = _resolve_ref(node["$ref"], root)
+    merged = dict(node)
+    for branch in node.get("allOf") or []:
+        resolved, branch_ref = _resolved(root, branch)
+        if ref_name is None:
+            ref_name = branch_ref
+        properties = dict(merged.get("properties") or {})
+        for key, value in (resolved.get("properties") or {}).items():
+            existing = properties.get(key)
+            properties[key] = {**existing, **value} if isinstance(existing, dict) else value
+        merged["properties"] = properties
+        merged["required"] = list(
+            dict.fromkeys([*(merged.get("required") or []), *(resolved.get("required") or [])])
+        )
+        for keyword in ("type", "pattern", "const", "enum", "minItems", "maxItems", "items", "prefixItems"):
+            if keyword in resolved and keyword not in merged:
+                merged[keyword] = resolved[keyword]
+    return merged, ref_name
+
+
+def _describe_object(
+    root: dict, node: Any, path: str, lines: list[str], described: dict[str, str],
+) -> None:
+    schema, ref_name = _resolved(root, node)
+    if ref_name and ref_name in described:
+        lines.append(f"`{path}`: same shape as `{described[ref_name]}`")
+        return
+    if ref_name:
+        described[ref_name] = path
+    properties = schema.get("properties") or {}
+    required = [key for key in (schema.get("required") or []) if isinstance(key, str)]
+    optional = [key for key in properties if key not in required]
+    parts: list[str] = []
+    if required:
+        parts.append("required " + ", ".join(f"`{key}`" for key in required))
+    if optional:
+        parts.append("optional " + ", ".join(f"`{key}`" for key in optional))
+    nested: list[tuple[str, Any]] = []
+    for key, value in properties.items():
+        constraint = _describe_property(root, value, f"{path}.{key}", nested)
+        if constraint:
+            parts.append(f"`{key}` {constraint}")
+    lines.append(f"`{path}`: " + "; ".join(parts))
+    for child_path, child in nested:
+        _describe_object(root, child, child_path, lines, described)
+
+
+def _describe_property(
+    root: dict, node: Any, path: str, nested: list[tuple[str, Any]],
+) -> str:
+    """한 속성의 제약을 한 구절로. 객체 자식은 `nested` 에 넣어 자기 줄을 받는다."""
+    schema, _ref = _resolved(root, node)
+    branches = schema.get("oneOf") or schema.get("anyOf") or []
+    nullable = False
+    if branches:
+        resolved_branches = [_resolved(root, branch)[0] for branch in branches]
+        nullable = any(branch.get("type") == "null" for branch in resolved_branches)
+        others = [branch for branch in branches if _resolved(root, branch)[0].get("type") != "null"]
+        if len(others) == 1:
+            schema = _resolved(root, others[0])[0] | {"__branch": others[0]}
+    types = schema.get("type")
+    types = types if isinstance(types, list) else ([types] if types else [])
+    if "null" in types:
+        nullable = True
+        types = [item for item in types if item != "null"]
+    suffix = " or `_none_`" if nullable else ""
+    if "const" in schema:
+        return f"exactly `{schema['const']}`{suffix}"
+    if isinstance(schema.get("enum"), list):
+        return "one of " + ", ".join(f"`{value}`" for value in schema["enum"]) + suffix
+    if "properties" in schema or types == ["object"]:
+        nested.append((path, schema.get("__branch", node)))
+        return f"object (see `{path}`){suffix}"
+    if types == ["array"] or "items" in schema or "prefixItems" in schema:
+        return _describe_array(root, schema, path, nested) + suffix
+    if types == ["integer"]:
+        return "integer" + _range(schema) + suffix
+    if types == ["number"]:
+        return "number" + _range(schema) + suffix
+    if types == ["string"]:
+        pattern = schema.get("pattern")
+        return (f"matches `{pattern}`" if pattern else "string") + suffix
+    if types == ["boolean"]:
+        return "`true` or `false`" + suffix
+    return ""
+
+
+def _describe_array(
+    root: dict, schema: dict, path: str, nested: list[tuple[str, Any]],
+) -> str:
+    minimum = schema.get("minItems")
+    maximum = schema.get("maxItems")
+    if maximum == 0:
+        return "must be empty (`> _none_`)"
+    if minimum is not None and minimum == maximum:
+        size = f"exactly {maximum} items"
+    else:
+        bounds = [
+            text
+            for text in (
+                f"at least {minimum}" if minimum else "",
+                f"at most {maximum}" if maximum is not None else "",
+            )
+            if text
+        ]
+        size = "list" + (f" ({', '.join(bounds)})" if bounds else "")
+    prefix_items = schema.get("prefixItems")
+    if isinstance(prefix_items, list) and prefix_items:
+        order = _prefix_order(root, prefix_items)
+        first, _ = _resolved(root, prefix_items[0])
+        if "properties" in first:
+            nested.append((f"{path}[]", prefix_items[0]))
+            return f"{size} in this order: {order}; each item (see `{path}[]`)"
+        return f"{size} in this order: {order}"
+    items = schema.get("items")
+    item_schema, _ = _resolved(root, items) if items is not None else ({}, None)
+    if "properties" in item_schema:
+        nested.append((f"{path}[]", items))
+        return f"{size} of objects (see `{path}[]`)"
+    if "pattern" in item_schema:
+        return f"{size} of strings matching `{item_schema['pattern']}`"
+    if isinstance(item_schema.get("enum"), list):
+        return f"{size}, each one of " + ", ".join(f"`{value}`" for value in item_schema["enum"])
+    if item_schema.get("type"):
+        return f"{size} of {item_schema['type']}"
+    return size
+
+
+def _prefix_order(root: dict, prefix_items: list) -> str:
+    """고정 순서 배열의 각 자리가 못 박은 값 — `criterion` 처럼 상수인 속성."""
+    labels: list[str] = []
+    for item in prefix_items:
+        merged, _ = _resolved(root, item)
+        consts = [
+            f"`{key}`=`{value['const']}`"
+            for key, value in (merged.get("properties") or {}).items()
+            if isinstance(value, dict) and "const" in value
+        ]
+        labels.append(", ".join(consts) if consts else "item")
+    return "; ".join(labels)
+
+
+def _range(schema: dict) -> str:
+    low, high = schema.get("minimum"), schema.get("maximum")
+    if low is not None and high is not None:
+        return f" {low}..{high}"
+    if low is not None:
+        return f" >= {low}"
+    if high is not None:
+        return f" <= {high}"
+    return ""
+
+
 def validate(data: Any, schema: dict) -> list[str]:
     """Validate ``data`` against ``schema``. Returns the list of human-
     readable error messages (empty when the data is valid)."""

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)}"