okstra 0.195.4 → 0.197.0

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -99,6 +99,10 @@ from .initial_prompt_materialization import (
 )
 from .agent.invocation import AgentInvocationError, materialize_retry_invocation
 from .path_hints import hydrate_active_run_context
+from .worker_prompt_policy import (
+    is_verification_dispatch_kind,
+    verification_dispatch_round,
+)
 from .schema_excerpt import (
     bundle_excerpt_path,
     describe_changed,
@@ -1856,13 +1860,14 @@ def _job_for_attempt(job: WorkerJob, attempt: int) -> WorkerJob:
 
 
 def _dispatch_round(dispatch_kind: str) -> int:
-    prefix = "reverify-r"
-    if not dispatch_kind.startswith(prefix):
+    """attempt 행의 라운드 번호. 예약과 같은 계산을 쓴다
+    (`worker_prompt_policy.verification_dispatch_round`)."""
+    if not is_verification_dispatch_kind(dispatch_kind):
         return 1
-    suffix = dispatch_kind[len(prefix):]
-    if not suffix.isdigit() or int(suffix) < 1:
-        raise DispatchError(f"invalid reverify dispatch kind: {dispatch_kind}")
-    return int(suffix)
+    round_number = verification_dispatch_round(dispatch_kind)
+    if round_number is None:
+        raise DispatchError(f"invalid verification dispatch kind: {dispatch_kind}")
+    return round_number
 
 
 def _dispatch_job_with_retry(plan: DispatchPlan, job: WorkerJob) -> int:

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -61,7 +61,10 @@ from .worker_prompt_contract import (
     validate_prompt_model_header,
     validate_reverify_prompt,
 )
-from .worker_prompt_policy import is_verification_dispatch_kind
+from .worker_prompt_policy import (
+    is_verification_dispatch_kind,
+    verification_dispatch_round,
+)
 from .worker_runner import LIVE, QUIET
 from .worker_request import verifier_extra_dirs
 from .worker_artifact_paths import audit_sidecar_rel
@@ -1000,13 +1003,14 @@ def prompt_anchor_values(
 
 
 def _execution_dispatch_round(dispatch_kind: str) -> int:
-    prefix = "reverify-r"
-    if not dispatch_kind.startswith(prefix):
+    """attempt 행에 적는 라운드 번호. 예약(`agent-prompt materialize` 의
+    `_reservation_round`)과 같은 계산을 써야 한다."""
+    if not is_verification_dispatch_kind(dispatch_kind):
         return 1
-    suffix = dispatch_kind[len(prefix):]
-    if not suffix.isdigit() or int(suffix) < 1:
-        raise DispatchError(f"invalid reverify dispatch kind: {dispatch_kind}")
-    return int(suffix)
+    round_number = verification_dispatch_round(dispatch_kind)
+    if round_number is None:
+        raise DispatchError(f"invalid verification dispatch kind: {dispatch_kind}")
+    return round_number
 
 
 def link_agent_dispatch_result(

package/runtime/python/okstra_ctl/domain/worker_presentation.py

@@ -13,6 +13,7 @@ CLI 는 갈라 읽어야 한다.
 from __future__ import annotations
 
 import json
+import re
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Callable, Literal, Mapping, Protocol, runtime_checkable
@@ -34,6 +35,11 @@ ObserveServedModel = Callable[[Mapping[str, Any]], str | None]
 ObserveUsage = Callable[[Mapping[str, Any]], Mapping[str, Any] | None]
 
 WORKER = "worker"
+_TERMINAL_COLORS = re.compile(r"\x1b\[[0-9;:]*m")
+
+
+def strip_terminal_colors(text: str) -> str:
+    return _TERMINAL_COLORS.sub("", text)
 
 
 class TranscriptWriter(Protocol):
@@ -93,7 +99,7 @@ class SplitText:
     def sinks(self, writer: TranscriptWriter) -> tuple[SinkSpec, ...]:
         def result(line: str) -> str | None:
             writer.write(WORKER, line)
-            return line
+            return strip_terminal_colors(line)
 
         def progress(line: str) -> str | None:
             writer.write(WORKER, line)

package/runtime/python/okstra_ctl/domain/worker_stream.py

@@ -38,7 +38,6 @@ _MAX_SUMMARY = 120
 # 결과 하나가 pane 을 다 차지하면 직전 호출이 위로 밀려 나가므로 앞부분만
 # 보여주고, 나머지는 로그가 갖는다.
 _LIVE_BODY_ROWS = 4
-_BODY_INDENT = "    "
 
 
 @dataclass(frozen=True)
@@ -197,8 +196,8 @@ def _rows(event: StreamEvent, *, limit: int | None, body_rows: int | None) -> li
             tail = (
                 f"the tool reported: {report}" if report else "the tool reported nothing"
             )
-            return [_truncate(f"  ← {_outcome(event.failed)} — no body returned; {tail}", limit)]
-        head = f"  ← {_outcome(event.failed)} ({event.size_bytes} bytes)"
+            return [_truncate(f"← {_outcome(event.failed)} — no body returned; {tail}", limit)]
+        head = f"← {_outcome(event.failed)} ({event.size_bytes} bytes)"
         return [head, *_result_body(event.body, limit=limit, keep=body_rows)]
     if isinstance(event, Denial):
         return [_truncate(f"!! PERMISSION DENIED — {event.tool}: {event.reason}", limit)]
@@ -217,10 +216,10 @@ def _result_body(body: str, *, limit: int | None, keep: int | None) -> list[str]
     rows = _body_rows(body)
     if keep is None:
         return rows
-    shown = [_truncate(_BODY_INDENT + row, limit) for row in rows[:keep]]
+    shown = [_truncate(row, limit) for row in rows[:keep]]
     dropped = len(rows) - keep
     if dropped > 0:
-        shown.append(f"{_BODY_INDENT}… +{dropped} more line(s) — full body in the log")
+        shown.append(f"… +{dropped} more line(s) — full body in the log")
     return shown
 
 

package/runtime/python/okstra_ctl/final_report_schema.py

@@ -202,7 +202,68 @@ class _Validator:
             elif schema.get("additionalProperties") is False:
                 # Don't fire for keys we know are part of the conditional
                 # branches (we still validate values when they appear).
-                self._err(path, f"additional property '{name}' is not allowed")
+                self._err(
+                    path,
+                    f"additional property '{name}' is not allowed"
+                    + self._misplaced_property_hint(name, path),
+                )
+
+    def _misplaced_property_hint(
+        self, name: str, path: tuple[str | int, ...],
+    ) -> str:
+        """이 키가 스키마의 다른 자리에서 정의된 필드면 "옮겨라" 를 덧붙인다.
+
+        `additional property 'X' is not allowed` 만 보면 "스키마에 그런 칸이
+        없다" 로 읽힌다. 실제로는 X 가 다른 객체의 필드이고 작성자가 자리를
+        틀린 경우가 있고, 그때 지우면 다음 라운드에서 `required property 'X'
+        is missing` 이 나온다 — 라운드 하나를 왕복에 쓴다(2026-09-09 실측,
+        dev-10642 implementation-planning: 최상위 필수 `summary` 를
+        `rationale` 안에 써서 지웠다가 되살렸다).
+        """
+        found = self._required_property_owners(name) - {_format_path(path)}
+        if not found:
+            return ""
+        # 최상위를 앞에 둔다. 잘못 놓인 키는 대개 최상위 필드가 한 단계 안으로
+        # 들어간 것이고, 나머지 소유자는 같은 이름을 쓰는 다른 행 타입이다.
+        owners = (
+            ["<root>"] if "<root>" in found else []
+        ) + sorted(found - {"<root>"})
+        return (
+            f" — '{name}' is a REQUIRED property of {', '.join(owners[:3])}, not "
+            f"of {_format_path(path)}; move it there rather than removing it"
+        )
+
+    def _required_property_owners(self, name: str) -> set[str]:
+        """`name` 을 **필수**로 요구하는 객체들의 이름.
+
+        정의만 가진 자리까지 세면(예: `summary` 는 8곳에서 정의된다) 힌트가
+        이름 목록이 돼 아무것도 가리키지 못한다. 지우면 다음 라운드에서
+        `required property ... is missing` 이 나오는 자리, 즉 필수인 곳만 센다.
+        """
+        owners: set[str] = set()
+
+        def walk(node: Any, label: str) -> None:
+            if isinstance(node, list):
+                for item in node:
+                    walk(item, label)
+                return
+            if not isinstance(node, dict):
+                return
+            required = node.get("required")
+            if isinstance(required, list) and name in required:
+                owners.add(label)
+            for key, value in node.items():
+                if key == "properties" and isinstance(value, dict):
+                    for child, sub in value.items():
+                        walk(sub, f"{label}.{child}" if label else child)
+                elif key in ("definitions", "$defs") and isinstance(value, dict):
+                    for child, sub in value.items():
+                        walk(sub, child)
+                elif key in ("items", "allOf", "oneOf", "anyOf", "then", "else"):
+                    walk(value, label)
+
+        walk(self.root, "<root>")
+        return owners
 
     def _validate_array(self, instance: list, schema: dict, path: tuple[str | int, ...]) -> None:
         min_items = schema.get("minItems")

package/runtime/python/okstra_ctl/plan_items.py

@@ -790,6 +790,20 @@ PLAN_VERIFY_RESPONSE_FORMAT = (
 )
 
 
+# 계획 항목 큐의 렌더러 서명. 검증 계약(`worker_prompt_contract.
+# validate_reverify_prompt`)이 `plan-verify-r<N>` 디스패치에 이 줄을 요구한다 —
+# 번호 reverify 가 `okstra convergence reverify-prompt` 서명을 요구하는 것과
+# 같은 이유다. 손으로 쓴 큐는 항목 id·직전 반대 의견·응답 형식이 임의로 빠지고,
+# 그렇게 버려진 라운드가 실재한다(run 003 실측, `with_response_format` 주석).
+RENDERED_BY_LINE = "**Rendered by:** okstra plan-items prompt"
+
+
+def with_rendered_by(queue_markdown: str) -> str:
+    """렌더러 서명을 프롬프트 맨 앞에 붙인다. 디스패치는 이 출력을 그대로
+    `--instruction` 으로 받으므로 서명은 `## Task Instructions` 뒤에 놓인다."""
+    return f"{RENDERED_BY_LINE}\n\n{queue_markdown.lstrip()}"
+
+
 def with_response_format(queue_markdown: str) -> str:
     """큐 본문 뒤에 응답 형식 블록을 덧붙인다. run 003 실측: 리드가 손 조립
     중 이 블록을 빼먹어 검증자 2명의 판정 32건 전부가 형식 불일치로 버려졌다."""

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -43,6 +43,7 @@ from .plan_items import (
     reverify_prompt_text,
     tie_vote_item_ids,
     voting_analyser_keys,
+    with_rendered_by,
     with_response_format,
 )
 from .paths import RunRef
@@ -242,6 +243,14 @@ def _parser() -> argparse.ArgumentParser:
         metavar="<worker-id>=<path>",
         help="one worker's plan-verify Markdown result (repeatable)",
     )
+    apply_verdicts.add_argument(
+        "--items", type=Path,
+        metavar="<plan-items artifact>",
+        help="the plan-items artifact this round dispatched, when it dispatched "
+             "part of the queue (the `--tie-vote` artifact). Its dispatchQueue "
+             "is what each --result must answer; without it a result is checked "
+             "against the whole persisted queue",
+    )
     apply_verdicts.add_argument(
         "--run-manifest", type=Path,
         help="resolve the project a `fact` claim's probe runs against; without "
@@ -831,10 +840,10 @@ def _prompt(args: argparse.Namespace) -> str:
             rows.append(split)
     body = with_response_format("".join(rows))
     if envelope.get("dispatchKind") == "critic-tie":
-        return critic_tie_prompt_text(body)
+        return with_rendered_by(critic_tie_prompt_text(body))
     if envelope.get("dispatchKind") == "reverify":
-        return reverify_prompt_text(body)
-    return body
+        return with_rendered_by(reverify_prompt_text(body))
+    return with_rendered_by(body)
 
 
 def _validate_prepared(args: argparse.Namespace) -> dict[str, Any]:
@@ -1377,6 +1386,7 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
         {item_id for item_id in queue if isinstance(item_id, str)}
         if isinstance(queue, list) else known
     )
+    assigned = _narrow_assignment(args, assigned)
     rows = _incoming_verdict_rows(args, assigned)
     missing = sorted(item_id for item_id in rows if item_id not in known)
     if missing:
@@ -1872,6 +1882,38 @@ def _correction_prompt(args: argparse.Namespace) -> str:
     return correction_prompt_text(_prompt(args))
 
 
+def _narrow_assignment(
+    args: argparse.Namespace, assigned: set[object],
+) -> set[object]:
+    """이 라운드가 실제로 배정한 항목들.
+
+    tie 라운드는 큐의 일부(7항목)만 critic 에게 보낸다. 그런데 `--result` 는
+    지금까지 state 에 남은 라운드 큐(44항목) 전체를 배정으로 보고 답 없는
+    37항목을 미응답으로 거절했다 — 문서가 "model-facing" 이라고 적은 형식이
+    tie 라운드에서는 쓸 수 없고, 우회로가 헬프 스스로 historical 이라 적은
+    `--verdicts` 뿐이었다(실측 2026-09-10, fontsninja-v3-site dev-10628-3).
+    `--items` 로 그 라운드의 artifact 를 주면 그 `dispatchQueue` 가 배정이
+    된다. 미응답 검사 자체는 그대로다 — 좁힌 배정 안에서 여전히 전건을
+    요구하므로, 워커가 자기 몫을 조용히 빠뜨리는 것은 계속 잡힌다.
+    """
+    items_path = getattr(args, "items", None)
+    if items_path is None:
+        return assigned
+    narrowed = {item_id for item_id in _assigned_item_ids(items_path)}
+    if not narrowed:
+        raise PlanItemContractError(
+            f"items artifact dispatches nothing: {items_path}"
+        )
+    unknown = sorted(narrowed - {i for i in assigned if isinstance(i, str)})
+    if unknown:
+        raise PlanItemContractError(
+            f"items artifact dispatches {unknown}, which this round's persisted "
+            f"queue does not contain — pass the artifact this round dispatched, "
+            f"not another round's"
+        )
+    return narrowed
+
+
 def _incoming_verdict_rows(
     args: argparse.Namespace, known: set[object],
 ) -> dict[str, list[dict[str, Any]]]:

package/runtime/python/okstra_ctl/run.py

@@ -551,6 +551,11 @@ class PrepareInputs:
     # implementation 전용: `--qa-waiver "<stageKey>:<reason>"` 사용자 확인형 우회.
     # prepare-time 에 task-level conformance 매니페스트 entry.waiver 를 채운다.
     qa_waiver: str = ""
+    # implementation-planning 전용: `--tdd-bypass "<stage>:<reason>"` 사용자
+    # 확인형 TDD 우회. prepare-time 에 `<task-root>/qa/tdd-bypass.json` 에
+    # 사유를 원문 그대로 남기고, S10e 는 그 원장이 있을 때만 계획서의
+    # `tddExemption: user-bypass` 를 인정한다.
+    tdd_bypass: str = ""
     stage: str = "auto"
     # release-handoff 전용: PR 로 내보낼 stage 묶음 (csv, 예: "2,3"). 빈 값 =
     # whole-task 모드. `--stage`(impl/fv 의 Stage Map 실행/검증 선택)와는
@@ -1915,6 +1920,40 @@ def validate_project_qa_commands(task_type: str, project_root: Path) -> None:
         raise PrepareError(_format_qa_errors(qa_errors))
 
 
+def _apply_tdd_bypass_if_requested(inp: "PrepareInputs", project_root: Path) -> None:
+    """`--tdd-bypass` 가 있으면 task-level TDD 우회 원장에 사유를 남긴다.
+
+    같은 task-key 의 다른 prepare 와 같은 파일을 read-modify-write 하므로
+    `_apply_qa_waiver_if_requested` 와 동일한 per-task-key 락 안에서 쓴다.
+    원장이 없으면 만든다 — 사용자가 빈 파일을 손으로 만들 이유가 없다.
+    """
+    if not inp.tdd_bypass:
+        return
+    from .paths import task_dir
+    from .tdd_bypass import (
+        TddBypassError,
+        bypass_file,
+        parse_bypass_arg,
+        record_bypass,
+    )
+    parsed = parse_bypass_arg(inp.tdd_bypass)
+    if parsed is None:
+        raise PrepareError(
+            '--tdd-bypass must be "<stage>:<reason>" with a positive stage '
+            f"number, got {inp.tdd_bypass!r}"
+        )
+    stage, reason = parsed
+    path = bypass_file(task_dir(project_root, inp.task_group, inp.task_id))
+    when = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    with worktree_provision_mutex(
+        okstra_home(), inp.project_id, slugify(inp.task_group), slugify(inp.task_id),
+    ):
+        try:
+            record_bypass(path, stage, reason, at=when)
+        except TddBypassError as exc:
+            raise PrepareError(f"--tdd-bypass: {exc}") from exc
+
+
 def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> None:
     """`--qa-waiver` 가 있으면 task-level 매니페스트 entry 의 waiver 를 채운다.
 
@@ -2008,6 +2047,9 @@ def _register_and_check_project(project_root: Path, inp: PrepareInputs) -> None:
     # waiver 는 stage 단위 Tier 3 면제라 implementation 진입에서만 적용한다.
     if inp.task_type == "implementation":
         _apply_qa_waiver_if_requested(inp, project_root)
+    # TDD 우회는 계획서의 stage 를 면제하므로 계획 진입에서만 적용한다.
+    if inp.task_type == "implementation-planning":
+        _apply_tdd_bypass_if_requested(inp, project_root)
 
 
 def _resolve_roster(inp: PrepareInputs, profile_file: Path) -> tuple[list[str], str]:
@@ -4563,6 +4605,25 @@ def _resolve_terminal_backend(project_root: Path, inp: PrepareInputs) -> str:
     ) if part))
 
 
+def lead_pane_title(task_group: str, task_id: str) -> str:
+    """cmux 에서 리드 pane 에 붙는 제목. 사용자가 여러 task 의 pane 을 구분하는
+    이름이므로 slug 가 아니라 입력한 task-group / task-id 그대로 쓴다."""
+    return f"{task_group}/{task_id}"
+
+
+def _title_lead_pane(inp: PrepareInputs) -> None:
+    """리드 pane 제목을 `<task-group>/<task-id>` 로 바꾼다 (cmux 백엔드 전용).
+
+    prepare 는 리드 세션(또는 리드를 띄울 pane)에서 실행되므로 호출 surface 가
+    곧 리드 pane 이다. 제목은 화면 편의라 실패해도 run 을 막지 않지만, 무엇이
+    막았는지는 stderr 에 남긴다 — codex 샌드박스가 cmux 소켓을 EPERM 으로 막는
+    경우가 실제로 있다(`_resolve_terminal_backend` 참조).
+    """
+    reason = cmux.rename_lead_surface(lead_pane_title(inp.task_group, inp.task_id))
+    if reason:
+        print(f"okstra: lead pane title not applied — {reason}", file=sys.stderr)
+
+
 def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     """Produce a complete okstra task bundle on disk. See module docstring."""
     workspace_root = Path(inp.workspace_root)
@@ -4872,6 +4933,9 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
 
     _record_run_in_central_index(inp, ctx, workspace_root, run_seq_override)
 
+    if terminal_backend == BACKEND_CMUX_PANE:
+        _title_lead_pane(inp)
+
     if not inp.render_only:
         _provision_settings_symlink(inp)
 
@@ -5036,6 +5100,17 @@ def build_prepare_argument_parser():
     p.add_argument("--critic", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
     p.add_argument("--approved-plan", default="", dest="approved_plan_path")
+    p.add_argument(
+        "--tdd-bypass",
+        default="",
+        dest="tdd_bypass",
+        help=(
+            'User-recorded TDD bypass for one plan stage: "<stage>:<reason>" '
+            "(implementation-planning only). Records the reason verbatim into "
+            "<task-root>/qa/tdd-bypass.json; S10e accepts a stage declaring "
+            "tddExemption `user-bypass` only while that record exists."
+        ),
+    )
     p.add_argument(
         "--qa-waiver",
         default="",
@@ -5301,6 +5376,7 @@ def main(argv: list[str]) -> int:
         base_ref=args.base_ref,
         approved_plan_path=args.approved_plan_path,
         qa_waiver=args.qa_waiver,
+        tdd_bypass=args.tdd_bypass,
         stage=args.stage,
         stages=args.stages,
         clarification_response_path=clarification_abs,

package/runtime/python/okstra_ctl/session_transcript.py

@@ -11,16 +11,17 @@ from datetime import datetime
 from pathlib import Path
 from typing import Callable
 
+from .domain.worker_presentation import strip_terminal_colors
+
 OKSTRA = "okstra"
-_SPEAKER_WIDTH = 14
 _RESET = "\x1b[0m"
 _MUTED = "\x1b[90m"
 _LIVE_COLORS = (
     ("→ ", "\x1b[36m"),
-    ("  ← ok", "\x1b[32m"),
-    ("  ← error", "\x1b[31m"),
+    ("← ok", "\x1b[32m"),
+    ("← error", "\x1b[31m"),
     ("!! PERMISSION DENIED", "\x1b[1;31m"),
-    ("  ← done", "\x1b[33m"),
+    ("← done", "\x1b[33m"),
 )
 
 # 파일 사본이 담는 워커 진행 줄의 상한. 진행은 워커 출력의 부피가 몰리는
@@ -50,11 +51,20 @@ class SessionTranscript:
         path.parent.mkdir(parents=True, exist_ok=True)
         self._file = path.open("w", encoding="utf-8")
         self._live = live
+        # cmux 워커는 색상 사용을 명시한다. 리드에서 상속한 비대화형 출력
+        # 설정이 워커 터미널의 색상까지 끄지 않도록 명시적 요청을 우선한다.
+        force_color = os.environ.get("FORCE_COLOR", "")
         self._color = (
             live
             and sys.stdout.isatty()
-            and not os.environ.get("NO_COLOR")
-            and os.environ.get("TERM") != "dumb"
+            and (
+                force_color not in ("", "0")
+                or (
+                    force_color != "0"
+                    and not os.environ.get("NO_COLOR")
+                    and os.environ.get("TERM") != "dumb"
+                )
+            )
         )
         self._clock = clock
         self._archived = 0
@@ -89,9 +99,7 @@ class SessionTranscript:
             self._keep(self._row(speaker, line), capped=True)
 
     def _row(self, speaker: str, line: str) -> str:
-        # 패딩이 본문 앞 공백을 겸한다. 뒤에 공백을 한 칸 더 넣으면
-        # `[worker:grok]`(13칸) 줄이 두 칸이 되고 `[okstra]` 정렬이 깨진다.
-        label = f"[{speaker}]".ljust(_SPEAKER_WIDTH)
+        label = f"[{speaker}]"
         return f"{self._clock()} {label}{line}".rstrip()
 
     def _show(self, row: str, line: str) -> None:
@@ -110,7 +118,7 @@ class SessionTranscript:
                     f"{_MUTED}{row[:prefix_size]}{_RESET}"
                     f"{color}{row[prefix_size:]}{_RESET}"
                 )
-            print(row, flush=True)
+            print(row if self._color else strip_terminal_colors(row), flush=True)
 
     def _keep(self, row: str, *, capped: bool) -> None:
         if not capped:
@@ -136,7 +144,7 @@ class SessionTranscript:
         self._file.close()
 
     def _append(self, row: str) -> None:
-        self._file.write(row + "\n")
+        self._file.write(strip_terminal_colors(row) + "\n")
         self._file.flush()
 
     def _note_elision(self) -> None: