okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/paths.py

@@ -27,7 +27,7 @@ from okstra_project.dirs import (
     TASKS_RELATIVE,
     okstra_home,
 )
-from okstra_project.state import slugify
+from okstra_project.slug import slugify
 
 __all__ = [
     "OKSTRA_RELATIVE",
@@ -43,8 +43,22 @@ __all__ = [
     "container_paths",
     "okstra_home",
     "find_asset_root",
+    "RUN_VALIDATOR_RELATIVE",
+    "BRIEF_VALIDATOR_RELATIVE",
+    "STAGE_VALIDATOR_RELATIVE",
 ]
 
+# validators 트리 안의 자산들. `find_asset_root` 에 그대로 넘겨 쓰라고 튜플로
+# 둔다 — 이 이름들을 문자열로 조립하던 호출부들이 저마다 다른 루트를 가정해
+# 어긋나 있었다(설치본에서는 `~/.okstra/lib/validators`, 체크아웃에서는
+# `<repo>/validators`).
+RUN_VALIDATOR_RELATIVE = ("validators", "validate-run.py")
+BRIEF_VALIDATOR_RELATIVE = ("validators", "validate-brief.py")
+STAGE_VALIDATOR_RELATIVE = (
+    "validators",
+    "validate-implementation-plan-stages.py",
+)
+
 
 def find_asset_root(
     relative: Sequence[str],
@@ -191,6 +205,18 @@ class RunRef:
     def manifest(self) -> Path:
         return self.run_dir / "manifests" / f"run-manifest{self._suffix}.json"
 
+    @property
+    def convergence_state(self) -> Path:
+        """이 run 의 finding convergence 상태 파일.
+
+        이름은 다른 산출물과 같은 seq 규칙을 쓴다. `compute_run_paths` 는
+        디렉터리마다 seq 를 따로 세므로(`reports: 004` 와 `state: 005` 가 실제로
+        갈린 적이 있다), 리포트 경로에서 만든 ref 로 이 값을 계산하면 그 갈린
+        run 에서는 존재하지 않는 파일을 가리킨다. 호출자는 파일이 없는 경우를
+        정상 분기로 다뤄야 한다.
+        """
+        return self.run_dir / "state" / f"convergence{self._suffix}.json"
+
     def carry(self, stage: int) -> Path:
         """stage 의 carry 사이드카. implementation 은 stage-SHARED(flat)다."""
         return self.carry_dir / f"stage-{int(stage)}.json"
@@ -354,6 +380,20 @@ def task_manifest_file(task_root: Path) -> Path:
     return Path(task_root) / TASK_MANIFEST_FILENAME
 
 
+def task_qa_dir(task_root: Path) -> Path:
+    """task 의 qa 산출물 디렉터리.
+
+    Tier 3 conformance manifest 와 그 스크립트, self-mock 사이드카, 워커가 실행한
+    result-*.json 이 모두 여기 산다. 쓰기 계약이 이 경로를 역할별로 허용해야 하므로
+    (`dispatch_core._task_qa_paths`) 디렉터리 이름을 리터럴로 흩어 두지 않는다."""
+    return Path(task_root) / "qa"
+
+
+def task_conformance_manifest_file(task_root: Path) -> Path:
+    """task 의 Tier 3 conformance manifest 경로."""
+    return task_qa_dir(task_root) / "conformance-manifest.json"
+
+
 def task_timeline_file(task_root: Path) -> Path:
     """task 의 history timeline 경로."""
     return Path(task_root) / "history" / "timeline.json"
@@ -369,10 +409,7 @@ def container_paths(project_root: Path, task_group: str, task_id: str) -> dict:
     return {
         "container_dir": base,
         "env_override": base / "env.override",
-        "registry": base / "registry.json",
-        "registry_lock": base / "registry.json.lock",
         "deploy_state": base / "deploy-state.json",
-        "watchers_dir": base / "watchers",
     }
 
 
@@ -445,8 +482,8 @@ def compute_run_paths(
     """주어진 identity 와 task-type 에 대해 모든 path/segment 값을 계산해
     dict 로 돌려준다. 부수효과 없음.
 
-    run_seq_override: 정수가 주어지면 7개 seq 모두 그 값으로 강제. okstra-ctl
-    rerun 처럼 외부에서 seq 를 미리 reserve 한 경로용. 미지정 시 디스크 스캔
+    run_seq_override: 정수가 주어지면 7개 seq 모두 그 값으로 강제. 외부에서
+    seq 를 미리 reserve 한 경로용(현재는 테스트 hook). 미지정 시 디스크 스캔
     결과로 결정.
     """
     project_root = Path(project_root)
@@ -471,7 +508,7 @@ def compute_run_paths(
     task_index = task_root / "task-index.md"
     instruction_set = task_root / "instruction-set"
     analysis_packet = instruction_set / "analysis-packet.md"
-    task_qa = task_root / "qa"
+    task_qa = task_qa_dir(task_root)
     runs_dir = runs_dir_of(task_root)
     history_dir = task_root / "history"
     timeline_file = task_timeline_file(task_root)
@@ -569,6 +606,7 @@ def compute_run_paths(
     approval_decisions = run_state / f"approval-decisions-{task_type_segment}-{seqs['state']}.json"
     design_preparation = run_state / f"design-preparation-{task_type_segment}-{seqs['state']}.json"
     plan_body_verification = run_state / f"plan-body-verification-{task_type_segment}-{seqs['state']}.json"
+    incremental_decision = run_state / f"incremental-decision-{task_type_segment}-{seqs['state']}.json"
 
     run_errors_log = run_logs / f"errors-{task_type_segment}-{seqs['state']}.jsonl"
     runtime_home = okstra_home()
@@ -578,7 +616,14 @@ def compute_run_paths(
     antigravity_worker_errors_sidecar = worker_results / f"antigravity-worker-errors{suffixes['worker_results']}.json"
     report_writer_worker_errors_sidecar = worker_results / f"report-writer-worker-errors{suffixes['worker_results']}.json"
 
-    run_validator_script = workspace_root / "validators" / "validate-run.py"
+    # validators 트리는 설치본에서 `~/.okstra/lib/validators` 에, 체크아웃에서는
+    # `<repo>/validators` 에 있다. workspace_root 로 계산하면 셸 진입점이 넘기는
+    # `~/.okstra` 아래에서 빗나가므로(그 아래엔 `validators/` 가 없다) 자산을
+    # 실제로 가진 루트를 탐색해서 해소한다. 탐색이 실패하면 workspace_root 를
+    # 그대로 써서 소비자 쪽 존재 검사가 원래 경로를 그대로 보고하게 둔다.
+    run_validator_script = (
+        find_asset_root(RUN_VALIDATOR_RELATIVE) or workspace_root
+    ).joinpath(*RUN_VALIDATOR_RELATIVE)
 
     abs_paths = {
         "PROJECT_ID": project_id,
@@ -679,6 +724,7 @@ def compute_run_paths(
         "DESIGN_PREPARATION_PATH": str(design_preparation),
         "CONVERGENCE_STATE_PATH": str(convergence_state),
         "PLAN_BODY_VERIFICATION_STATE_PATH": str(plan_body_verification),
+        "INCREMENTAL_DECISION_STATE_PATH": str(incremental_decision),
         "RUN_ERRORS_LOG_PATH": str(run_errors_log),
         "CLAUDE_WORKER_ERRORS_SIDECAR_PATH": str(claude_worker_errors_sidecar),
         "CODEX_WORKER_ERRORS_SIDECAR_PATH": str(codex_worker_errors_sidecar),
@@ -758,6 +804,7 @@ def compute_run_paths(
         ("APPROVAL_DECISIONS_RELATIVE_PATH", approval_decisions),
         ("DESIGN_PREPARATION_RELATIVE_PATH", design_preparation),
         ("PLAN_BODY_VERIFICATION_STATE_RELATIVE_PATH", plan_body_verification),
+        ("INCREMENTAL_DECISION_STATE_RELATIVE_PATH", incremental_decision),
         ("RUN_ERRORS_LOG_RELATIVE_PATH", run_errors_log),
         ("CLAUDE_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", claude_worker_errors_sidecar),
         ("CODEX_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", codex_worker_errors_sidecar),
@@ -767,3 +814,24 @@ def compute_run_paths(
     ]
     rel_paths = {key: _rel(project_root, target) for key, target in rel_pairs}
     return {**abs_paths, **rel_paths}
+
+
+# ---- task-root 에서 역산하는 순수 경로 계산 ----------------------------
+# task_target 에 있었다. 그 모듈은 okstra_project 를 끌어오므로, 이 두 함수만
+# 필요한 stage_map·stage_ledger 가 okstra_project 를 통째로 딸려오게 했다.
+
+def infer_project_root(task_root: Path) -> Path:
+    parts = task_root.parts
+    if ".okstra" not in parts:
+        return task_root
+    # The okstra subtree (.okstra/tasks/...) introduces the deepest ".okstra"
+    # segment; a project checked out under a path that itself contains
+    # ".okstra" must not resolve to that outer segment.
+    idx = len(parts) - 1 - parts[::-1].index(".okstra")
+    return Path(*parts[:idx]).resolve()
+
+def project_rel(path: Path, project_root: Path) -> str:
+    try:
+        return str(path.resolve().relative_to(project_root.resolve()))
+    except ValueError:
+        return str(path)

package/runtime/python/okstra_ctl/plan_items.py

@@ -294,21 +294,11 @@ def _extract_prep_items(
 ) -> None:
     if not planning.get("stages"):
         return
-    detection_input = planning
-    if planning.get("planningContract") == _SELECTED_DIRECTION_CONTRACT:
-        realization = planning.get("directionRealization")
-        if not isinstance(realization, Mapping):
-            raise PlanItemContractError("directionRealization must be an object")
-        detection_input = dict(planning)
-        detection_input["optionCandidates"] = [
-            {
-                "name": "Selected Direction",
-                "fileStructure": realization.get("fileStructure") or [],
-            }
-        ]
-        detection_input["recommendedOption"] = {"name": "Selected Direction"}
+    # 계약 분기는 탐지기가 안다(`design_surfaces._planned_file_structure`).
+    # 여기서 레거시 모양을 흉내 내 넘기던 동안 그 지식은 이 호출부에만 있었고,
+    # 같은 탐지기를 부르는 나머지 세 곳은 선택 방향 계획에서 실패했다.
     try:
-        triggers = detect_design_surfaces(detection_input)
+        triggers = detect_design_surfaces(planning)
     except (DesignSurfaceError, TypeError, AttributeError) as exc:
         raise PlanItemContractError(f"design-surface detection failed: {exc}") from exc
     for trigger in triggers:
@@ -658,6 +648,55 @@ def is_critic_worker(worker: str) -> bool:
     return name == CRITIC_WORKER_ID or name.endswith("-critic-worker")
 
 
+def analyser_key(worker: str) -> str:
+    """`codex` 와 `codex-worker` 는 같은 분석자다."""
+    name = str(worker or "").strip()
+    return name[: -len("-worker")] if name.endswith("-worker") else name
+
+
+def voting_analyser_keys(items: Sequence[Mapping[str, Any]]) -> set[str]:
+    """`participatingAnalysers.voting` 의 유일한 계산.
+
+    게이트 산술의 분모다 — 두 표의 과반과 세 표의 과반은 다른 주장이므로,
+    이 run 에서 판정을 남긴 서로 다른 분석자를 항목·라운드를 가리지 않고
+    센다. 빠지는 둘: 결과를 못 낸 워커(`verification-error`)는 게이트 산술에
+    들어가지 않고, critic 은 다수결에 참여하지 않고 짝수 분할만 가르며
+    로스터(`workerAssignments`)에도 없어 `rostered` 에 잡히지 않는다.
+
+    생산자(`okstra plan-items complete-round`)와 검증기
+    (`validators/validate-run.py` `_validate_participating_analysers`)가 같은
+    함수를 부른다. 종전에는 생산자가 이번 라운드 디스패치 큐의 표만 세고
+    검증기가 전 항목·전 라운드를 다시 세서, critic 이 동수만 가른 라운드에서
+    기록값과 재계산값이 갈렸다.
+    """
+    keys: set[str] = set()
+    for item in items:
+        if not isinstance(item, Mapping):
+            continue
+        for worker, token in _item_votes(item):
+            if token == "verification-error" or is_critic_worker(worker):
+                continue
+            key = analyser_key(worker)
+            if key and key != analyser_key(CRITIC_WORKER_ID):
+                keys.add(key)
+    return keys
+
+
+def critic_is_rostered(run_manifest: Mapping[str, Any]) -> bool:
+    """이 run 이 critic 슬롯을 실제로 배정했는가.
+
+    정본은 `invocationAssignments` 다 — run 이 해소한 critic 을 적는 곳이고
+    (`okstra_ctl.render._optional_worker_roles`), `critic/*` 항목이 없으면
+    critic 이 없다. `workerAssignments` 로는 판정할 수 없다: critic 은 분석
+    워커 로스터에서 제외되므로(`okstra_ctl.run._analysis_worker_rows`)
+    rostered 여부와 무관하게 그 배열에 나타나지 않는다.
+    """
+    assignments = run_manifest.get("invocationAssignments")
+    if not isinstance(assignments, Mapping):
+        return False
+    return any(str(ref).startswith("critic/") for ref in assignments)
+
+
 def tie_vote_item_ids(
     items: Sequence[Mapping[str, Any]],
     ledger: Mapping[str, str] | None,
@@ -702,6 +741,58 @@ CRITIC_TIE_PREAMBLE = (
     "settles the split. Do not re-open items that are not listed.\n"
 )
 
+# 라운드 2+ 는 직전 라운드의 반대 의견을 해결하려고 존재한다. 그 의견을 프롬프트가
+# 싣지 않으면 반대한 워커는 자기 판정을 그대로 다시 적고 동료는 근거 없이 다시
+# 판단하므로, 루프가 예산을 같은 분할을 재도출하는 데 쓴다.
+REVERIFY_PREAMBLE = (
+    "This is a re-verification round. Each item below carries a "
+    "**Prior round dissent** block: what the previous round's verifiers said "
+    "about that item, and what the planner changed in response. Read that "
+    "block before judging the CURRENT text. If you raised the prior objection "
+    "and still DISAGREE, state what you re-opened after the rewrite and why "
+    "the correction is insufficient — restating your previous explanation "
+    "without engaging the correction is not a valid verdict. If the correction "
+    "resolves your objection, say so and AGREE. Add one line per item to your "
+    "response, directly under **Verdict**:\n"
+    "**Prior dissent**: resolved | unresolved | none — <which prior objection, "
+    "and what the current text does about it>\n"
+)
+
+
+# 파서(`verdict_blocks._ITEM_RE` / `_FIELD_RE`)가 읽을 수 있는 응답 형식.
+# 정본 서술은 plan-body-verification.md §"Response format" 이지만 전달 채널은
+# 이 출력이다 — 큐는 모든 검증자 프롬프트에 verbatim 으로 실리는 유일한
+# 조각이라, 여기 실린 블록은 리드가 프롬프트를 어떻게 손 조립하든 도달한다.
+# 두 실측 실패 모양(`## <id>` 2해시 헤딩, `**Verdict:** AGREE` 굵게 안 콜론)을
+# 본문이 직접 금지한다.
+PLAN_VERIFY_RESPONSE_FORMAT = (
+    "\n## Response format\n"
+    "\n"
+    "Answer with one block per plan item in the queue above, headed by the "
+    "item's own id at exactly three hashes (`### P-...`). The collector parses "
+    "`^### ` and nothing else — a block at any other depth is not an unparsed "
+    "block; it is a verdict that was never recorded, and the round is scored "
+    "on the items that remain. Field labels keep the colon outside the bold: "
+    "`**Verdict**: AGREE`, never `**Verdict:** AGREE`.\n"
+    "\n"
+    "### <item-id>\n"
+    "**Verdict**: AGREE | DISAGREE(<a|b|c|d|e|f>) | SUPPLEMENT | UNVERIFIABLE\n"
+    "**Fixability** (only when DISAGREE): planner-fixable | needs-user-input\n"
+    "**Claim** (only on DISAGREE(a), or DISAGREE(f) on a P-Req item): "
+    "fact | judgement\n"
+    "**Probe** (only when Claim is fact): <one line of JSON, e.g. "
+    '{"kind": "path-absent", "path": "src/missing.ts"}>\n'
+    "**Note**: <the falsification candidate considered and why it is "
+    "excluded; required even for AGREE>\n"
+    "**Explanation**: <2-3 sentences>\n"
+)
+
+
+def with_response_format(queue_markdown: str) -> str:
+    """큐 본문 뒤에 응답 형식 블록을 덧붙인다. run 003 실측: 리드가 손 조립
+    중 이 블록을 빼먹어 검증자 2명의 판정 32건 전부가 형식 불일치로 버려졌다."""
+    return queue_markdown.rstrip("\n") + "\n" + PLAN_VERIFY_RESPONSE_FORMAT
+
 
 def item_cites_build_command(item: Mapping[str, Any]) -> bool:
     """이 항목이 계획 워크트리에서 실행 불가한 빌드/테스트 명령을 인용하는가."""
@@ -826,8 +917,18 @@ class NextDispatch:
 def next_dispatch(
     items: Sequence[Mapping[str, Any]],
     payloads: Mapping[str, Mapping[str, Any]] | None = None,
+    *,
+    critic_rostered: bool = True,
 ) -> NextDispatch:
-    """환경 전용 UNVERIFIABLE 은 전체 라운드를 만들지 않는다. 일괄 오류만 그 워커."""
+    """환경 전용 UNVERIFIABLE 은 전체 라운드를 만들지 않는다. 일괄 오류만 그 워커.
+
+    ``critic_rostered`` 가 거짓이면 미해결 1대1 은 `user-decision` 이다 —
+    critic 이 없는 로스터에는 라운드 안에서 동수를 가를 표가 존재하지 않고,
+    또 한 라운드를 도는 것은 같은 두 분석자에게 같은 분할을 다시 시키는
+    일이다. 호출자가 로스터를 모를 때(run manifest 없이 부를 때)는 종전대로
+    `critic-tie` 다: critic 이 있는 run 을 사용자 결정으로 보내는 쪽이 더
+    나쁜 오답이다.
+    """
     assigned = tuple(
         str(item["id"]) for item in items
         if isinstance(item.get("id"), str) and item["id"]
@@ -847,13 +948,23 @@ def next_dispatch(
         str(item["id"]) for item in items
         if isinstance(item.get("id"), str) and _is_tie(item)
     )
-    if ties:
+    if ties and critic_rostered:
         return NextDispatch(
             kind="critic-tie",
             workers=(CRITIC_WORKER_ID,),
             item_ids=ties,
             reason="unsettled analyser tie; critic settles",
         )
+    if ties:
+        return NextDispatch(
+            kind="user-decision",
+            workers=(),
+            item_ids=ties,
+            reason=(
+                "unsettled analyser tie and no rostered critic; open one "
+                "approval decision per item"
+            ),
+        )
     return NextDispatch(
         kind="none", workers=(), item_ids=(),
         reason="no worker batch",
@@ -869,3 +980,8 @@ def critic_tie_prompt_text(queue_markdown: str) -> str:
     """동수 critic 프롬프트. 가르는 지시가 큐보다 앞이다."""
     return f"{CRITIC_TIE_PREAMBLE.rstrip()}\n\n{queue_markdown.lstrip()}"
 
+
+def reverify_prompt_text(queue_markdown: str) -> str:
+    """라운드 2+ 프롬프트. 직전 반대 의견을 읽으라는 지시가 큐보다 앞이다."""
+    return f"{REVERIFY_PREAMBLE.rstrip()}\n\n{queue_markdown.lstrip()}"
+