okstra 0.218.0 → 0.219.1

package/runtime/python/okstra_ctl/report_prose_keys.py

@@ -0,0 +1,153 @@
+"""Final-report leaf keys whose values a reader reads as prose and nothing else.
+
+A value under one of these keys is displayed text; ids, enum values, paths and
+anchor targets live under other keys.
+"""
+from __future__ import annotations
+
+PROSE_KEYS = frozenset({
+    "acceptance",
+    "action",
+    "actions",
+    "addedWork",
+    "alternativesConsidered",
+    "answer",
+    "approach",
+    "approvalDisposition",
+    "approvalEvidence",
+    "architectureBoundaries",
+    "assumptions",
+    "behavior",
+    "blastRadius",
+    "blockReason",
+    "blockedReason",
+    "blockers",
+    "body",
+    "boundary",
+    "briefEvidence",
+    "canonical",
+    "carryIn",
+    "causeSummary",
+    "change",
+    "check",
+    "claim",
+    "commitment",
+    "complexity",
+    "condition",
+    "confirmingSignal",
+    "conformanceExemption",
+    "consequences",
+    "constraint",
+    "context",
+    "coreMechanism",
+    "coreReason",
+    "counterevidence",
+    "decision",
+    "decisions",
+    "declinedFixRecommendations",
+    "description",
+    "details",
+    "directionChange",
+    "disagreement",
+    "discrepancy",
+    "disproveWith",
+    "environmentSetup",
+    "escalationTrigger",
+    "evidence",
+    "evidenceRequired",
+    "exemptionReaffirm",
+    "exemptionReason",
+    "exitContract",
+    "exitContractSummary",
+    "expected",
+    "expectedBehaviorAfter",
+    "expectedChangeAreas",
+    "expectedForm",
+    "expectedOutcome",
+    "expectedResult",
+    "expectedVerification",
+    "explanation",
+    "fact",
+    "failureHandling",
+    "falsifyingEvidenceChecked",
+    "finalConclusion",
+    "goal",
+    "guardrails",
+    "headline",
+    "howToStart",
+    "hypothesis",
+    "ifStillOpen",
+    "injectedAs",
+    "interfaces",
+    "item",
+    "justification",
+    "knownFacts",
+    "label",
+    "mitigation",
+    "motivation",
+    "name",
+    "need",
+    "nextStep",
+    "noVariationRationale",
+    "notApplicableReason",
+    "note",
+    "observableFailure",
+    "observed",
+    "option",
+    "outcome",
+    "outputSummary",
+    "performed",
+    "planItem",
+    "position",
+    "problem",
+    "question",
+    "rationale",
+    "readyWhen",
+    "reason",
+    "rejectedSummary",
+    "rejectingSignal",
+    "relation",
+    "replacedInTest",
+    "replacedWith",
+    "requestKind",
+    "requiredDecision",
+    "requiredWork",
+    "requirement",
+    "resolution",
+    "responsibility",
+    "reversibility",
+    "risk",
+    "rolloutCost",
+    "routingRecommendation",
+    "satisfaction",
+    "scope",
+    "selfFixNote",
+    "sliceValue",
+    "stageTitle",
+    "stageValidation",
+    "statement",
+    "suggestedAction",
+    "summary",
+    "supersededStatement",
+    "symptom",
+    "systemInterpretation",
+    "testCaseBoundary",
+    "testCaseFailure",
+    "testCaseSuccess",
+    "testCoverageCost",
+    "text",
+    "title",
+    "topic",
+    "trigger",
+    "triggerSignal",
+    "unblockCondition",
+    "userChoice",
+    "userConstraints",
+    "userInput",
+    "userText",
+    "verification",
+    "verificationMethod",
+    "verificationSignal",
+    "whyItMatters",
+    "workingAssumption",
+})

package/runtime/python/okstra_ctl/report_synthesis_packet.py

@@ -866,7 +866,7 @@ def _attempt_result_specs(
         for row in invocations_value
         if isinstance(row, Mapping) and _string(row.get("invocationRef"))
     }
-    excluded_duties = {"lead", "report-writer", "translator"}
+    excluded_duties = {"lead", "report-writer"}
     specs: list[tuple[str, str, str, bool]] = []
     seen: set[str] = set()
     for attempt in attempts_value:

package/runtime/python/okstra_ctl/run.py

@@ -1896,19 +1896,12 @@ def _build_static_execution_manifest(
     plan: AssignmentPlan,
     context: AssignmentContext,
     lead: ResolvedAssignment,
-    translator: ResolvedAssignment,
 ) -> ExecutionManifest:
     participants: list[ParticipantAssignment] = []
     roles: list[RoleExecution] = []
-    # The translator is resolved outside the role plan, like the lead, and both
-    # are named in `invocationAssignments`. Without a role execution here,
-    # `agent-prompt materialize --audience translator` has no canonical
-    # identity to bind to and refuses — so a `reportLanguage: ko` run could
-    # never write its translation sidecar and rendered the English source.
     assignments = (
         lead,
         *(row for row in plan.assignments if row.role != "leader"),
-        translator,
     )
     for index, assignment in enumerate(assignments, start=1):
         participant_ref = f"participant-{index:03d}"
@@ -2387,7 +2380,6 @@ class _ModelBindings:
     lead_assignment: RoleAssignment
     worker_assignments: tuple[RoleAssignment, ...]
     invocation_assignments: dict[str, dict[str, object]]
-    translator: ResolvedAssignment
 
 
 @dataclass(frozen=True)
@@ -2622,13 +2614,6 @@ def _project_model_bindings(
         if executor_rows
         else None
     )
-    translator = _model_for_role(
-        context=context,
-        provider=report_writer.provider_id,
-        raw_value=report_writer.model_id,
-        role="translator",
-        duty_id="translator",
-    )
     projections = {
         provider: _legacy_projection_from_plan(provider, plan, context)
         for provider in ("claude", "codex", "antigravity")
@@ -2637,7 +2622,6 @@ def _project_model_bindings(
         lead_assignment,
         workers,
         critic_assignment,
-        _role_assignment(resolved=translator, role="translator"),
         inp.task_type,
     )
     worker_by_provider = {row.provider: row for row in workers}
@@ -2668,7 +2652,6 @@ def _project_model_bindings(
         lead_assignment=lead_assignment,
         worker_assignments=workers,
         invocation_assignments=invocation_assignments,
-        translator=translator,
     )
 
 
@@ -2759,7 +2742,6 @@ def _build_invocation_assignments(
     lead: RoleAssignment,
     workers: tuple[RoleAssignment, ...],
     critic: RoleAssignment | None,
-    translator: RoleAssignment,
     task_type: str,
 ) -> dict[str, dict[str, object]]:
     assignments = {"lead": lead.to_model_payload()}
@@ -2776,7 +2758,6 @@ def _build_invocation_assignments(
         # role 라벨을 만들기 때문에 두 행의 이름이 겹쳐 validate-run 이
         # `duplicate worker role detected` 로 런을 실패시킨다.
         assignments[critic_assignment_ref(task_type)] = critic.to_model_payload()
-    assignments["translator"] = translator.to_model_payload()
     return assignments
 
 
@@ -3660,7 +3641,7 @@ def _allowed_agent_audiences(
     inp: PrepareInputs,
     models: _ModelBindings,
 ) -> list[str]:
-    audiences = {"lead", "translator"}
+    audiences = {"lead"}
     if models.worker_assignments:
         audiences.add("reverification-worker")
     if any(item.worker_id == "report-writer" for item in models.worker_assignments):
@@ -4162,7 +4143,6 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         assignment_plan,
         assignment_context,
         models.lead,
-        models.translator,
     )
     dynamic_roles = tuple(
         requirement.role

package/runtime/python/okstra_ctl/stage_integrate.py

@@ -283,8 +283,14 @@ def _teardown_all(project_id, task_group, task_id, task_wt: str,
 
 def _remove_clean_worktree(task_wt: str, wt: str, stage_n: int) -> tuple[str, str] | None:
     """clean stage worktree 를 물리 제거. dirty/실패면 (outcome, detail), 성공이면 None."""
-    from .worktree import is_dirty_excluding_okstra, remove_worktree_force
-
+    from .worktree import (
+        is_dirty_excluding_okstra,
+        nested_worktree_excludes,
+        remove_worktree_force,
+    )
+
+    if nested_worktree_excludes(wt):
+        return ("skipped", "nested worktrees remain — preserved")
     if is_dirty_excluding_okstra(wt):
         return ("skipped", "dirty — 미커밋 변경 보존")
     rm = remove_worktree_force(task_wt, wt)
@@ -293,6 +299,35 @@ def _remove_clean_worktree(task_wt: str, wt: str, stage_n: int) -> tuple[str, st
     return None
 
 
+def reclaim_completed_stage(
+    project_root: Path, project_id: str, task_group: str, task_id: str,
+    stage: int, expected_head: str, done: dict | None, status: str,
+) -> tuple[str, str]:
+    from . import worktree_registry
+    from .worktree import main_worktree_path
+
+    row = worktree_registry.get_stage_row(project_id, task_group, task_id, stage)
+    if not row:
+        return "skipped", "stage worktree is not registered"
+    if status != "done" or row.get("status") == "active":
+        return "skipped", "stage is unfinished or active"
+    if not expected_head or (done or {}).get("head_commit") != expected_head:
+        return "skipped", "completion commit does not match this report"
+    tip = _git(project_root, "rev-parse", "--verify", f"refs/heads/{row['branch']}")
+    if tip.returncode or tip.stdout.strip() != expected_head:
+        return "skipped", "stage branch moved after completion"
+    wt = Path(row["worktree_path"])
+    if wt.resolve() == main_worktree_path(project_root).resolve():
+        return "skipped", "main worktree is preserved"
+    if wt.exists():
+        current = _git(wt, "symbolic-ref", "--short", "HEAD")
+        if current.returncode or current.stdout.strip() != row["branch"]:
+            return "skipped", "worktree no longer holds the registered stage branch"
+    return _teardown_stage(
+        project_id, task_group, task_id, str(project_root), stage, row, expected_head,
+    )
+
+
 def _unmerged_branch_tip_warning(task_wt: str, stage_n: int, branch: str,
                                  verified_head: str = "") -> str:
     """Warn text when the stage branch tip is not an ancestor of the commit

package/runtime/python/okstra_ctl/stage_rebase.py

@@ -0,0 +1,189 @@
+"""선행 기준이 이동한 단계 브랜치를 의존 순서로 재배치한다."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import consumers, worktree_registry
+from .stage_targets import (
+    StageWorktreeIdentity,
+    order_stage_closure,
+    resolve_stage_base_commit,
+)
+from .worktree import is_ancestor
+from .worktree.rebase import _checked_git, rebase_stage_branch
+
+
+def _rebase_completed_stage(
+    project_root: Path,
+    plan_run_root: Path,
+    identity: StageWorktreeIdentity,
+    row: dict,
+    done_row: dict,
+    base: str,
+) -> dict:
+    number, branch = row["stage"], row["branch"]
+    tip = _checked_git(project_root, "rev-parse", f"refs/heads/{branch}")
+    if tip != done_row.get("head_commit"):
+        raise RuntimeError(
+            f"stage {number} branch moved beyond its done commit; reconcile it before rebasing"
+        )
+    head = rebase_stage_branch(project_root, branch, row["base_ref"], base)
+    worktree_registry.update_stage_base(
+        identity.project_id,
+        identity.task_group,
+        identity.task_id,
+        number,
+        expected_base=row["base_ref"],
+        base_ref=base,
+    )
+    consumers.append_consumer(
+        plan_run_root,
+        impl_task_key=done_row["impl_task_key"],
+        stage=number,
+        status="done",
+        force_reappend=True,
+        head_commit=head,
+        replaced_commit=tip,
+        reconciled=True,
+        reconcile_reason="dependency-rebase",
+        report_path=done_row.get("report_path", ""),
+    )
+    return {**done_row, "head_commit": head}
+
+
+def _refresh_predecessor_head(
+    root: Path,
+    plan: Path,
+    row: dict,
+    done_row: dict,
+    active: bool,
+) -> dict:
+    tip = _checked_git(root, "rev-parse", f"refs/heads/{row['branch']}")
+    previous = done_row["head_commit"]
+    if tip == previous:
+        return done_row
+    if active or not is_ancestor(root, previous, tip):
+        raise RuntimeError(
+            f"predecessor stage {row['stage']} is active or rewritten; finish or reconcile it first"
+        )
+    consumers.append_consumer(
+        plan,
+        impl_task_key=done_row["impl_task_key"],
+        stage=row["stage"],
+        status="done",
+        force_reappend=True,
+        head_commit=tip,
+        replaced_commit=previous,
+        reconciled=True,
+        reconcile_reason="predecessor-advance",
+        report_path=done_row.get("report_path", ""),
+    )
+    return {**done_row, "head_commit": tip}
+
+
+def synchronize_stage_stack(
+    *,
+    project_root: Path,
+    plan_run_root: Path,
+    stage_map: list[dict],
+    identity: StageWorktreeIdentity,
+) -> list[int]:
+    """호출자가 task-key provision 잠금을 잡은 상태에서 실행한다."""
+    rows = consumers.read_consumers(plan_run_root)
+    done = consumers.latest_done_by_stage(rows)
+    statuses = consumers.last_lifecycle_status_by_stage(rows)
+    anchor = (
+        worktree_registry.get_implementation_base(
+            identity.project_id,
+            identity.task_group,
+            identity.task_id,
+        )
+        or ""
+    )
+    graph = [(s["stage_number"], s.get("depends_on") or []) for s in stage_map]
+    order = order_stage_closure(graph, {n for n, _ in graph}, set())
+    if len(order) != len(graph):
+        raise RuntimeError("cannot synchronize a cyclic Stage Map")
+    by_number = {s["stage_number"]: s for s in stage_map}
+    predecessors = {dep for _, deps in graph for dep in deps}
+    changed = []
+    for number in order:
+        row = worktree_registry.get_stage_row(
+            identity.project_id,
+            identity.task_group,
+            identity.task_id,
+            number,
+        )
+        stage = by_number[number]
+        if not row or number not in done or stage.get("cancelled"):
+            continue
+        active = statuses.get(number) == "started" or row.get("status") == "active"
+        if _synchronize_recorded_stage(
+            project_root,
+            plan_run_root,
+            identity,
+            stage,
+            row,
+            done,
+            anchor,
+            active,
+            number in predecessors,
+        ):
+            changed.append(number)
+    return changed
+
+
+def _synchronize_recorded_stage(
+    root: Path,
+    plan: Path,
+    identity: StageWorktreeIdentity,
+    stage: dict,
+    row: dict,
+    done: dict[int, dict],
+    anchor: str,
+    active: bool,
+    predecessor: bool,
+) -> bool:
+    number = stage["stage_number"]
+    previous = done[number]["head_commit"]
+    if predecessor:
+        done[number] = _refresh_predecessor_head(root, plan, row, done[number], active)
+    if stage.get("depends_on"):
+        done[number] = _synchronize_dependent(
+            root,
+            plan,
+            identity,
+            stage,
+            row,
+            done,
+            anchor,
+            active,
+        )
+    return previous != done[number]["head_commit"]
+
+
+def _synchronize_dependent(
+    root: Path,
+    plan: Path,
+    identity: StageWorktreeIdentity,
+    stage: dict,
+    row: dict,
+    done: dict[int, dict],
+    anchor: str,
+    active: bool,
+) -> dict:
+    number = stage["stage_number"]
+    base = resolve_stage_base_commit(
+        stage,
+        list(done.values()),
+        anchor,
+        project_root=root,
+        plan_run_root=plan,
+        identity=identity,
+    )
+    if row["base_ref"] == base:
+        return done[number]
+    if active:
+        raise RuntimeError(f"cannot rebase active stage {number}; finish its run first")
+    return _rebase_completed_stage(root, plan, identity, row, done[number], base)

package/runtime/python/okstra_ctl/stage_targets.py

@@ -831,76 +831,43 @@ def containing_stage(project_root: Path,
     return single_containing_head(project_root, heads)
 
 
-def integrate_and_teardown_whole_task(
+def teardown_completed_stage_worktrees(
     *, project_root: Path, task_group: str, task_id: str,
+    expected_heads: dict[int, str] | None = None,
 ) -> dict[str, Any]:
-    """판정이 끝난 whole-task 검증의 stage worktree 와 registry 키를 회수한다.
-
-    진입은 통합만 하고 정리를 남겨 두므로(`phases/final_verification/target.py`), 정리는
-    판정 뒤인 Phase 7 에서 여기로 들어온다. 통합은 이미 끝나 있어 Phase A 는 전부
-    `already_merged` 로 지나가고 Phase B 만 실제 일을 한다. 두 번 불려도 결과는 같다 —
-    사라진 worktree 는 건너뛰고, 미커밋 변경이 남은 stage 트리는 보존한다.
-
-    stage_map 은 done 행에서 만든다. 정리 대상은 완료된 stage 뿐이고, 계획에만 있고
-    완료되지 않은 stage 는 Phase A 가 어차피 건너뛰기 때문이다.
-    """
+    """완료된 단계의 작업 트리만 회수하고 브랜치와 기준 기록은 보존한다."""
     from okstra_project.dirs import okstra_home, project_json_path
 
-    from . import consumers, worktree_registry
+    from . import consumers
     from .json_boundary import load_owned_object
     from .locks import worktree_provision_mutex
     from .paths import task_runs_dir
-    from .stage_integrate import integrate_stages
+    from .stage_integrate import reclaim_completed_stage
 
-    try:
-        project_id = load_owned_object(
-            project_json_path(project_root), artifact="project config"
-        ).get("projectId", "")
-    except (OSError, ValueError):
-        project_id = ""
+    config = project_json_path(project_root)
+    if not config.is_file():
+        return {"skipped": "project.json is missing"}
+    project_id = load_owned_object(config, artifact="project config").get("projectId", "")
     if not project_id:
         return {"skipped": "project.json declares no projectId"}
-
-    plan_run_root = task_runs_dir(
-        project_root, task_group, task_id
-    ) / "implementation-planning"
-    done_rows = [
-        row for row in consumers.read_consumers(plan_run_root)
-        if row.get("status") == "done"
-    ]
-    if not done_rows:
-        return {"skipped": "no done stage rows to reclaim"}
-    stage_map = [
-        {"stage_number": stage}
-        for stage in sorted(consumers.latest_done_by_stage(done_rows))
-    ]
-
-    entry = worktree_registry.lookup(project_id, task_group, task_id)
-    if entry is None:
-        return {"skipped": "task worktree is no longer registered"}
-
-    done_by_stage = consumers.latest_done_by_stage(done_rows)
-    tip = containing_stage(project_root, done_by_stage)
+    plan = task_runs_dir(project_root, task_group, task_id) / "implementation-planning"
+    removed, skipped, warnings = [], [], []
     with worktree_provision_mutex(okstra_home(), project_id, task_group, task_id):
-        result = integrate_stages(
-            project_id=project_id,
-            task_group=task_group,
-            task_id=task_id,
-            task_worktree_path=entry.worktree_path,
-            stage_map=stage_map,
-            done_rows=done_rows,
-            teardown=True,
-            # 한 stage 브랜치가 이미 전체를 담고 있으면 검증은 거기서 돌았다
-            # (`phases/final_verification/target.py`). 그 경우 task 브랜치로의 머지는 아무도
-            # 읽지 않는 산출물이므로 정리만 한다.
-            merge=tip is None,
-            verified_head=(done_by_stage.get(tip) or {}).get("head_commit", ""),
-        )
-    return {
-        "tornDown": result.torn_down,
-        "teardownSkipped": [
-            {"stage": stage, "reason": reason}
-            for stage, reason in result.teardown_skipped
-        ],
-        "warnings": result.warnings,
-    }
+        rows = consumers.read_consumers(plan)
+        done = consumers.latest_done_by_stage(rows)
+        statuses = consumers.last_lifecycle_status_by_stage(rows)
+        heads = expected_heads if expected_heads is not None else {
+            stage: row.get("head_commit", "") for stage, row in done.items()
+        }
+        for stage, head in sorted(heads.items()):
+            outcome, detail = reclaim_completed_stage(
+                project_root, project_id, task_group, task_id, stage, head,
+                done.get(stage), statuses.get(stage, ""),
+            )
+            if outcome == "torn_down":
+                removed.append(stage)
+            elif outcome == "skipped":
+                skipped.append({"stage": stage, "reason": detail})
+            else:
+                warnings.append(detail)
+    return {"tornDown": removed, "teardownSkipped": skipped, "warnings": warnings}

package/runtime/python/okstra_ctl/team.py

@@ -228,12 +228,7 @@ def _record_dispatch(args, manifest: Mapping[str, Any], prepared) -> list[str]:
 
 
 def team_dispatch_port(manifest: Mapping[str, Any]) -> WorkerDispatchPort:
-    """이 run 의 워커를 띄울 포트. cmux run 이면 pane, 아니면 리드 호스트의 포트.
-
-    `team dispatch` 와 finalize 의 `translate` 단계가 같이 쓴다 — 번역자만
-    CLI 래퍼 디스패처로 띄우던 동안 cmux run 에서도 번역자는 pane 없이 돌았다
-    (실측 2026-09-22, dev-10860 implementation-planning-001: 18건 중 번역자 1건).
-    """
+    """이 run 의 워커를 띄울 포트. cmux run 이면 pane, 아니면 리드 호스트의 포트."""
     lead_runtime = _require_string(manifest, "leadRuntime")
     fallback_port = default_host_registry().resolve(
         lead_runtime

package/runtime/python/okstra_ctl/wizard/confirmation.py

@@ -333,14 +333,6 @@ def confirmation_block(state: WizardState) -> str:
         lines.append(f"  pr-template   : {state.pr_template_path} ({state.pr_template_scope or 'once'})")
     if state.fix_cycle:
         lines.append(f"  fix-cycle     : {state.fix_cycle}")
-    report_writer_models = state.role_models.get("report-writer", [])
-    translator_model = (
-        report_writer_models[0] if report_writer_models
-        else "(selection required)"
-    )
-    lines.append(_msg(
-        state.workspace_root, "confirmation", "translation_scope", model=translator_model,
-    ))
     lines.append(_msg(
         state.workspace_root, "confirmation", "provider_data_scope",
         project_root=state.project_root,

package/runtime/python/okstra_ctl/wizard/registry.py

@@ -93,10 +93,10 @@ from .state import (
 from .prompts import _opt, _p
 from .sources import (
     _brief_resolved,
+    _clarification_pick_required,
     _has_prior_run_inputs,
     _latest_implementation_planning_report,
     _reverify_scope_pick_required,
-    _suggest_latest_final_report,
 )
 from .roles import _clear_role_selection, _reset_role_selection_from, next_role_prompt
 from .steps_identity import (
@@ -535,8 +535,7 @@ STEPS: list[Step] = [
     Step(S_CLARIFICATION_PICK,
          applies=lambda s: (S_CLARIFICATION_PICK not in s.answered
                             and _identity_ready(s)
-                            and (s.task_type != "implementation-planning"
-                                 or bool(_suggest_latest_final_report(s)))),
+                            and _clarification_pick_required(s)),
          build=_build_clarification_pick, submit=_submit_clarification_pick,
          owns=("clarification_response_path", "clarification_pending_text")),
     Step(S_CLARIFICATION,

package/runtime/python/okstra_ctl/wizard/sources.py

@@ -600,6 +600,16 @@ def _latest_run_inputs(
         phase_segment=phase_segment)
 
 
+def _clarification_pick_required(state: WizardState) -> bool:
+    if state.task_type == "release-handoff":
+        report = _suggest_latest_final_report(state)
+        return bool(report and sidecar_answers(Path(state.project_root) / report))
+    return (
+        state.task_type != "implementation-planning"
+        or bool(_suggest_latest_final_report(state))
+    )
+
+
 def _carried_planning_report(state: WizardState) -> Optional[Path]:
     """이번 재실행이 이어받는 직전 implementation-planning 리포트 (없으면 None)."""
     if state.task_type != "implementation-planning":