okstra 0.69.0 → 0.71.0

package/runtime/python/okstra_ctl/run.py

@@ -291,6 +291,10 @@ class PrepareInputs:
     # prepare-time 에 task-level conformance 매니페스트 entry.waiver 를 채운다.
     qa_waiver: str = ""
     stage: str = "auto"
+    # release-handoff 전용: PR 로 내보낼 stage 묶음 (csv, 예: "2,3"). 빈 값 =
+    # whole-task 모드. `--stage`(impl/fv 의 Stage Map 실행/검증 선택)와는
+    # 별개 채널이다.
+    stages: str = ""
     clarification_response_path: str = ""  # absolute or empty
     # release-handoff 전용: PR 본문 템플릿 1회성 override. 빈 문자열이면
     # project.json → global config → 스킬 디폴트 순으로 해석된다.
@@ -1064,7 +1068,17 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     를 검증하고, implementation 일 때 stage map 을 파싱해 돌려준다 (그 외엔 빈 리스트)."""
     if not project_root.is_dir():
         raise PrepareError(f"project root not found: {project_root}")
-    if not inp.brief_path.is_file():
+    if inp.stages and inp.task_type != "release-handoff":
+        raise PrepareError(
+            "--stages is only meaningful with --task-type release-handoff; "
+            f"got {inp.task_type}"
+        )
+    if inp.task_type == "release-handoff":
+        # brief 는 entry phase 의 입력물 — release-handoff 는 검증 보고서를
+        # 인용하는 input 문서를 prepare 가 직접 생성해 brief 자리에 채운다
+        # (_materialize_release_handoff_input, 이 검증 직후 실행).
+        pass
+    elif not inp.brief_path.is_file():
         raise PrepareError(f"task brief not found: {inp.brief_path}")
     ctx_stage_map: list = []
     # implementation 과 final-verification 은 둘 다 승인된 plan 의 Stage Map 을
@@ -1121,7 +1135,9 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
                 "--implementation-option is only meaningful with --task-type "
                 "implementation and --approved-plan <path>"
             )
-        if inp.stage != "auto":
+        # wizard 는 모든 flag 를 빈 값 포함 항상 전달하므로(`--stage ""`),
+        # 빈 문자열은 "stage 미지정" 으로 받아들인다.
+        if inp.stage not in ("", "auto"):
             raise PrepareError(
                 "--stage is only meaningful with --task-type implementation or "
                 f"final-verification; got {inp.task_type}"
@@ -1133,6 +1149,113 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     return ctx_stage_map
 
 
+def _collect_handoff_source_report_rows(
+    rows: list, nums: list,
+) -> list:
+    """선택 stage 들의 마지막 verified 행에서 인용 표 행을 만든다 (last-wins)."""
+    last_verified: dict = {}
+    for r in rows:
+        if r.get("status") == "verified" and isinstance(r.get("stage"), int):
+            last_verified[r["stage"]] = r
+    return [
+        f"| {n} | {last_verified[n].get('report_path', '')} "
+        f"| `{last_verified[n].get('verdict', '')}` |"
+        for n in nums
+    ]
+
+
+def _materialize_release_handoff_input(
+    workspace_root: Path, project_root: Path, inp: "PrepareInputs",
+) -> dict:
+    """release-handoff 의 입력 문서를 검증 보고서 인용으로 자동 생성한다.
+
+    brief 는 entry phase 의 입력물이라 release-handoff 에는 없다 — 이 run 의
+    `--task-brief` 자리는 여기서 생성된 input 문서가 채운다. stage 자격은
+    okstra_ctl.handoff 의 SSOT 판정을 prepare 에서도 그대로 강제한다.
+    반환: ctx 에 올릴 {"HANDOFF_MODE": ..., "HANDOFF_STAGES": ...}."""
+    from .consumers import read_consumers
+    from .handoff import (HandoffError, _require_eligible,
+                          latest_whole_task_fv_accepted)
+    from .paths import task_dir
+    from .render import render_template_with_ctx
+    from .run_context import _now_task_date
+
+    # Path("") 는 "." 로 정규화된다 — 빈 brief 센티널은 둘 다로 들어올 수 있다.
+    if str(inp.brief_path).strip() not in ("", "."):
+        raise PrepareError(
+            "--task-brief is not accepted for --task-type release-handoff — "
+            "the input document is generated from the cited final-verification "
+            "reports (pick stages via --stages, or leave it empty for "
+            "whole-task)"
+        )
+    if not inp.approved_plan_path:
+        raise PrepareError(
+            "release-handoff requires --approved-plan "
+            "<implementation-planning final-report> — the Stage Map and the "
+            "consumers ledger drive stage eligibility"
+        )
+    plan = Path(inp.approved_plan_path)
+    if not plan.is_file():
+        raise PrepareError(f"approved plan not found: {plan}")
+    stage_map = _parse_stage_map_into_ctx(str(plan))
+    if not stage_map:
+        raise PrepareError(f"approved plan has no parsable Stage Map: {plan}")
+    rows = read_consumers(plan.resolve().parents[1])
+
+    if inp.stages:
+        try:
+            nums = sorted({int(x) for x in inp.stages.split(",") if x.strip()})
+        except ValueError:
+            raise PrepareError(
+                f"--stages must be a comma-separated int list, got {inp.stages!r}"
+            )
+        if not nums:
+            raise PrepareError("--stages must select at least one stage")
+        try:
+            _require_eligible(stage_map, rows, nums)
+        except HandoffError as exc:
+            raise PrepareError(str(exc)) from exc
+        mode = "stage-group"
+        stages_csv = ",".join(str(n) for n in nums)
+        report_rows = _collect_handoff_source_report_rows(rows, nums)
+    else:
+        report = latest_whole_task_fv_accepted(
+            project_root, inp.project_id, inp.task_group, inp.task_id)
+        if not report:
+            raise PrepareError(
+                "whole-task release-handoff requires an accepted whole-task "
+                "final-verification report — run final-verification first, "
+                "or pass --stages <csv> for a stage-group PR"
+            )
+        mode = "whole-task"
+        stages_csv = ""
+        report_relative = relative_to_project_root(Path(report), project_root)
+        report_rows = [f"| (all) | {report_relative or report} | `accepted` |"]
+
+    template = (workspace_root / "templates" / "reports"
+                / "release-handoff-input.template.md")
+    if not template.is_file():
+        raise PrepareError(
+            f"release-handoff input template missing: {template}.{_INSTALL_HINT}"
+        )
+    out = (task_dir(project_root, inp.task_group, inp.task_id)
+           / "release-handoff-input.md")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    render_template_with_ctx(str(template), str(out), {
+        "TASK_KEY": f"{inp.project_id}:{inp.task_group}:{inp.task_id}",
+        "TASK_ID": inp.task_id,
+        "TASK_GROUP": inp.task_group,
+        "PROJECT_ID": inp.project_id,
+        "TASK_TYPE": inp.task_type,
+        "TASK_DATE": _now_task_date(),
+        "HANDOFF_MODE": mode,
+        "HANDOFF_STAGES": stages_csv or "(all)",
+        "HANDOFF_SOURCE_REPORTS": "\n".join(report_rows),
+    })
+    inp.brief_path = out
+    return {"HANDOFF_MODE": mode, "HANDOFF_STAGES": stages_csv}
+
+
 def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> None:
     """`--qa-waiver` 가 있으면 task-level 매니페스트 entry 의 waiver 를 채운다."""
     if not inp.qa_waiver:
@@ -1822,6 +1945,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     final_report_template = assets.final_report_template
     ctx_stage_map = _validate_prepare_inputs(project_root, inp)
 
+    # release-handoff: 검증 보고서 인용 input 문서를 생성해 brief 자리에 채운다.
+    # 이후의 모든 brief 소비 경로(material/instruction-set 복사)는 그대로 동작한다.
+    handoff_tokens = {"HANDOFF_MODE": "", "HANDOFF_STAGES": ""}
+    if inp.task_type == "release-handoff":
+        handoff_tokens = _materialize_release_handoff_input(
+            workspace_root, project_root, inp)
+
     verify_installation(workspace_root)
     _register_and_check_project(project_root, inp)
 
@@ -1868,7 +1998,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     ):
         if inp.task_type == "final-verification" and inp.stage and inp.stage != "auto":
             worktree = _single_stage_final_verification_worktree(inp)
+            # Single-stage final-verification namespaces its run path under
+            # runs/final-verification/stage-<N> (same isolation as
+            # implementation) so concurrent per-stage verifications never
+            # share state/reports/worker-results.
+            fv_stage_arg = int(inp.stage)
         else:
+            fv_stage_arg = None
             try:
                 worktree = provision_task_worktree(
                     task_type=inp.task_type,
@@ -1890,8 +2026,9 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         # lands in runs/implementation/stage-<N>. The registry stage-key is
         # reserved exactly once here (inside provision_stage_worktree), and
         # the surrounding mutex makes the registry read in stage selection
-        # and that reserve atomic. Non-implementation task-types skip this
-        # entirely → stage_arg stays None → identical paths.
+        # and that reserve atomic. Other task-types skip this selection;
+        # single-stage final-verification threads its explicit stage via
+        # fv_stage_arg, everything else keeps stage_arg=None (flat paths).
         if inp.task_type == "implementation":
             impl_stage_selection = _select_and_provision_implementation_stage(
                 inp, ctx_stage_map, task_group_segment, task_id_segment,
@@ -1904,7 +2041,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             _clear_stale_stage_waiver(inp, project_root, impl_stage_selection.stage)
         else:
             impl_stage_selection = None
-            stage_arg = None
+            stage_arg = fv_stage_arg
 
     ctx = compute_and_write_run_context(
         workspace_root=workspace_root, project_root=project_root,
@@ -1982,6 +2119,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "RECOMMENDED_ANALYSERS": selected_reviewers,
         "PR_TEMPLATE_PATH": pr_template_path_str,
         "PR_TEMPLATE_SOURCE": pr_template_source,
+        **handoff_tokens,
         "CLAUDE_SESSION_ID": claude_session_id,
         "CLARIFICATION_RESPONSE_PATH": inp.clarification_response_path,
         "CLARIFICATION_RESPONSE_RELATIVE_PATH": clarification_relative,
@@ -2106,7 +2244,14 @@ def main(argv: list[str]) -> int:
     p.add_argument("--task-group", required=True)
     p.add_argument("--task-id", required=True)
     p.add_argument("--task-type", required=True)
-    p.add_argument("--task-brief", required=True, dest="task_brief")
+    p.add_argument(
+        "--task-brief", default="", dest="task_brief",
+        help=(
+            "Required for every task-type except release-handoff (whose input "
+            "document is generated by prepare from the cited "
+            "final-verification reports)."
+        ),
+    )
     p.add_argument("--directive", default="")
     p.add_argument("--workers", default="", dest="workers_override")
     p.add_argument("--lead-model", default="")
@@ -2128,6 +2273,15 @@ def main(argv: list[str]) -> int:
             "consumers.jsonl status:done. Numeric '<N>' = force that stage."
         ),
     )
+    p.add_argument(
+        "--stages", default="", dest="stages",
+        help=(
+            "release-handoff only. Comma-separated stage numbers to bundle "
+            "into one PR (stage-group mode); empty = whole-task mode. "
+            "Distinct from --stage (implementation/final-verification "
+            "Stage Map selection)."
+        ),
+    )
     p.add_argument(
         "--approve",
         action="store_true",
@@ -2199,10 +2353,22 @@ def main(argv: list[str]) -> int:
     args = p.parse_args(argv)
 
     project_root = Path(args.project_root).expanduser().resolve()
-    brief_abs = resolve_user_file(args.task_brief, project_root)
-    if brief_abs is None:
-        print(f"task brief not found: {args.task_brief}", file=__import__("sys").stderr)
-        return 1
+    if args.task_type == "release-handoff":
+        if args.task_brief:
+            print(
+                "--task-brief is not accepted for --task-type release-handoff "
+                "— the input document is generated from the cited "
+                "final-verification reports",
+                file=__import__("sys").stderr,
+            )
+            return 1
+        brief_abs = Path("")  # prepare 가 input 문서를 생성해 채운다
+    else:
+        brief_abs = resolve_user_file(args.task_brief, project_root)
+        if brief_abs is None:
+            print(f"task brief not found: {args.task_brief}",
+                  file=__import__("sys").stderr)
+            return 1
     clarification_abs = ""
     if args.clarification_response_path:
         cr = resolve_user_file(args.clarification_response_path, project_root)
@@ -2237,6 +2403,7 @@ def main(argv: list[str]) -> int:
         approved_plan_path=args.approved_plan_path,
         qa_waiver=args.qa_waiver,
         stage=args.stage,
+        stages=args.stages,
         clarification_response_path=clarification_abs,
         pr_template_path=args.pr_template_path,
         render_only=args.render_only,