okstra 0.34.1 → 0.36.0

package/runtime/prompts/wizard/prompts.ko.json

@@ -0,0 +1,230 @@
+{
+  "schema_version": 1,
+  "locale": "ko",
+  "steps": {
+    "task_pick": {
+      "label": "어느 task?",
+      "echo_template": "task: {value}",
+      "options": {
+        "__new__": "Start a brand-new task",
+        "_LATEST_SUFFIX": "  (latest)"
+      }
+    },
+    "task_group": {
+      "label": "Task group 을 알려주세요 (예: backend-api, INV-1234, refactor)",
+      "echo_template": "task-group: {value}",
+      "echo_variants": {
+        "free_input": "task-group: (직접 입력)"
+      }
+    },
+    "task_group_with_suggestion": {
+      "label": "Task group? (brief 추천: {suggestion})",
+      "echo_template": "task-group: {value}",
+      "options": {
+        "__use_suggested__": "brief 값 사용: {suggestion}",
+        "__free_input__": "다른 값 입력"
+      }
+    },
+    "task_group_text": {
+      "label": "Task group 을 입력해주세요 (예: backend-api, INV-1234, refactor)",
+      "echo_template": "task-group: {value}"
+    },
+    "task_id": {
+      "label": "Task id 를 알려주세요 (예: login-error-analysis, dev-9043)",
+      "echo_template": "task-id: {value}",
+      "echo_variants": {
+        "free_input": "task-id: (직접 입력)"
+      }
+    },
+    "task_id_with_suggestion": {
+      "label": "Task id? (brief 추천: {suggestion})",
+      "echo_template": "task-id: {value}",
+      "options": {
+        "__use_suggested__": "brief 값 사용: {suggestion}",
+        "__free_input__": "다른 값 입력"
+      }
+    },
+    "task_id_text": {
+      "label": "Task id 를 입력해주세요 (예: login-error-analysis, dev-9043)",
+      "echo_template": "task-id: {value}"
+    },
+    "task_type": {
+      "label": "Task type?",
+      "echo_template": "task-type: {value}",
+      "options": {
+        "_RECOMMENDED_SUFFIX": " (recommended)"
+      }
+    },
+    "brief_keep": {
+      "label": "기존 brief 경로 [{existing_brief_path}] 를 유지할까요?",
+      "echo_template": "brief: {value}",
+      "options": {
+        "keep": "유지",
+        "change": "변경"
+      },
+      "echo_variants": {
+        "kept": "brief: {brief_path} (유지)"
+      }
+    },
+    "brief_path": {
+      "label": "task brief markdown 의 경로를 알려주세요 (project root 기준 상대경로 또는 절대경로)",
+      "echo_template": "brief: {value}"
+    },
+    "base_ref_pick": {
+      "label": "이 task worktree 의 base branch?",
+      "echo_template": "base-ref: {value}",
+      "options": {
+        "_RECOMMENDED_SUFFIX": " (recommended)",
+        "__free_input__": "직접 입력"
+      }
+    },
+    "base_ref_text": {
+      "label": "base ref 를 입력해주세요 (branch, tag, 또는 short/full SHA)",
+      "echo_template": "base-ref: {value}"
+    },
+    "approved_plan_pick": {
+      "label": "approved final-report 경로 (기본: {default})",
+      "echo_template": "approved-plan(pick): {value}",
+      "options": {
+        "__use_default__": "기본 경로 사용: {default}",
+        "__other__": "다른 경로 입력"
+      },
+      "errors": {
+        "default_not_found": "기본 approved-plan 경로를 찾을 수 없습니다. '다른 경로 입력'을 선택하세요."
+      }
+    },
+    "approved_plan": {
+      "label": "approved final-report.md 의 경로를 알려주세요 (APPROVED 마커 필수)",
+      "echo_template": "approved-plan: {value}"
+    },
+    "stage_pick": {
+      "label": "실행할 stage 를 선택하세요. auto 는 의존성이 만족된 가장 빠른 미완료 stage 를 자동으로 잡습니다.",
+      "echo_template": "stage: {value}",
+      "options": {
+        "auto": "auto (다음 미완료 stage)"
+      }
+    },
+    "directive_pick": {
+      "label": "추가 directive 가 있나요?",
+      "echo_template": "directive(pick): {value}",
+      "options": {
+        "__skip__": "없음 (건너뛰기)",
+        "__enter__": "있음 (입력)"
+      }
+    },
+    "related_tasks_pick": {
+      "label": "관련 task id 목록이 있나요?",
+      "echo_template": "related-tasks(pick): {value}",
+      "options": {
+        "__skip__": "없음 (건너뛰기)",
+        "__enter__": "있음 (입력)"
+      }
+    },
+    "clarification_pick": {
+      "label": "clarification-response 파일 경로가 있나요? (follow-up 시에만)",
+      "echo_template": "clarification(pick): {value}",
+      "options": {
+        "__skip__": "없음 (건너뛰기)",
+        "__enter__": "있음 (입력)"
+      }
+    },
+    "pr_template_pick": {
+      "label": "PR 본문 템플릿 경로를 직접 지정할까요?",
+      "echo_template": "pr-template(pick): {value}",
+      "options": {
+        "__skip__": "자동 해석 (project.json → config → 기본)",
+        "__enter__": "직접 경로 입력 (1회성 override)"
+      }
+    },
+    "executor": {
+      "label": "실행자 (executor)?",
+      "echo_template": "executor: {value}",
+      "options": {
+        "_DEFAULT_SUFFIX": " (default)"
+      }
+    },
+    "defaults_or_custom": {
+      "label": "기본 워커/모델로 진행할까요, 아니면 커스터마이즈할까요?",
+      "echo_template": "customize: {value}",
+      "options": {
+        "defaults": "Use defaults",
+        "customize": "Customize"
+      }
+    },
+    "workers_override": {
+      "label": "참여시킬 분석 워커를 선택해주세요 (최소 1개). report-writer 는 항상 포함됩니다.",
+      "echo_template": "workers: {value}",
+      "options": {
+        "_OPTIONAL_SUFFIX": " (옵션)"
+      },
+      "errors": {
+        "min_one_required": "워커를 최소 1개 선택해주세요"
+      }
+    },
+    "lead_model": {
+      "label": "리더(Claude lead) 모델?",
+      "echo_template": "lead-model: {value}"
+    },
+    "executor_model": {
+      "label": "실행자({executor}) 모델?",
+      "echo_template": "{executor}-model: {value}"
+    },
+    "claude_model": {
+      "label": "claude 워커 모델?",
+      "echo_template": "claude-model: {value}"
+    },
+    "codex_model": {
+      "label": "codex 워커 모델?",
+      "echo_template": "codex-model: {value}"
+    },
+    "gemini_model": {
+      "label": "gemini 워커 모델?",
+      "echo_template": "gemini-model: {value}"
+    },
+    "report_writer_model": {
+      "label": "리포트 작성자(report-writer) 모델?",
+      "echo_template": "report-writer-model: {value}"
+    },
+    "directive": {
+      "label": "추가 directive 가 있으면 적어주세요 (없으면 빈 줄)",
+      "echo_template": "directive: {value}"
+    },
+    "related_tasks": {
+      "label": "관련 task id 목록을 쉼표로 구분해서 적어주세요 (없으면 빈 줄)",
+      "echo_template": "related-tasks: {value}"
+    },
+    "clarification": {
+      "label": "clarification-response 파일 경로 (follow-up 시에만, 없으면 빈 줄)",
+      "echo_template": "clarification: {value}"
+    },
+    "pr_template": {
+      "label": "PR 본문 템플릿 경로 1회성 override (빈 줄이면 project.json → ~/.okstra/config.json → 스킬 디폴트 순으로 자동 해석)",
+      "echo_template": "pr-template: {value}"
+    },
+    "pr_template_scope": {
+      "label": "방금 입력한 경로를 영구 저장할까요?",
+      "echo_template": "pr-template-scope: {value}",
+      "options": {
+        "once": "이번 run 만 (1회성)",
+        "project": "프로젝트에 저장 (project scope)",
+        "global": "전역에 저장 (global scope)"
+      }
+    },
+    "confirm": {
+      "label": "이대로 진행할까요?",
+      "echo_template": "confirm: {value}",
+      "options": {
+        "proceed": "Proceed",
+        "edit": "Edit"
+      }
+    },
+    "edit_target": {
+      "label": "어느 step 으로 돌아갈까요?",
+      "echo_template": "edit-target: {value}"
+    }
+  },
+  "confirmation": {
+    "header": "선택 확인:",
+    "workers_implementation_default": "  workers       : (프로필 기본 — executor + verifier 2 + report-writer)"
+  }
+}

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

@@ -23,57 +23,10 @@ collect_required_arguments() {
   prompt_for_required_argument PROJECT_ID "Project ID"
   prompt_for_required_argument TASK_GROUP "Task Group"
   prompt_for_required_argument TASK_ID "Task ID"
-  prompt_for_required_argument ANALYSIS_TYPE "Task Type"
+  prompt_for_required_argument TASK_TYPE "Task Type"
   prompt_for_required_argument BRIEF_PATH "Task Brief Path"
 }
 
-confirm_execution_plan() {
-  local confirmation=""
-  local normalized_confirmation=""
-  if [[ "$ASSUME_YES" == "true" ]]; then
-    return 0
-  fi
-
-  if ! is_interactive_session; then
-    return 0
-  fi
-
-  cat >&2 <<CONFIRM_EOF
-okstra execution summary:
-  render only: ${RENDER_ONLY}
-  task type: ${ANALYSIS_TYPE}
-  project id: ${PROJECT_ID}
-  task group: ${TASK_GROUP}
-  task id: ${TASK_ID}
-  task brief path: ${BRIEF_FILE_PATH}
-  clarification response: ${CLARIFICATION_RESPONSE_FILE:-None}
-  related tasks: ${RELATED_TASKS_INLINE}
-  recommended workers: ${SELECTED_REVIEWERS}
-  lead model: ${LEAD_MODEL_DISPLAY}
-  worker models: claude=${CLAUDE_WORKER_MODEL_DISPLAY}, codex=${CODEX_WORKER_MODEL_DISPLAY}, gemini=${GEMINI_WORKER_MODEL_DISPLAY}, report-writer=${REPORT_WRITER_MODEL_DISPLAY}
-  executor (implementation only): ${EXECUTOR_OVERRIDE:-default(claude)}
-  task key input: ${TASK_KEY_INPUT:-None}
-  task key: ${TASK_KEY}
-  task root: ${TASK_ROOT}
-  run dir: ${RUN_DIR}
-  final report path: ${FINAL_REPORT_FILE}
-  final report template: ${FINAL_REPORT_TEMPLATE_FILE}
-CONFIRM_EOF
-
-  printf 'Continue? [y/yes]: ' >&2
-  if ! IFS= read -r confirmation; then
-    printf 'confirmation cancelled\n' >&2
-    exit 1
-  fi
-
-  normalized_confirmation="$(trim_whitespace "$confirmation")"
-  normalized_confirmation="$(printf '%s' "$normalized_confirmation" | tr '[:upper:]' '[:lower:]')"
-
-  if [[ "$normalized_confirmation" != "y" && "$normalized_confirmation" != "yes" ]]; then
-    printf 'okstra cancelled before execution\n' >&2
-    exit 1
-  fi
-}
 require_option_value() {
   local option_name="$1"
   local option_value="${2-}"
@@ -143,7 +96,7 @@ while [[ $# -gt 0 ]]; do
       shift 2
       ;;
     --task-type)
-      ANALYSIS_TYPE="$(require_option_value --task-type "${2-}")"
+      TASK_TYPE="$(require_option_value --task-type "${2-}")"
       shift 2
       ;;
     --project-id)

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

@@ -4,7 +4,7 @@ PROFILE_DIR="$WORKSPACE_ROOT/prompts/profiles"
 PROMPT_TEMPLATE="$WORKSPACE_ROOT/prompts/launch.template.md"
 TASK_INDEX_TEMPLATE="$WORKSPACE_ROOT/templates/project-docs/task-index.template.md"
 FINAL_REPORT_TEMPLATE_SOURCE="$WORKSPACE_ROOT/templates/reports/final-report.template.md"
-RUN_VALIDATOR_SCRIPT="$WORKSPACE_ROOT/validators/validate-run.py"
+RUN_VALIDATOR_PATH="$WORKSPACE_ROOT/validators/validate-run.py"
 SOURCE_CLAUDE_OKSTRA_SKILL="$WORKSPACE_ROOT/agents/SKILL.md"
 OKSTRA_ROOT=""
 OKSTRA_TASKS_ROOT=""
@@ -27,14 +27,14 @@ EXECUTOR_OVERRIDE=""
 WORK_CATEGORY=""
 BASE_REF=""
 RELATED_TASKS_RAW=""
-ANALYSIS_TYPE=""
+TASK_TYPE=""
 BRIEF_PATH=""
 PROJECT_ID=""
 TASK_GROUP=""
 TASK_ID=""
 TASK_KEY_INPUT=""
 TASK_KEY=""
-REVIEW_PROFILE=""
+ANALYSIS_PROFILE=""
 DIRECTIVE=""
 CLARIFICATION_RESPONSE_PATH=""
 APPROVED_PLAN_PATH=""
@@ -42,7 +42,7 @@ APPROVE_PLAN_ACK="false"
 # Phase 6 plan-body verification toggle. Default "true" (round runs).
 # Flipped to "false" by --no-plan-verification on the CLI.
 PLAN_VERIFICATION_ENABLED="true"
-CLARIFICATION_RESPONSE_FILE=""
+CLARIFICATION_RESPONSE_PATH=""
 CLARIFICATION_RESPONSE_RELATIVE_PATH=""
 PROJECT_ROOT=""
 PROJECT_ROOT_OVERRIDE=""
@@ -50,17 +50,17 @@ PROFILE_FILE=""
 BRIEF_FILE_PATH=""
 REVIEW_MATERIAL=""
 PROFILE_CONTENT=""
-SELECTED_REVIEWERS=""
+RECOMMENDED_ANALYSERS=""
 BRIEF_RELATIVE_PATH=""
 TASK_GROUP_SEGMENT=""
 TASK_ID_SEGMENT=""
 TASK_ROOT=""
-TASK_MANIFEST_FILE=""
-TASK_INDEX_FILE=""
-INSTRUCTION_SET_DIR=""
+TASK_MANIFEST_PATH=""
+TASK_INDEX_PATH=""
+INSTRUCTION_SET_PATH=""
 RUNS_DIR=""
 HISTORY_DIR=""
-TIMELINE_FILE=""
+TIMELINE_PATH=""
 RUN_DIR=""
 RUN_MANIFESTS_DIR=""
 RUN_STATE_DIR=""
@@ -69,7 +69,7 @@ RUN_REPORTS_DIR=""
 RUN_STATUS_DIR=""
 RUN_SESSIONS_DIR=""
 RUN_LOGS_DIR=""
-RUN_MANIFEST_FILE=""
+RUN_MANIFEST_PATH=""
 RUN_MANIFEST_RELATIVE_PATH=""
 RUN_PROMPT_SNAPSHOT_FILE=""
 RUN_PROMPT_SNAPSHOT_RELATIVE_PATH=""
@@ -81,17 +81,17 @@ GEMINI_WORKER_PROMPT_FILE=""
 GEMINI_WORKER_PROMPT_RELATIVE_PATH=""
 REPORT_WRITER_WORKER_PROMPT_FILE=""
 REPORT_WRITER_WORKER_PROMPT_RELATIVE_PATH=""
-FINAL_REPORT_FILE=""
-FINAL_STATUS_FILE=""
+FINAL_REPORT_PATH=""
+FINAL_STATUS_PATH=""
 FINAL_REPORT_RELATIVE_PATH=""
 FINAL_STATUS_RELATIVE_PATH=""
-FINAL_REPORT_TEMPLATE_FILE=""
+FINAL_REPORT_TEMPLATE_PATH=""
 FINAL_REPORT_TEMPLATE_RELATIVE_PATH=""
 REFERENCE_EXPECTATIONS_FILE=""
 REFERENCE_EXPECTATIONS_RELATIVE_PATH=""
-TEAM_STATE_FILE=""
+TEAM_STATE_PATH=""
 TEAM_STATE_RELATIVE_PATH=""
-WORKER_RESULTS_DIR=""
+WORKER_RESULTS_PATH=""
 WORKER_RESULTS_RELATIVE_PATH=""
 RUN_VALIDATOR_RELATIVE_PATH=""
 CLAUDE_WORKER_RESULT_FILE=""
@@ -103,7 +103,7 @@ GEMINI_WORKER_RESULT_RELATIVE_PATH=""
 REPORT_WRITER_WORKER_RESULT_FILE=""
 REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH=""
 CLAUDE_SESSION_ID=""
-CLAUDE_RESUME_COMMAND_FILE=""
+CLAUDE_RESUME_COMMAND_PATH=""
 CLAUDE_RESUME_COMMAND_RELATIVE_PATH=""
 RUN_TIMESTAMP_ISO=""
 RUN_DATETIME_SEGMENT=""
@@ -143,15 +143,15 @@ RELATED_TASKS_JSON="[]"
 RELATED_TASKS_BULLETS="- None recorded"
 RELATED_TASKS_INLINE="None"
 PROMPT=""
-LEAD_MODEL_DISPLAY=""
+LEAD_MODEL=""
 LEAD_MODEL_EXECUTION_VALUE=""
-CLAUDE_WORKER_MODEL_DISPLAY=""
+CLAUDE_WORKER_MODEL=""
 CLAUDE_WORKER_MODEL_EXECUTION_VALUE=""
-CODEX_WORKER_MODEL_DISPLAY=""
+CODEX_WORKER_MODEL=""
 CODEX_WORKER_MODEL_EXECUTION_VALUE=""
-GEMINI_WORKER_MODEL_DISPLAY=""
+GEMINI_WORKER_MODEL=""
 GEMINI_WORKER_MODEL_EXECUTION_VALUE=""
-REPORT_WRITER_MODEL_DISPLAY=""
+REPORT_WRITER_MODEL=""
 REPORT_WRITER_MODEL_EXECUTION_VALUE=""
 DEFAULT_WORKERS="claude,codex,report-writer"
 DEFAULT_LEAD_MODEL_NAME="${OKSTRA_DEFAULT_LEAD_MODEL:-opus-4-6}"

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

@@ -152,7 +152,7 @@ autofill_from_manifest() {
   if [[ -z "$PROJECT_ID" ]]; then
     return 0
   fi
-  if [[ -n "$BRIEF_PATH" && -n "$ANALYSIS_TYPE" ]]; then
+  if [[ -n "$BRIEF_PATH" && -n "$TASK_TYPE" ]]; then
     return 0
   fi
   if [[ -z "$TASK_GROUP" || -z "$TASK_ID" ]]; then
@@ -176,7 +176,7 @@ autofill_from_manifest() {
 
   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')"
+  need_type_val="$([[ -z "$TASK_TYPE" ]] && printf '1' || printf '0')"
   local autofill_output=""
   autofill_output="$(python3 - "$manifest_path" "$need_brief_val" "$need_type_val" <<'PY'
 import json, sys
@@ -217,9 +217,9 @@ PY
     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
+  if [[ -z "$TASK_TYPE" && -n "$manifest_type" ]]; then
+    TASK_TYPE="$manifest_type"
+    printf 'autofill: task-type from manifest workflow.nextRecommendedPhase: %s\n' "$TASK_TYPE" >&2
   fi
 }
 
@@ -229,7 +229,7 @@ missing_required_arguments_summary() {
   [[ -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 "$TASK_TYPE" ]] && missing+=("<task-type>")
   [[ -z "$BRIEF_PATH" ]] && missing+=("<brief-path>")
 
   if (( ${#missing[@]} == 0 )); then
@@ -349,7 +349,7 @@ run_resume_clarification() {
 
   local lookup_result=""
   if ! lookup_result="$(find_latest_final_report \
-        "$resume_project_root" "$TASK_GROUP" "$TASK_ID" "${ANALYSIS_TYPE-}")"; then
+        "$resume_project_root" "$TASK_GROUP" "$TASK_ID" "${TASK_TYPE-}")"; then
     exit 1
   fi
   local report_path="${lookup_result%$'\t'*}"

package/runtime/python/okstra_ctl/clarification_items.py

@@ -5,8 +5,8 @@ single section) is the canonical home for every clarification an
 implementation-planning run owes the user — decisions, file attachments,
 single data points. Each row carries a ``Blocks`` column whose value picks
 one of ``{approval, next-phase, none}``. Rows with ``Blocks=approval`` are
-the approval gate: they MUST resolve before the user marks the report
-``Approved`` and starts the next ``implementation`` run.
+the approval gate: they MUST resolve before the user flips the frontmatter
+``approved`` field to ``true`` and starts the next ``implementation`` run.
 
 This module exposes one read function for that gate so both
 ``_validate_approved_plan`` (pre-implementation run-prep) and any later
@@ -168,7 +168,7 @@ UNRESOLVED_STATUSES = {"open", "answered"}
 
 
 def unresolved_approval_blockers(report_text: str) -> Optional[list[ClarificationItem]]:
-    """Return rows that gate the User Approval Request — ``Blocks=approval``
+    """Return rows that gate the frontmatter ``approved`` flag — ``Blocks=approval``
     AND ``Status`` in ``{open, answered}``.
 
     ``None`` propagates the "schema absent" signal from
@@ -182,9 +182,3 @@ def unresolved_approval_blockers(report_text: str) -> Optional[list[Clarificatio
         it for it in items
         if it.blocks == "approval" and it.status in UNRESOLVED_STATUSES
     ]
-
-
-def unresolved_approval_blockers_in_file(path: Path) -> Optional[list[ClarificationItem]]:
-    return unresolved_approval_blockers(
-        Path(path).read_text(encoding="utf-8", errors="replace")
-    )

package/runtime/python/okstra_ctl/consumers.py

@@ -0,0 +1,53 @@
+"""Append-only writer / reader for `consumers.jsonl` under a plan run's task root.
+
+A row's identity for idempotency is the tuple
+    (impl_task_key, stage, status)
+so the same (started / done) record is never duplicated."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .run_context import consumers_mutex
+
+CONSUMERS_FILENAME = "consumers.jsonl"
+
+
+def _path(plan_run_root: Path) -> Path:
+    return plan_run_root / CONSUMERS_FILENAME
+
+
+def read_consumers(plan_run_root: Path) -> List[Dict[str, Any]]:
+    p = _path(plan_run_root)
+    if not p.exists():
+        return []
+    out = []
+    for line in p.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        out.append(json.loads(line))
+    return out
+
+
+def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
+                    status: str, **fields: Any) -> None:
+    if status not in ("started", "done"):
+        raise ValueError(f"status must be 'started' or 'done', got: {status!r}")
+    with consumers_mutex(plan_run_root.name):
+        existing = read_consumers(plan_run_root)
+        for row in existing:
+            if (row.get("impl_task_key") == impl_task_key
+                    and row.get("stage") == stage
+                    and row.get("status") == status):
+                return  # idempotent
+        record: Dict[str, Any] = {
+            "impl_task_key": impl_task_key,
+            "stage": stage,
+            "status": status,
+            **fields,
+        }
+        with _path(plan_run_root).open("a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")

package/runtime/python/okstra_ctl/final_report_schema.py

@@ -244,10 +244,3 @@ def load_schema(schema_path: Path | None = None) -> dict:
                 "could not locate schemas/final-report-v1.0.schema.json"
             )
     return json.loads(Path(schema_path).read_text(encoding="utf-8"))
-
-
-def validate_data_file(data_path: Path, schema_path: Path | None = None) -> list[str]:
-    """Convenience wrapper: read data.json, return validation errors."""
-    schema = load_schema(schema_path)
-    data = json.loads(Path(data_path).read_text(encoding="utf-8"))
-    return validate(data, schema)

package/runtime/python/okstra_ctl/i18n.py

@@ -0,0 +1,73 @@
+"""Final-report i18n dictionary loader + Jinja2 lookup function.
+
+사전은 ``templates/reports/i18n/<lang>.json`` 에 둔다. ChainableUndefined
+환경에서도 누락 키가 silent 로 빈 문자열이 되지 않도록 lookup 함수가
+직접 raise 한다.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Callable
+
+SUPPORTED_LANGS = ("en", "ko")
+DICTIONARY_REL = ("templates", "reports", "i18n")
+
+
+class I18nError(RuntimeError):
+    """사전 lookup 실패 또는 사전 로드 실패."""
+
+
+def _i18n_dir() -> Path:
+    okstra_home = os.environ.get("OKSTRA_HOME")
+    if okstra_home:
+        candidate = Path(okstra_home).joinpath(*DICTIONARY_REL)
+        if candidate.is_dir():
+            return candidate
+    here = Path(__file__).resolve()
+    for parent in [here, *here.parents]:
+        candidate = parent.joinpath(*DICTIONARY_REL)
+        if candidate.is_dir():
+            return candidate
+    raise I18nError(
+        "could not locate templates/reports/i18n/. Set OKSTRA_HOME or "
+        "run from a checkout that contains templates/reports/i18n/."
+    )
+
+
+def load_dictionary(lang: str) -> dict[str, Any]:
+    if lang not in SUPPORTED_LANGS:
+        raise I18nError(
+            f"unsupported reportLanguage {lang!r}; supported: {SUPPORTED_LANGS}"
+        )
+    path = _i18n_dir() / f"{lang}.json"
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise I18nError(f"failed to load {path}: {exc}") from exc
+
+
+def lookup(dictionary: dict[str, Any], dotted_key: str) -> str:
+    parts = dotted_key.split(".")
+    cur: Any = dictionary
+    for i, part in enumerate(parts):
+        if not isinstance(cur, dict):
+            raise I18nError(
+                f"i18n key {dotted_key!r}: segment {'.'.join(parts[:i]) or '<root>'!r} "
+                f"is not a dict (got {type(cur).__name__})"
+            )
+        if part not in cur:
+            raise I18nError(f"i18n key {dotted_key!r} not found in dictionary")
+        cur = cur[part]
+    if not isinstance(cur, str):
+        raise I18nError(
+            f"i18n key {dotted_key!r} resolved to {type(cur).__name__}, expected str"
+        )
+    return cur
+
+
+def make_jinja_global(dictionary: dict[str, Any]) -> Callable[[str], str]:
+    def t(dotted_key: str) -> str:
+        return lookup(dictionary, dotted_key)
+    return t

package/runtime/python/okstra_ctl/improvement_lenses.py

@@ -0,0 +1,44 @@
+"""Improvement-discovery phase SSOT: lens enum and cap constants.
+
+profile / brief skill / validator / wizard MUST import from this module.
+Re-defining the enum anywhere else violates the single-reference-point rule
+and is rejected by tests/test_okstra_improvement_lenses.py.
+"""
+from __future__ import annotations
+
+LENSES: tuple[str, ...] = (
+    "performance",
+    "security",
+    "readability",
+    "architecture",
+    "test-coverage",
+    "dx",
+    "observability",
+    "accessibility",
+)
+
+DEFAULT_CANDIDATE_CAP = 8
+ABSOLUTE_CANDIDATE_CAP = 12
+MIN_PRIORITY_LENSES = 1
+MAX_PRIORITY_LENSES = 4
+
+# report-writer is the AUTHOR of the final report; it never produces source
+# findings. validators reject `report-writer:<id>` entries in Source workers.
+SOURCE_WORKERS: tuple[str, ...] = ("claude", "codex", "gemini")
+
+
+def is_valid_lens(value: str) -> bool:
+    return value in LENSES
+
+
+def is_valid_lens_subset(values: list[str]) -> bool:
+    if not (MIN_PRIORITY_LENSES <= len(values) <= MAX_PRIORITY_LENSES):
+        return False
+    return all(v in LENSES for v in values)
+
+
+def is_within_candidate_cap(count: int, *, brief_cap: int | None) -> bool:
+    cap = brief_cap if brief_cap is not None else DEFAULT_CANDIDATE_CAP
+    if cap < 1 or cap > ABSOLUTE_CANDIDATE_CAP:
+        return False
+    return 1 <= count <= cap