okstra 0.202.0 → 0.205.0

package/runtime/python/okstra_ctl/handoff_verification.py

@@ -64,17 +64,36 @@ def require_finished_verification(manifest: dict, data: dict) -> None:
 
 
 def verification_row_is_current(row: dict) -> bool:
-    """저장한 승인 행이 같은 단계의 최신 완료 검증을 가리키는지 확인한다."""
+    """저장한 승인 행이 그 단계의 최신 완료 검증을 가리키는지 확인한다.
+
+    근거는 두 모양이다. 단독-stage 행은 그 stage 범위 run 을 가리키고 검증된
+    head 가 곧 그 stage 의 커밋이다. 전체 task 행은 task 범위 run 을 가리키고,
+    검증된 head 는 tip stage 의 커밋이므로 행의 `verified_head_commit` 과
+    대조한다 — 그 stage 가 보고서의 `stageReports` 에 실려 있어야 한다.
+    """
     try:
         report = final_report_data_path(Path(str(row.get("report_path") or "")))
         ref = RunRef.from_report_path(report.resolve())
         latest, manifest, data = load_latest_verification(ref.run_dir)
         require_finished_verification(manifest, data)
-        return (latest == report.resolve()
-                and ref.stage == row.get("stage")
-                and manifest.get("taskKey") == row.get("impl_task_key")
-                and (data.get("finalVerification") or {}).get("sourceImplementationReport", {}).get("capturedHeadSha") == row.get("head_commit")
-                and data.get("finalVerdict") == row.get("final_verdict"))
+        if (latest != report.resolve()
+                or manifest.get("taskKey") != row.get("impl_task_key")
+                or data.get("finalVerdict") != row.get("final_verdict")):
+            return False
+        captured = (data.get("finalVerification") or {}).get(
+            "sourceImplementationReport", {}).get("capturedHeadSha")
+        if row.get("verification_scope") == "whole-task":
+            covered = {
+                entry.get("stage")
+                for entry in (data.get("finalVerification") or {}).get("stageReports") or ()
+                if isinstance(entry, dict)
+            }
+            return (ref.stage is None
+                    and data.get("verificationScope") == "whole-task"
+                    and row.get("stage") in covered
+                    and captured == row.get("verified_head_commit"))
+        return (ref.stage == row.get("stage")
+                and captured == row.get("head_commit"))
     except (ValueError, JsonBoundaryError):
         # expected-miss: 이전 형식·재검증 중인 행에는 현재 인계 자격이 없다.
         return False

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -177,6 +177,15 @@ def claim_implementation_stage_run(
             candidate_base=head_sha,
             project_root=Path(task_worktree_path),
             plan_run_root=plan_run_root,
+            # 선행이 둘 이상인 stage 는 그 선행들만 담은 브랜치에서 시작한다.
+            # 그 브랜치를 만들 수 있는 것은 이 경로뿐이고, run.py 가 이미 task-key
+            # provision 락을 쥐고 있어 원시연산은 락을 다시 잡지 않는다.
+            identity=stage_targets.StageWorktreeIdentity(
+                project_id=inp.project_id,
+                task_group=task_group_segment,
+                task_id=task_id_segment,
+                work_category=inp.work_category,
+            ),
         )
     except stage_targets.StageTargetError as exc:
         raise _as_implementation_stage_error(exc) from exc

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -131,6 +131,8 @@ _REQUIRED_PROMPT_RESOURCES_HEADING = "## Required prompt resources"
 _HTML_COMMENTS = re.compile(r"<!--.*?-->\n?", re.DOTALL)
 _AGENT_CONTRACT_KEYS = {
     "schemaVersion",
+    # 이 run 이 동결한 계약 형식. 없는 run 은 Markdown 직무를 동결했다.
+    "contractFormatVersion",
     "dutyRootPath",
     "catalogDigest",
     "invocationReservationRootPath",
@@ -214,6 +216,117 @@ def materialize_initial_prompts(
         ) from exc
 
 
+def declared_delivery_mode(manifest: Mapping[str, Any]) -> PromptDeliveryMode:
+    """이 run 의 어댑터가 선언한 초기 프롬프트 배송 방식.
+
+    선언은 `leadAdapter.initialPromptDeliveryMode` 에 있고, 그 값은 render 가
+    호스트 descriptor(어댑터가 워커 디스패치를 가져갔으면 그 어댑터)에서
+    옮겨 적은 것이다. 선언이 없는 매니페스트는 이 필드가 생기기 전에 준비된
+    run 이므로 그때의 동작인 `eager-include` 로 간다. 아는 값이 아니면 멈춘다 —
+    프롬프트를 발행하고 나면 그 프롬프트는 불변이라, 잘못 고른 배송 방식은
+    나중에 고칠 수 없다.
+    """
+    adapter = manifest.get("leadAdapter")
+    declared = (
+        _string_value(adapter.get("initialPromptDeliveryMode"))
+        if isinstance(adapter, Mapping)
+        else ""
+    )
+    if not declared:
+        return PromptDeliveryMode.EAGER_INCLUDE
+    try:
+        return PromptDeliveryMode(declared)
+    except ValueError:
+        allowed = ", ".join(mode.value for mode in PromptDeliveryMode)
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            "leadAdapter.initialPromptDeliveryMode is not a delivery mode: "
+            f"{declared!r} (allowed: {allowed})",
+        ) from None
+
+
+def _read_side_context(
+    project_root: Path, run_manifest_path: Path, runtime_root: Path,
+) -> "_MaterializationContext":
+    """프롬프트를 쓰지 않는 호출자를 위한 컨텍스트.
+
+    읽는 것은 매니페스트·active run context·런타임 루트뿐이다. 발행 권한 검사와
+    team-state 는 프롬프트를 쓰는 쪽(호출한 CLI)의 몫이다.
+    """
+    root = project_root.resolve()
+    manifest = _load_json_object(
+        _resolve_input_path(root, run_manifest_path), "run manifest"
+    )
+    return _MaterializationContext(
+        request=InitialPromptMaterializationRequest(
+            project_root=root,
+            run_manifest_path=run_manifest_path,
+            runtime_root=runtime_root,
+            delivery_mode=declared_delivery_mode(manifest),
+            workers=(),
+        ),
+        project_root=root,
+        manifest=manifest,
+        team_state={},
+        active_context=hydrate_active_run_context(
+            _load_referenced_json(root, manifest, "activeRunContextPath")
+        ),
+    )
+
+
+def implementation_anchor_lines(
+    *,
+    project_root: Path,
+    run_manifest_path: Path,
+    runtime_root: Path,
+    worker_id: str,
+) -> list[str]:
+    """이 워커의 프롬프트가 싣는 구현 앵커 줄. 구현 audience 가 아니면 빈 목록.
+
+    executor 의 mutating cwd, 그리고 executor·verifier 공통의
+    `**Approved plan:**` / `**Stage for this implementation run:**` 이다.
+    `okstra agent-prompt jobs` 는 이 두 헤더를 요구하므로, 리드가 회수 경로로
+    발행한 프롬프트는 그 검사에서 거절됐다(실측 2026-09-23, fontradar-v2-api
+    dev-10860 stage-3: 리드가 헤더 두 줄을 손으로 지시문에 붙여 통과시켰다).
+    """
+    context = _read_side_context(project_root, run_manifest_path, runtime_root)
+    return _implementation_anchor_lines(
+        context, _prompt_plan(context.manifest, worker_id)
+    )
+
+
+def required_resource_block(
+    *,
+    project_root: Path,
+    run_manifest_path: Path,
+    runtime_root: Path,
+    worker_id: str,
+) -> str:
+    """이 워커의 프롬프트가 싣는 필수 자원 블록. 없으면 빈 문자열.
+
+    디스패치 시점의 composer 와 같은 블록이다 — executor 는 BLOCKING 게이트 세
+    본문과 stage discipline, verifier 는 `_implementation-verifier.md`, 둘 다
+    clarification 권한 블록과 fix-run carry. 리드가 `okstra agent-prompt
+    materialize` 로 먼저 발행한 프롬프트는 디스패치가 기존 파일로 그대로 쓰므로
+    composer 가 돌지 않았고, 이 블록이 통째로 빠졌다(실측 2026-09-22,
+    fontradar-v2-api dev-10860 implementation stage-1: executor·verifier 4개
+    프롬프트 모두 0건). 그 명령이 이 함수로 같은 블록을 붙인다.
+    """
+    context = _read_side_context(project_root, run_manifest_path, runtime_root)
+    plan = _prompt_plan(context.manifest, worker_id)
+    item = _PromptItem(
+        worker=InitialPromptWorkerRequest(worker_id, ""),
+        final_path=Path(),
+        plan=plan,
+        existed=False,
+        clarification_input=_resolve_clarification_input(context, plan),
+    )
+    item = _with_prompt_resources(
+        item, _resolve_prompt_resources(context, plan, existed=False)
+    )
+    return "\n".join(_resource_lines(context, item)).strip()
+
+
 def _materialize_initial_prompts(
     request: InitialPromptMaterializationRequest,
 ) -> dict[str, Path]:

package/runtime/python/okstra_ctl/lead_progress.py

@@ -243,7 +243,7 @@ def _append(args: argparse.Namespace) -> int:
 
 _CLI_EPILOG = r"""Usage:
   okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-1-intake
-  okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-4-dispatch --worker codex-worker --field model=gpt-5.6-sol
+  okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-4-dispatch --worker codex-worker --field model=gpt-6-sol
   okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-5-collect --worker codex-worker --field status=completed
 
 `progressLine` in the output is the line to emit to the user, verbatim.

package/runtime/python/okstra_ctl/legacy_model_selection.py

@@ -11,7 +11,7 @@ from .domain.host import (
     HostSessionContext,
 )
 from .domain.role import RoleCatalogError, normalize_role
-from .role_requirements import RoleProfile, RoleRequirement
+from .role_requirements import RoleProfile, RoleRequirement, StaticRoleRequirement
 
 
 class ModelSelectionInputError(ValueError):
@@ -404,7 +404,7 @@ def _validate_selection(
     explicit_counts: Mapping[str, int],
 ) -> None:
     requirements = {row.role: row for row in profile.roles if not row.dynamic}
-    requirements["leader"] = RoleRequirement("leader", 1, 1, 1, "lead")
+    requirements["leader"] = StaticRoleRequirement("leader", 1, 1, 1, "lead")
     for role in sorted(set(counts) | set(models)):
         requirement = requirements.get(role)
         if requirement is None:

package/runtime/python/okstra_ctl/manager_cli.py

@@ -22,7 +22,13 @@ from .manager_store import (
     link_project,
     list_managers,
     list_projects,
+    list_task_groups,
     list_tasks,
+    remove_child,
+    remove_task,
+    remove_task_group,
+    unlink_project,
+    update_task,
 )
 from .manager_split import split_task
 from .manager_sync import status_task, sync_task
@@ -37,6 +43,8 @@ _LIST_ROWS = {
                                   ("project count", "projectCount"), ("task count", "taskCount"))),
     "list-projects": ("Project", (("ID", "projectId"), ("root", "projectRoot"), ("role", "role"),
                                   ("tags", "tags"), ("linked at", "linkedAt"))),
+    "list-task-groups": ("Task group", (("name", "taskGroup"), ("created at", "createdAt"),
+                                        ("task count", "taskCount"))),
     "list-tasks": ("Task", (("group", "taskGroup"), ("ID", "taskId"), ("objective", "objective"),
                             ("progress mode", "progressMode"), ("child count", "childCount"),
                             ("created at", "createdAt"))),
@@ -47,7 +55,8 @@ def render_manager_text(command: str, payload: dict | list[dict]) -> str:
     """manager 모델 표면에 승인된 식별자와 상태만 투영한다."""
     allowed = {"init", "discover-projects", "new-project", "new-task-group", "new-task",
                "task-assign", "task-note", "task-sync", "task-status", "task-run", "task-split",
-               "list-managers", "list-projects", "list-tasks", "view"}
+               "list-managers", "list-projects", "list-task-groups", "list-tasks", "view",
+               "task-update", "task-remove-child", "remove-project", "remove-task", "remove-task-group"}
     if command not in allowed:
         raise ValueError("unknown manager text purpose")
     rows = [f"Okstra manager {command}\n", line("Status", "ready")]
@@ -94,11 +103,30 @@ def render_manager_text(command: str, payload: dict | list[dict]) -> str:
             for label, key in (("task key", "taskKey"), ("project ID", "projectId"), ("ticket", "ticketId"),
                                ("path", "briefPath"), ("status", "briefStatus")):
                 rows.append(line(f"Brief {index} {label}", brief.get(key)))
+    if command == "task-update":
+        rows.append(line("Changed fields", ", ".join(payload.get("changedFields") or []) or "none"))
+        rows.extend(value_lines("Manifest", payload.get("manifest")))
+    if command.startswith("remove-") or command == "task-remove-child":
+        rows.extend(_render_removal(payload))
     if command == "task-sync" and "syncedAt" in payload:
         rows.append(line("Synced at", payload.get("syncedAt")))
     return "".join(rows)
 
 
+# 삭제 명령은 --confirm 이 없으면 대상만 보여 준다. 무엇이 지워지고 무엇이 남는지 한 줄씩 찍는다.
+def _render_removal(payload: dict) -> list[str]:
+    rows = [line("Removed", "yes" if payload.get("removed") else "no — dry run; rerun with --confirm")]
+    for label, key in (("Removed path", "path"), ("Child count", "childCount")):
+        if key in payload:
+            rows.append(line(label, payload.get(key)))
+    for label, key in (("Kept child", "keptChildren"), ("Removed task", "taskIds")):
+        values = payload.get(key)
+        if isinstance(values, list):
+            rows.append(line(f"{label} count", len(values)))
+            rows.extend(line(f"{label} {index}", value) for index, value in enumerate(values, 1))
+    return rows
+
+
 def _render_list(command: str, items: list[dict]) -> list[str]:
     prefix, fields = _LIST_ROWS[command]
     rows: list[str] = []
@@ -126,10 +154,12 @@ def _render_manager_status(payload: dict) -> list[str]:
             continue
         for label, key in (("task key", "taskKey"), ("run status", "latestRunStatus"),
                            ("current phase", "currentPhase"), ("work status", "workStatus"),
-                           ("summary", "summaryBucket"), ("ticket", "ticketId"), ("brief path", "briefPath"),
+                           ("summary", "summaryBucket"), ("project linked", "projectLinked"),
+                           ("ticket", "ticketId"), ("brief path", "briefPath"),
                            ("report path", "latestReportRecordPath"), ("error", "error")):
             if key in child:
-                rows.append(line(f"Child {index} {label}", child.get(key)))
+                value = child.get(key)
+                rows.append(line(f"Child {index} {label}", ("yes" if value else "no") if isinstance(value, bool) else value))
     return rows
 
 
@@ -188,11 +218,18 @@ _CLI_EPILOG = r"""Usage:
   okstra manager task note --manager-id <id> --task-group <task-group> --task-id <task-id> --scope <shared|project> --body <text>
   okstra manager task run --manager-id <id> --project-id <project-id> --task-group <task-group> --task-id <task-id>
   okstra manager task split --manager-id <id> --task-group <task-group> --task-id <task-id> --plan <split-plan.json> [--overwrite]
+  okstra manager task update --manager-id <id> --task-group <task-group> --task-id <task-id> [--objective <text>] [--common-brief <path>] [--progress-mode <manual|auto>]
+  okstra manager task remove-child --manager-id <id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <id>] [--confirm]
+  okstra manager remove project --manager-id <id> --project-id <project-id> [--confirm]
+  okstra manager remove task --manager-id <id> --task-group <task-group> --task-id <task-id> [--confirm]
+  okstra manager remove task-group --manager-id <id> --task-group <task-group> [--confirm]
   okstra manager list managers
   okstra manager list projects --manager-id <id>
+  okstra manager list task-groups --manager-id <id>
   okstra manager list tasks --manager-id <id>
   okstra manager view --manager-id <id>
 
+  remove and task remove-child only show their targets unless --confirm is given.
   --workspace-root is owned by this command.
 """
 _CLI_DESCRIPTION = "Manage cross-project okstra tasks."
@@ -277,10 +314,42 @@ def _parser() -> argparse.ArgumentParser:
     split.add_argument("--plan", required=True)
     split.add_argument("--overwrite", action="store_true")
 
+    update = task_sub.add_parser("update")
+    update.add_argument("--manager-id", required=True)
+    update.add_argument("--task-group", required=True)
+    update.add_argument("--task-id", required=True)
+    update.add_argument("--objective", default=None)
+    update.add_argument("--common-brief", default=None)
+    update.add_argument("--progress-mode", choices=["manual", "auto"], default=None)
+
+    remove_child_cmd = task_sub.add_parser("remove-child")
+    remove_child_cmd.add_argument("--manager-id", required=True)
+    remove_child_cmd.add_argument("--task-group", required=True)
+    remove_child_cmd.add_argument("--task-id", required=True)
+    remove_child_cmd.add_argument("--project-id", required=True)
+    remove_child_cmd.add_argument("--child-task-id", default=None)
+    remove_child_cmd.add_argument("--confirm", action="store_true")
+
+    remove = sub.add_parser("remove")
+    remove_sub = remove.add_subparsers(dest="remove_command", required=True)
+    remove_project = remove_sub.add_parser("project")
+    remove_project.add_argument("--manager-id", required=True)
+    remove_project.add_argument("--project-id", required=True)
+    remove_project.add_argument("--confirm", action="store_true")
+    remove_task_cmd = remove_sub.add_parser("task")
+    remove_task_cmd.add_argument("--manager-id", required=True)
+    remove_task_cmd.add_argument("--task-group", required=True)
+    remove_task_cmd.add_argument("--task-id", required=True)
+    remove_task_cmd.add_argument("--confirm", action="store_true")
+    remove_group = remove_sub.add_parser("task-group")
+    remove_group.add_argument("--manager-id", required=True)
+    remove_group.add_argument("--task-group", required=True)
+    remove_group.add_argument("--confirm", action="store_true")
+
     listing = sub.add_parser("list")
     list_sub = listing.add_subparsers(dest="list_command", required=True)
     list_sub.add_parser("managers")
-    for name in ("projects", "tasks"):
+    for name in ("projects", "task-groups", "tasks"):
         list_sub.add_parser(name).add_argument("--manager-id", required=True)
 
     view = sub.add_parser("view")
@@ -391,6 +460,25 @@ def main(argv: list[str] | None = None) -> int:
             _emit("list-managers", list_managers(home), args.json)
         elif args.command == "list" and args.list_command == "projects":
             _emit("list-projects", list_projects(home, args.manager_id), args.json)
+        elif args.command == "task" and args.task_command == "update":
+            _emit("task-update", update_task(home, args.manager_id, args.task_group, args.task_id,
+                                             objective=args.objective, common_brief_path=args.common_brief,
+                                             progress_mode=args.progress_mode), args.json)
+        elif args.command == "task" and args.task_command == "remove-child":
+            _emit("task-remove-child", remove_child(home, args.manager_id, args.task_group, args.task_id,
+                                                    args.project_id, child_task_id=args.child_task_id,
+                                                    confirm=args.confirm), args.json)
+        elif args.command == "remove" and args.remove_command == "project":
+            _emit("remove-project", unlink_project(home, args.manager_id, args.project_id,
+                                                   confirm=args.confirm), args.json)
+        elif args.command == "remove" and args.remove_command == "task":
+            _emit("remove-task", remove_task(home, args.manager_id, args.task_group, args.task_id,
+                                             confirm=args.confirm), args.json)
+        elif args.command == "remove" and args.remove_command == "task-group":
+            _emit("remove-task-group", remove_task_group(home, args.manager_id, args.task_group,
+                                                         confirm=args.confirm), args.json)
+        elif args.command == "list" and args.list_command == "task-groups":
+            _emit("list-task-groups", list_task_groups(home, args.manager_id), args.json)
         elif args.command == "list" and args.list_command == "tasks":
             _emit("list-tasks", list_tasks(home, args.manager_id), args.json)
         elif args.command == "view":

package/runtime/python/okstra_ctl/manager_launch.py

@@ -33,7 +33,7 @@ def _find_project(projects: dict, project_id: str) -> dict:
     for project in projects.get("projects", []):
         if isinstance(project, dict) and project.get("projectId") == project_id:
             return project
-    raise ManagerError(f"unknown project membership: {project_id}")
+    raise ManagerError(f"{project_id}: project unlinked from this manager; re-register it with `okstra manager new project`")
 
 
 def _target_task_key(project_id: str, task_group: str, task_id: str) -> str:

package/runtime/python/okstra_ctl/manager_paths.py

@@ -54,10 +54,21 @@ def manager_root(home: Path, manager_id: str) -> Path:
     return Path(home) / "managers" / canonical_manager_id(manager_id)
 
 
+def task_groups_root(home: Path, manager_id: str) -> Path:
+    return manager_root(home, manager_id) / "task-groups"
+
+
+def task_group_root(home: Path, manager_id: str, task_group: str) -> Path:
+    return task_groups_root(home, manager_id) / _slug_segment(task_group, "task-group")
+
+
+def task_group_meta_path(home: Path, manager_id: str, task_group: str) -> Path:
+    """폴더 이름은 slug 라 원래 그룹 이름을 여기에 남긴다."""
+    return task_group_root(home, manager_id, task_group) / "group.json"
+
+
 def task_root(home: Path, manager_id: str, task_group: str, task_id: str) -> Path:
-    group_segment = _slug_segment(task_group, "task-group")
-    task_segment = _slug_segment(task_id, "task-id")
-    return manager_root(home, manager_id) / "task-groups" / group_segment / task_segment
+    return task_group_root(home, manager_id, task_group) / _slug_segment(task_id, "task-id")
 
 
 def manager_json_path(home: Path, manager_id: str) -> Path: