okstra 0.1.0

package/runtime/python/lib/okstra/interactive.sh

@@ -0,0 +1,411 @@
+# shellcheck shell=bash
+
+trim_whitespace() {
+  local value="${1-}"
+  value="${value#"${value%%[![:space:]]*}"}"
+  value="${value%"${value##*[![:space:]]}"}"
+  printf '%s' "$value"
+}
+
+is_interactive_session() {
+  [[ -t 0 && -t 1 ]]
+}
+
+split_task_key() {
+  local raw_key=""
+  raw_key="$(trim_whitespace "${TASK_KEY_INPUT-}")"
+
+  if [[ -z "$raw_key" ]]; then
+    return 0
+  fi
+
+  if [[ "$raw_key" != *:*:* ]]; then
+    printf 'invalid --task-key value: %s (expected <project-id>:<task-group>:<task-id>)\n' "$raw_key" >&2
+    exit 1
+  fi
+
+  local key_proj="${raw_key%%:*}"
+  local key_rest="${raw_key#*:}"
+  local key_group="${key_rest%%:*}"
+  local key_id="${key_rest#*:}"
+
+  if [[ -z "$key_proj" || -z "$key_group" || -z "$key_id" || "$key_id" == *:* ]]; then
+    printf 'invalid --task-key value: %s (expected <project-id>:<task-group>:<task-id>)\n' "$raw_key" >&2
+    exit 1
+  fi
+
+  if [[ -n "$PROJECT_ID" && "$PROJECT_ID" != "$key_proj" ]]; then
+    printf '%s\n' "--task-key project-id ($key_proj) conflicts with --project-id ($PROJECT_ID)" >&2
+    exit 1
+  fi
+  if [[ -n "$TASK_GROUP" && "$TASK_GROUP" != "$key_group" ]]; then
+    printf '%s\n' "--task-key task-group ($key_group) conflicts with --task-group ($TASK_GROUP)" >&2
+    exit 1
+  fi
+  if [[ -n "$TASK_ID" && "$TASK_ID" != "$key_id" ]]; then
+    printf '%s\n' "--task-key task-id ($key_id) conflicts with --task-id ($TASK_ID)" >&2
+    exit 1
+  fi
+
+  PROJECT_ID="$key_proj"
+  TASK_GROUP="$key_group"
+  TASK_ID="$key_id"
+}
+
+resolve_task_root_for_shortcut() {
+  local project_root="$1"
+  local project_id="$2"
+  local task_group="$3"
+  local task_id="$4"
+
+  local resolved=""
+  resolved="$(python3 - "$project_root" "$project_id" "$task_group" "$task_id" <<'PY'
+import json, os, re, sys
+from pathlib import Path
+
+project_root = Path(sys.argv[1])
+project_id = sys.argv[2]
+task_group = sys.argv[3]
+task_id = sys.argv[4]
+
+requested_key = f"{project_id}:{task_group}:{task_id}"
+requested_key_ci = requested_key.lower()
+
+def slugify(value: str) -> str:
+    value = value.lower()
+    value = re.sub(r"[^a-z0-9]+", "-", value).strip("-")
+    return value
+
+candidates = []
+
+catalog_path = project_root / ".project-docs" / "okstra" / "discovery" / "task-catalog.json"
+catalog_keys = []
+if catalog_path.is_file():
+    try:
+        catalog = json.loads(catalog_path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        sys.stderr.write(f"resolve_task_root: failed to parse {catalog_path}: {exc}\n")
+        catalog = None
+    if isinstance(catalog, dict):
+        catalog_project_id = catalog.get("projectId")
+        tasks = catalog.get("tasks") or []
+        for entry in tasks:
+            if not isinstance(entry, dict):
+                continue
+            entry_key = entry.get("taskKey") or ""
+            if not isinstance(entry_key, str) or not entry_key:
+                continue
+            entry_belongs_to_project = (
+                catalog_project_id == project_id
+                or entry.get("projectId") == project_id
+                or entry_key.startswith(f"{project_id}:")
+            )
+            if entry_belongs_to_project:
+                catalog_keys.append(entry_key)
+            if entry_key.lower() == requested_key_ci:
+                rel = entry.get("taskRootPath") or entry.get("taskRoot")
+                if isinstance(rel, str) and rel:
+                    abs_path = (project_root / rel).resolve() if not os.path.isabs(rel) else Path(rel)
+                    if abs_path.is_dir():
+                        print(f"OK\t{abs_path}")
+                        sys.exit(0)
+                    candidates.append(str(abs_path))
+
+slug_path = project_root / ".project-docs" / "okstra" / "tasks" / slugify(task_group) / slugify(task_id)
+if slug_path.is_dir():
+    print(f"OK\t{slug_path}")
+    sys.exit(0)
+candidates.append(str(slug_path))
+
+# Failure path: emit diagnostics so the wrapper can show them.
+print("MISSING")
+print(f"REQUESTED\t{requested_key}")
+for cand in candidates:
+    print(f"TRIED\t{cand}")
+for key in sorted(set(catalog_keys)):
+    print(f"AVAILABLE\t{key}")
+PY
+)"
+
+  local status=""
+  status="$(printf '%s' "$resolved" | head -n 1 | awk -F '\t' '{print $1}')"
+
+  if [[ "$status" == "OK" ]]; then
+    printf '%s' "$resolved" | head -n 1 | awk -F '\t' '{print $2}'
+    return 0
+  fi
+
+  printf 'task root not found for %s:%s:%s\n' "$project_id" "$task_group" "$task_id" >&2
+  printf '%s\n' "$resolved" | awk -F '\t' '
+    $1 == "TRIED"    { printf "  tried: %s\n", $2 }
+    $1 == "AVAILABLE"{ avail = avail "    " $2 "\n" }
+    END {
+      if (avail != "") {
+        printf "  available task-keys for this project (case- and slug-sensitive on disk):\n%s", avail
+      }
+    }' >&2
+  printf '  hint: task-key lookup is case-insensitive against task-catalog.json. Group / id segments on disk are slugified (lowercased, non-alphanumeric runs collapsed to "-").\n' >&2
+  return 1
+}
+
+autofill_from_manifest() {
+  if [[ -z "$PROJECT_ID" ]]; then
+    return 0
+  fi
+  if [[ -n "$BRIEF_PATH" && -n "$ANALYSIS_TYPE" ]]; then
+    return 0
+  fi
+  if [[ -z "$TASK_GROUP" || -z "$TASK_ID" ]]; then
+    return 0
+  fi
+
+  # 신규 모델: PROJECT_ROOT 는 okstra.sh 가 시작 단계에서 best-effort 해석해 둔다.
+  # 미해석(빈 문자열) 상태이거나 실제 디렉토리가 아니면 autofill 을 skip 한다 — 과거
+  # "conf 파일 부재" 분기와 동일한 의미.
+  if [[ -z "${PROJECT_ROOT:-}" || ! -d "${PROJECT_ROOT:-}" ]]; then
+    return 0
+  fi
+  local manifest_project_root="$PROJECT_ROOT"
+
+  local manifest_task_root=""
+  manifest_task_root="$(resolve_task_root_for_shortcut "$manifest_project_root" "$PROJECT_ID" "$TASK_GROUP" "$TASK_ID" 2>/dev/null)" || return 0
+  local manifest_path="$manifest_task_root/task-manifest.json"
+  if [[ ! -f "$manifest_path" ]]; then
+    return 0
+  fi
+
+  local need_brief_val need_type_val
+  need_brief_val="$([[ -z "$BRIEF_PATH" ]] && printf '1' || printf '0')"
+  need_type_val="$([[ -z "$ANALYSIS_TYPE" ]] && printf '1' || printf '0')"
+  local autofill_output=""
+  autofill_output="$(python3 - "$manifest_path" "$need_brief_val" "$need_type_val" <<'PY'
+import json, sys
+path = sys.argv[1]
+need_brief = sys.argv[2] == "1"
+need_type = sys.argv[3] == "1"
+try:
+    data = json.loads(open(path, "r", encoding="utf-8").read())
+except Exception as exc:
+    sys.stderr.write(f"autofill_from_manifest: failed to parse {path}: {exc}\n")
+    sys.exit(0)
+
+brief = ""
+task_type = ""
+if need_brief:
+    brief = (data.get("taskBriefPath") or "").strip()
+if need_type:
+    workflow = data.get("workflow") or {}
+    task_type = (workflow.get("nextRecommendedPhase") or "").strip()
+    if task_type in ("", "pending-routing-decision", "done-or-follow-up"):
+        task_type = ""
+
+print(f"BRIEF={brief}")
+print(f"TYPE={task_type}")
+PY
+)"
+
+  local manifest_brief=""
+  local manifest_type=""
+  while IFS= read -r line; do
+    case "$line" in
+      BRIEF=*) manifest_brief="${line#BRIEF=}" ;;
+      TYPE=*)   manifest_type="${line#TYPE=}" ;;
+    esac
+  done <<<"$autofill_output"
+
+  if [[ -z "$BRIEF_PATH" && -n "$manifest_brief" ]]; then
+    BRIEF_PATH="$manifest_brief"
+    printf 'autofill: brief-path from task-manifest.json: %s\n' "$BRIEF_PATH" >&2
+  fi
+  if [[ -z "$ANALYSIS_TYPE" && -n "$manifest_type" ]]; then
+    ANALYSIS_TYPE="$manifest_type"
+    printf 'autofill: task-type from manifest workflow.nextRecommendedPhase: %s\n' "$ANALYSIS_TYPE" >&2
+  fi
+}
+
+missing_required_arguments_summary() {
+  local missing=()
+
+  [[ -z "$PROJECT_ID" ]] && missing+=("<project-id>")
+  [[ -z "$TASK_GROUP" ]] && missing+=("<task-group>")
+  [[ -z "$TASK_ID" ]] && missing+=("<task-id>")
+  [[ -z "$ANALYSIS_TYPE" ]] && missing+=("<task-type>")
+  [[ -z "$BRIEF_PATH" ]] && missing+=("<brief-path>")
+
+  if (( ${#missing[@]} == 0 )); then
+    printf '%s' ""
+    return 0
+  fi
+
+  printf '%s' "${missing[*]}"
+}
+
+prompt_for_required_argument() {
+  local variable_name="$1"
+  local prompt_label="$2"
+  local current_value="${!variable_name}"
+
+  current_value="$(trim_whitespace "$current_value")"
+
+  while [[ -z "$current_value" ]]; do
+    printf '%s: ' "$prompt_label" >&2
+    if ! IFS= read -r current_value; then
+      printf 'input cancelled while reading %s\n' "$prompt_label" >&2
+      exit 1
+    fi
+    current_value="$(trim_whitespace "$current_value")"
+  done
+
+  printf -v "$variable_name" '%s' "$current_value"
+}
+
+find_latest_final_report() {
+  # Args: project_root task_group task_id task_type_filter(optional)
+  # Echoes: <abs path to latest final-report-*.md>\t<task-type>
+  # Returns: 1 if not found.
+  local project_root="$1"
+  local task_group="$2"
+  local task_id="$3"
+  local task_type_filter="$4"
+
+  local task_root=""
+  task_root="$(resolve_task_root_for_shortcut "$project_root" "$PROJECT_ID" "$task_group" "$task_id")" || {
+    printf 'resume-clarification: unable to resolve task root for the given task-key. See diagnostics above.\n' >&2
+    return 1
+  }
+
+  local runs_root="$task_root/runs"
+  if [[ ! -d "$runs_root" ]]; then
+    printf 'resume-clarification: no runs/ directory under %s\n' "$task_root" >&2
+    return 1
+  fi
+
+  local search_dirs=()
+  if [[ -n "$task_type_filter" ]]; then
+    search_dirs+=("$runs_root/$task_type_filter/reports")
+  else
+    [[ -d "$runs_root/error-analysis/reports" ]] && search_dirs+=("$runs_root/error-analysis/reports")
+    [[ -d "$runs_root/requirements-discovery/reports" ]] && search_dirs+=("$runs_root/requirements-discovery/reports")
+  fi
+
+  if (( ${#search_dirs[@]} == 0 )); then
+    printf 'resume-clarification: no requirements-discovery or error-analysis reports/ directory under %s/runs/. Run that phase first before invoking --resume-clarification.\n' "$task_root" >&2
+    return 1
+  fi
+
+  local best_path=""
+  local best_basename=""
+  local candidate=""
+  local candidate_base=""
+  local d=""
+  for d in "${search_dirs[@]}"; do
+    [[ -d "$d" ]] || continue
+    while IFS= read -r candidate; do
+      candidate_base="$(basename "$candidate")"
+      if [[ -z "$best_path" || "$candidate_base" > "$best_basename" ]]; then
+        best_path="$candidate"
+        best_basename="$candidate_base"
+      fi
+    done < <(find "$d" -maxdepth 1 -type f -name 'final-report-*.md' 2>/dev/null)
+  done
+
+  if [[ -z "$best_path" ]]; then
+    printf 'resume-clarification: no final-report-*.md found for task %s:%s under %s\n' \
+      "$task_group" "$task_id" "$runs_root" >&2
+    return 1
+  fi
+
+  local resolved_type=""
+  resolved_type="$(basename "$(dirname "$(dirname "$best_path")")")"
+  printf '%s\t%s\n' "$best_path" "$resolved_type"
+}
+
+run_resume_clarification() {
+  if [[ "$RENDER_ONLY" == "true" ]]; then
+    printf '%s\n' '--resume-clarification is incompatible with --render-only' >&2
+    exit 1
+  fi
+  if [[ -n "${CLARIFICATION_RESPONSE_PATH-}" ]]; then
+    printf '%s\n' '--resume-clarification is incompatible with --clarification-response (the resume mode supplies it automatically)' >&2
+    exit 1
+  fi
+  if [[ -n "${APPROVED_PLAN_PATH-}" ]]; then
+    printf '%s\n' '--resume-clarification is incompatible with --approved-plan' >&2
+    exit 1
+  fi
+
+  if [[ -z "$PROJECT_ID" || -z "$TASK_GROUP" || -z "$TASK_ID" ]]; then
+    printf 'resume-clarification: --project-id, --task-group, --task-id (or --task-key) are required\n' >&2
+    exit 1
+  fi
+
+  # 신규 모델: PROJECT_ROOT 는 okstra.sh 진입 시점에 resolve_project_root_strict
+  # 로 이미 확정되어 export 되어 있다.
+  if [[ -z "${PROJECT_ROOT:-}" || ! -d "${PROJECT_ROOT:-}" ]]; then
+    printf 'resume-clarification: PROJECT_ROOT not resolved\n' >&2
+    exit 1
+  fi
+  local resume_project_root="$PROJECT_ROOT"
+
+  local lookup_result=""
+  if ! lookup_result="$(find_latest_final_report \
+        "$resume_project_root" "$TASK_GROUP" "$TASK_ID" "${ANALYSIS_TYPE-}")"; then
+    exit 1
+  fi
+  local report_path="${lookup_result%$'\t'*}"
+  local resolved_type="${lookup_result##*$'\t'}"
+
+  case "$resolved_type" in
+    requirements-discovery|error-analysis) ;;
+    *)
+      printf '%s (resolved task-type: %s)\n' '--resume-clarification only applies to requirements-discovery or error-analysis runs' "$resolved_type" >&2
+      exit 1
+      ;;
+  esac
+
+  local resume_task_root=""
+  resume_task_root="$(resolve_task_root_for_shortcut "$resume_project_root" "$PROJECT_ID" "$TASK_GROUP" "$TASK_ID")" || {
+    printf 'resume-clarification: unable to resolve task root for the given task-key. See diagnostics above.\n' >&2
+    exit 1
+  }
+  local manifest_file="$resume_task_root/task-manifest.json"
+  if [[ ! -f "$manifest_file" ]]; then
+    printf 'resume-clarification: task-manifest.json not found: %s\n' "$manifest_file" >&2
+    exit 1
+  fi
+  local resume_brief_rel=""
+  resume_brief_rel="$(python3 - "$manifest_file" <<'PY'
+import json, sys
+data = json.loads(open(sys.argv[1], "r", encoding="utf-8").read())
+print((data.get("taskBriefPath") or "").strip())
+PY
+)"
+  if [[ -z "$resume_brief_rel" ]]; then
+    printf 'resume-clarification: manifest missing taskBriefPath: %s\n' "$manifest_file" >&2
+    exit 1
+  fi
+
+  if [[ "${OKSTRA_RESUME_CLARIFICATION_DRY_RUN:-false}" == "true" ]]; then
+    printf 'resume-clarification (dry-run):\n' >&2
+    printf '  report: %s\n' "$report_path" >&2
+    printf '  re-exec: bash %s --task-type %s --project-id %s --task-group %s --task-id %s --task-brief %s --clarification-response %s\n' \
+      "$0" "$resolved_type" "$PROJECT_ID" "$TASK_GROUP" "$TASK_ID" "$resume_brief_rel" "$report_path" >&2
+    return 0
+  fi
+
+  local editor_cmd="${EDITOR:-vi}"
+  printf 'resume-clarification: opening %s with %s\n' "$report_path" "$editor_cmd" >&2
+  if ! "$editor_cmd" "$report_path"; then
+    printf 'resume-clarification: editor exited non-zero; aborting\n' >&2
+    exit 1
+  fi
+
+  printf 'resume-clarification: re-running okstra with --clarification-response\n' >&2
+  exec bash "$0" \
+    --task-type "$resolved_type" \
+    --project-id "$PROJECT_ID" \
+    --task-group "$TASK_GROUP" \
+    --task-id "$TASK_ID" \
+    --task-brief "$resume_brief_rel" \
+    --clarification-response "$report_path"
+}

package/runtime/python/lib/okstra/project-resolver.sh

@@ -0,0 +1,57 @@
+# shellcheck shell=bash
+
+# bash wrappers around scripts/okstra_project resolver. okstra.sh 가 시작 시
+# PROJECT_ROOT 를 확정하고 <PROJECT_ROOT>/.project-docs/okstra/project.json 을
+# upsert 한다. 과거 conf 파일 모델은 폐기되었다.
+
+# 절대경로(또는 빈 문자열) 를 stdout 으로 출력한다. 실패 시 stderr 에 메시지를
+# 남기고 비-0 종료. autofill 처럼 best-effort 호출자가 에러를 무시할 수 있도록
+# strict/safe 두 종류를 분리한다.
+resolve_project_root_strict() {
+  local explicit="${1-}"
+  python3 - "$WORKSPACE_ROOT/scripts" "$explicit" <<'PY'
+import os, sys
+sys.path.insert(0, sys.argv[1])
+from okstra_project import resolve_project_root, ResolverError
+explicit = sys.argv[2] if len(sys.argv) > 2 else ""
+try:
+    p = resolve_project_root(explicit_root=explicit, cwd=os.getcwd())
+except ResolverError as exc:
+    sys.stderr.write(f"resolve_project_root: {exc}\n")
+    sys.exit(1)
+print(p)
+PY
+}
+
+# 실패해도 0 으로 종료하고 stdout 은 빈 문자열(autofill 등 best-effort 경로용).
+resolve_project_root_safe() {
+  local explicit="${1-}"
+  python3 - "$WORKSPACE_ROOT/scripts" "$explicit" <<'PY'
+import os, sys
+sys.path.insert(0, sys.argv[1])
+from okstra_project import resolve_project_root, ResolverError
+explicit = sys.argv[2] if len(sys.argv) > 2 else ""
+try:
+    p = resolve_project_root(explicit_root=explicit, cwd=os.getcwd())
+except ResolverError:
+    sys.exit(0)
+print(p)
+PY
+}
+
+# project.json upsert. 충돌(projectId 불일치) 시 비-0 종료 + stderr 메시지.
+upsert_project_json() {
+  local project_root="$1"
+  local project_id="$2"
+  python3 - "$WORKSPACE_ROOT/scripts" "$project_root" "$project_id" <<'PY'
+import sys
+sys.path.insert(0, sys.argv[1])
+from pathlib import Path
+from okstra_project import upsert_project_json, ResolverError
+try:
+    upsert_project_json(Path(sys.argv[2]), sys.argv[3])
+except ResolverError as exc:
+    sys.stderr.write(f"project.json upsert failed: {exc}\n")
+    sys.exit(1)
+PY
+}

package/runtime/python/lib/okstra/usage.sh

@@ -0,0 +1,98 @@
+# shellcheck shell=bash
+
+usage() {
+  cat >&2 <<USAGE_EOF
+usage:
+  $DISPLAY_COMMAND_NAME [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--related-tasks taskA,taskB] --project-id <project-id> [--project-root <path>] --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
+
+summary:
+  $DISPLAY_TOOL_NAME prepares a task-keyed instruction bundle for Claude Code and launches an interactive Claude session by default.
+  The stable task identifier is composed of project-id + task-group + task-id.
+
+  Skills, worker agents, and the codex wrapper are installed once per user under
+  ~/.claude and ~/.okstra by scripts/okstra-install.sh. The user's settings.json
+  and project .claude/settings.local.json files are never modified; per-session
+  permissions are injected via 'claude --settings' at launch time.
+
+required arguments:
+  --project-id         Globally unique project ID. Example: fontradar-v2-api.
+                       Each project is registered at <project-root>/.project-docs/okstra/project.json
+                       on first run; subsequent runs verify the projectId there matches.
+  --task-group         Logical task group. Example: backend-api, bugfix, linear-8858
+  --task-id            Stable task identifier inside the task group. Example: login-error-analysis
+  --task-type          Task type. Also selects prompts/profiles/<task-type>.md
+  --task-brief        Task brief file path. Relative paths are resolved against the target project root.
+
+optional arguments:
+  --project-root       Absolute path to the target project root. Resolution order when omitted:
+                       (1) ancestor of cwd that contains .project-docs/okstra/project.json,
+                       (2) `git rev-parse --show-toplevel` from cwd. Errors out if neither resolves.
+  --directive        Free-form user-supplied directive carried into the run as a "## Directive" section
+                       inside instruction-set/analysis-material.md. Lead, workers, and skills (e.g. okstra-schedule)
+                       may treat this as a hard hint that overrides default heuristics. Use to express intent
+                       like "render a Gantt even with single XL task" or "emphasize rollout risk".
+  --clarification-response
+                       Low-level path argument. Carries an edited final-report.md from a prior
+                       requirements-discovery or error-analysis run into this run as Section 0
+                       input so the lead can reconcile each prior Q*. Use this for scripted or
+                       CI runs where the answer file is already prepared. Interactive users
+                       should prefer --resume-clarification, which wraps this flag.
+  --approved-plan      Path to the approved final-report.md from a prior implementation-planning run.
+                       Required when --task-type=implementation; the file MUST contain a recorded user approval marker.
+  --task-key <project-id:task-group:task-id>
+                       Shorthand for --project-id/--task-group/--task-id. When the matching task-manifest.json
+                       exists, brief-path and task-type are auto-filled from it (taskBriefPath and
+                       workflow.nextRecommendedPhase). Explicit flags always win.
+
+options:
+  --render-only        Render the Claude handoff prompt only. Do not launch Claude.
+  --resume-clarification
+                       Interactive convenience mode that wraps --clarification-response.
+                       Locates the latest requirements-discovery or error-analysis
+                       final-report-*.md for the given task-key, opens it in \$EDITOR so
+                       you can fill Section 5, then re-execs okstra with
+                       --clarification-response set to the edited file. Use this for
+                       hand-driven turn-arounds. Requires task identity flags
+                       (--project-id/--task-group/--task-id or --task-key). Mutually
+                       exclusive with --clarification-response and --approved-plan.
+  --yes                Skip interactive prompting and confirmation. Requires all required arguments.
+  --refresh-assets    Deprecated. okstra now installs skills/agents into ~/.claude and the codex
+                      wrapper into ~/.okstra/bin via scripts/okstra-install.sh. Re-run that
+                      installer with --refresh to update installed assets.
+  --workers            Comma-separated worker list for this run. Default: claude,codex,gemini,report-writer
+  --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus
+  --claude-model       Model for Claude worker. Default: OKSTRA_DEFAULT_CLAUDE_MODEL or sonnet
+  --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.5
+  --gemini-model       Model for Gemini worker. Default: OKSTRA_DEFAULT_GEMINI_MODEL or auto
+  --report-writer-model
+                      Model for report writer worker. Default: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or lead model default
+  --related-tasks      Optional comma-separated related task identifiers. Example: auth-token-refresh,frontend-login-ui
+  --task-type          Set the task purpose for this run and select the matching profile file.
+  -h, --help           Show this help.
+
+model defaults:
+  Claude lead: OKSTRA_DEFAULT_LEAD_MODEL or opus
+  Report writer worker: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or Claude lead default
+  Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or sonnet
+  Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.5
+  Gemini worker: OKSTRA_DEFAULT_GEMINI_MODEL or auto
+
+output:
+  Stable task bundles are stored under:
+    <target-project>/.project-docs/okstra/tasks/<task-group>/<task-id>/
+  Per-run history is stored under:
+    <target-project>/.project-docs/okstra/tasks/<task-group>/<task-id>/runs/
+  Inside each run date folder, artifacts are grouped by type under:
+    manifests/, state/, prompts/, reports/, status/, sessions/, worker-results/
+
+project-level discovery:
+  Latest $DISPLAY_TOOL_NAME task pointer:
+    <target-project>/.project-docs/okstra/discovery/latest-task.json
+
+interactive behavior:
+  If required arguments are missing and stdin is interactive, $DISPLAY_TOOL_NAME prompts for them.
+  Before execution, interactive runs show the collected input summary and continue only when you enter y or yes.
+  If --yes is provided, $DISPLAY_TOOL_NAME skips prompting and confirmation and requires all required arguments up front.
+USAGE_EOF
+}
+

package/runtime/python/lib/okstra-ctl/cmd-batch.sh

@@ -0,0 +1,59 @@
+# shellcheck shell=bash
+
+_okstra_ctl_batch() {
+  if [[ $# -lt 1 ]]; then
+    printf 'batch: missing subcommand (list|status)\n' >&2; exit 2
+  fi
+  local sub="$1"; shift
+  case "$sub" in
+    list)
+      OKSTRA_HOME_RESOLVED="$(okstra_central_home)" python3 - <<'PY'
+import json, os
+from pathlib import Path
+home = Path(os.environ["OKSTRA_HOME_RESOLVED"])
+batches = sorted((home / "batches").glob("*.json"))
+print(f"{'BATCH-ID':<24}  {'CREATED':<22}  {'SPAWNED':>7}  {'SKIPPED':>7}")
+for b in batches:
+    m = json.loads(b.read_text())
+    s = m.get("summary", {})
+    print(f"{m['batchId']:<24}  {m['createdAt']:<22}  "
+          f"{s.get('spawned', 0):>7}  {s.get('skipped', 0):>7}")
+PY
+      ;;
+    status)
+      if [[ $# -lt 1 ]]; then
+        printf 'batch status: missing <batch-id>\n' >&2; exit 2
+      fi
+      OKSTRA_HOME_RESOLVED="$(okstra_central_home)" \
+      OKSTRA_CTL_LIB_DIR="$SCRIPT_DIR" \
+      OK_BID="$1" python3 - <<'PY'
+import json, os, sys
+sys.path.insert(0, os.environ["OKSTRA_CTL_LIB_DIR"])
+from pathlib import Path
+from okstra_ctl import find_row_by_run_id
+home = Path(os.environ["OKSTRA_HOME_RESOLVED"])
+target = home / "batches" / f"{os.environ['OK_BID']}.json"
+if not target.is_file():
+    print(f"batch: not found: {os.environ['OK_BID']}", file=sys.stderr); sys.exit(2)
+m = json.loads(target.read_text())
+print(f"batchId   : {m['batchId']}")
+print(f"createdAt : {m['createdAt']}")
+print(f"summary   : {m['summary']}")
+print()
+print(f"{'SPAWN':<10}  {'LIVE':<11}  {'NEW-RUN-ID':<55}  {'SESSION-NAME'}")
+for it in m["items"]:
+    spawn_status = it["status"]
+    new_run_id = it.get("newRunId") or "-"
+    # 현재 인덱스(active+recent+archive)에서 live 상태를 조회한다.
+    live = "-"
+    if it.get("newRunId"):
+        live_row = find_row_by_run_id(home, it["newRunId"])
+        if live_row is not None:
+            live = live_row.get("status", "-")
+    print(f"{spawn_status:<10}  {live:<11}  "
+          f"{new_run_id:<55}  {it.get('sessionName') or '-'}")
+PY
+      ;;
+    *) printf 'batch: unknown subcommand: %s\n' "$sub" >&2; exit 2 ;;
+  esac
+}

package/runtime/python/lib/okstra-ctl/cmd-list.sh

@@ -0,0 +1,35 @@
+# shellcheck shell=bash
+
+_okstra_ctl_list() {
+  local project="all" task_group="all" status="all" since="" limit="0"
+  local include_archive="false"
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --project) project="$2"; shift 2 ;;
+      --task-group) task_group="$2"; shift 2 ;;
+      --status) status="$2"; shift 2 ;;
+      --since) since="$2"; shift 2 ;;
+      --limit) limit="$2"; shift 2 ;;
+      --include-archive) include_archive="true"; shift ;;
+      *) printf 'list: unknown option: %s\n' "$1" >&2; exit 2 ;;
+    esac
+  done
+  OKSTRA_HOME_RESOLVED="$(okstra_central_home)" \
+  OKSTRA_CTL_LIB_DIR="$SCRIPT_DIR" \
+  OK_PROJECT="$project" OK_TG="$task_group" OK_STATUS="$status" \
+  OK_SINCE="$since" OK_LIMIT="$limit" OK_ARC="$include_archive" \
+  python3 - <<'PY'
+import os, sys
+sys.path.insert(0, os.environ["OKSTRA_CTL_LIB_DIR"])
+from pathlib import Path
+from okstra_ctl import list_runs, format_runs_table
+rows = list_runs(
+    Path(os.environ["OKSTRA_HOME_RESOLVED"]),
+    project=os.environ["OK_PROJECT"], task_group=os.environ["OK_TG"],
+    status=os.environ["OK_STATUS"], since=os.environ["OK_SINCE"],
+    limit=int(os.environ["OK_LIMIT"]),
+    include_archive=os.environ["OK_ARC"] == "true",
+)
+print(format_runs_table(rows), end="")
+PY
+}