okstra 0.196.0 → 0.197.0

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]:
@@ -5058,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="",
@@ -5323,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

@@ -18,10 +18,10 @@ _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"),
 )
 
 # 파일 사본이 담는 워커 진행 줄의 상한. 진행은 워커 출력의 부피가 몰리는
@@ -99,7 +99,7 @@ class SessionTranscript:
             self._keep(self._row(speaker, line), capped=True)
 
     def _row(self, speaker: str, line: str) -> str:
-        label = f"[{speaker}] "
+        label = f"[{speaker}]"
         return f"{self._clock()} {label}{line}".rstrip()
 
     def _show(self, row: str, line: str) -> None:

package/runtime/python/okstra_ctl/stage_close.py

@@ -0,0 +1,244 @@
+"""`okstra stage-close` — 이미 랜딩한 stage 를 기록만 남겨 done 으로 닫는다.
+
+stage 완료의 정본은 `runs/implementation-planning/consumers.jsonl` 의 `done`
+행이고, 그 행은 두 경로로만 생겼다: implementation run 이 정상 종료하거나,
+`backfill_done_from_carry` 가 carry 사이드카에서 복원하거나. 두 경로 모두
+없는 상태가 실재한다 — 제품 변경은 커밋되고 conformance 결과도 PASS 인데
+run 이 carry 를 쓰기 전에 끝난 경우다. 그러면 `stage-map` 은 `doneStages: []`
+을 보고하고, 다음 계획은 아무 일도 없었던 것처럼 그 stage 를 다시 쓰며, 거기서
+나오는 RED 기대는 전부 도달 불가다(실측 2026-09-10, fontsninja-v3-site
+dev-10628-3: 마지막 행이 `started`, carry 디렉터리는 빈 폴더, stage 결과는
+`overall: PASS`).
+
+이 명령은 그 복구 경로다. 커밋과 conformance 결과라는 두 증거를 확인한 뒤
+done 행을 append 한다 — 증거 없이 닫는 수단은 아니다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+from pathlib import Path
+
+from okstra_project import (
+    ResolverError,
+    StateError,
+    resolve_project_root,
+    resolve_task_identity,
+)
+
+from .conformance import (
+    conformance_result_file,
+    decide_conformance_gate,
+    qa_result_from_dict,
+)
+from .consumers import append_consumer, last_lifecycle_status_by_stage, read_consumers
+from .json_boundary import JsonBoundaryError, load_owned_object
+from .paths import RunRef, task_conformance_manifest_file, task_qa_dir
+from .stage_map import StageMapError, load_latest_plan_stage_map
+
+# 이 status 를 이미 가진 stage 는 리드가 판정을 내린 것이다. 되쓰기는 그 판정을
+# 덮는 일이므로 여기서 하지 않는다.
+_SETTLED = ("done", "failed")
+
+
+def _git_commit_exists(repo_root: Path, commit: str) -> bool:
+    probe = subprocess.run(
+        ["git", "-C", str(repo_root), "cat-file", "-e", f"{commit}^{{commit}}"],
+        capture_output=True,
+    )
+    return probe.returncode == 0
+
+
+def _manifest_entry(task_root: Path, stage: int) -> dict | None:
+    """이 stage 의 conformance entry, 선언이 없으면 None.
+
+    stageKey 의 `<task-id>` 는 planning 이 쓴 원문이라 디렉터리 segment 와 표기가
+    다를 수 있으므로 `-stage-<N>` 접미사로 맞춘다 — `_clear_stale_stage_waiver`
+    와 같은 규칙이다.
+    """
+    path = task_conformance_manifest_file(task_root)
+    if not path.is_file():
+        return None
+    try:
+        manifest = load_owned_object(path, artifact="conformance manifest")
+    except JsonBoundaryError as exc:
+        raise StateError(str(exc), stage="conformance") from exc
+    entries = manifest.get("entries")
+    if not isinstance(entries, list):
+        return None
+    suffix = f"-stage-{stage}"
+    return next(
+        (
+            entry for entry in entries
+            if isinstance(entry, dict)
+            and isinstance(entry.get("stageKey"), str)
+            and entry["stageKey"].endswith(suffix)
+        ),
+        None,
+    )
+
+
+def _conformance_state(task_root: Path, stage: int) -> tuple[bool, str]:
+    """(닫아도 되는가, 사람이 읽는 근거).
+
+    선언 자체가 없으면 게이트할 것이 없다. 있으면 그 stage 의 결과 사이드카로
+    `decide_conformance_gate` 를 그대로 돌린다 — 검증기가 쓰는 것과 같은 판정
+    함수라, 여기서 통과한 stage 는 검증기에서도 통과한다.
+    """
+    entry = _manifest_entry(task_root, stage)
+    if entry is None:
+        return True, "no conformance entry declared for this stage"
+    key = str(entry.get("stageKey"))
+    sidecar = conformance_result_file(task_qa_dir(task_root), key)
+    result = None
+    if sidecar.is_file():
+        try:
+            result = qa_result_from_dict(
+                load_owned_object(sidecar, artifact="conformance result")
+            )
+        except JsonBoundaryError:
+            # 읽을 수 없는 결과는 결과가 아니다 — MISSING 으로 게이트에 넘겨
+            # 판정을 `decide_conformance_gate` 가 내리게 한다. 검증기도 같다.
+            result = qa_result_from_dict(None)
+    verdict = decide_conformance_gate(entry, result)
+    return verdict.ok, f"{verdict.status}: {verdict.message}"
+
+
+def close_stage(
+    project_root: Path, task_key: str, stage: int, head_commit: str,
+) -> dict:
+    """stage 를 done 으로 닫고 그 근거를 함께 돌려준다."""
+    identity = resolve_task_identity(project_root, task_key)
+    task_root = Path(identity["taskRoot"])
+    plan_run_root = RunRef.from_task_root(task_root, "implementation-planning").run_dir
+    if not plan_run_root.is_dir():
+        raise StateError(
+            f"this task has no implementation-planning run at {plan_run_root} — "
+            "there is no Stage Map to close a stage of",
+            stage="plan-run",
+        )
+
+    try:
+        stage_map = load_latest_plan_stage_map(task_root)
+    except StageMapError as exc:
+        raise StateError(str(exc), stage=exc.code) from exc
+    known = sorted(
+        row["stage_number"] for row in stage_map.stages
+        if isinstance(row, dict) and isinstance(row.get("stage_number"), int)
+    )
+    if stage not in known:
+        raise StateError(
+            f"stage {stage} is not in this task's Stage Map (has {known or 'none'})",
+            stage="stage-map",
+        )
+
+    recorded = last_lifecycle_status_by_stage(read_consumers(plan_run_root))
+    if recorded.get(stage) in _SETTLED:
+        raise StateError(
+            f"stage {stage} is already recorded {recorded[stage]!r} — a lead's "
+            "ruling is not rewritten here",
+            stage="consumers",
+        )
+
+    if not _git_commit_exists(project_root, head_commit):
+        raise StateError(
+            f"{head_commit} is not a commit in {project_root} — pass the commit "
+            "the stage's work actually landed as",
+            stage="git",
+        )
+
+    ok, conformance = _conformance_state(task_root, stage)
+    if not ok:
+        raise StateError(
+            f"stage {stage} conformance does not permit closing it "
+            f"({conformance}) — run the stage's conformance script, or record a "
+            'user waiver with prepare `--qa-waiver "<stageKey>:<reason>"`, '
+            "before closing the stage",
+            stage="conformance",
+        )
+
+    append_consumer(
+        plan_run_root,
+        impl_task_key=identity["taskKey"],
+        stage=stage,
+        status="done",
+        head_commit=head_commit,
+        closed_by="stage-close",
+    )
+    return {
+        "taskKey": identity["taskKey"],
+        "taskRoot": str(task_root),
+        "stage": stage,
+        "headCommit": head_commit,
+        "conformance": conformance,
+        "consumersPath": str(plan_run_root / "consumers.jsonl"),
+    }
+
+
+_CLI_EPILOG = r"""Usage:
+  okstra stage-close <task-key> --stage <N> --from-commit <sha>
+  okstra stage-close <task-key> --stage <N> --from-commit <sha> --project <dir>
+
+Records the `done` row an implementation run would have written, for a stage
+whose work is already committed but which never registered as done (the run
+ended before writing its carry sidecar). Refuses unless the Stage Map has that
+stage, no `done`/`failed` row exists for it, `--from-commit` resolves to a
+commit in the project repo, and the stage's conformance gate permits progress.
+
+Output: JSON { ok, taskKey, taskRoot, stage, headCommit, conformance,
+consumersPath }. Exit 1 on a refusal (the reason names what to do), 2 when
+PROJECT_ROOT cannot be resolved.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Close an already-landed implementation stage as done.",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra stage-close")
+    parser.add_argument("task_key", metavar="task-key",
+                        help="project-id:task-group:task-id")
+    parser.add_argument("--stage", type=int, required=True,
+                        help="the Stage Map number to close")
+    parser.add_argument("--from-commit", required=True, dest="from_commit",
+                        help="the commit the stage's work landed as")
+    parser.add_argument("--project-root", "--project", default="",
+                        help="use this directory as PROJECT_ROOT")
+    parser.add_argument("--cwd", default=".",
+                        help="resolve PROJECT_ROOT starting from here")
+    args = parser.parse_args(argv)
+
+    def emit(payload: dict) -> None:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+    try:
+        resolved = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+    except ResolverError as exc:
+        emit({"ok": False, "stage": "resolve", "reason": str(exc)})
+        return 2
+
+    if args.stage < 1:
+        emit({"ok": False, "stage": "stage-map",
+              "reason": f"--stage must be a positive integer, got {args.stage}"})
+        return 1
+
+    try:
+        closed = close_stage(
+            Path(resolved), args.task_key, args.stage, args.from_commit.strip(),
+        )
+    except StateError as exc:
+        emit({
+            "ok": False,
+            "stage": getattr(exc, "stage", None) or "stage-close",
+            "reason": str(exc),
+        })
+        return 1
+
+    emit({"ok": True, **closed})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())