okstra 0.136.0 → 0.138.0

package/runtime/python/okstra_ctl/path_hints.py

@@ -12,7 +12,7 @@ from okstra_project.dirs import (
     okstra_home,
 )
 
-from .paths import runs_dir_of
+from .paths import runs_dir_of, task_manifest_file, task_timeline_file
 
 RUN_CONTEXT_KIND = "run-context"
 RUN_CONTEXT_SCHEMA_VERSION = "2.0"
@@ -356,14 +356,14 @@ def _task_path_set(task_root: Path) -> dict[str, Path]:
     history_dir = task_root / "history"
     recap_dir = task_root / "recap"
     return {
-        "task_manifest": task_root / "task-manifest.json",
+        "task_manifest": task_manifest_file(task_root),
         "task_index": task_root / "task-index.md",
         "instruction_set": instruction_set,
         "analysis_packet": instruction_set / "analysis-packet.md",
         "task_qa": task_root / "qa",
         "runs_dir": runs_dir_of(task_root),
         "history_dir": history_dir,
-        "timeline_file": history_dir / "timeline.json",
+        "timeline_file": task_timeline_file(task_root),
         "recap_dir": recap_dir,
         "recap_log": recap_dir / "recap-log.jsonl",
         "final_report_template": instruction_set / "final-report-template.md",

package/runtime/python/okstra_ctl/paths.py

@@ -21,6 +21,7 @@ from typing import Optional
 
 from okstra_project.dirs import (
     DISCOVERY_RELATIVE,
+    TASK_MANIFEST_FILENAME,
     OKSTRA_RELATIVE,
     TASKS_RELATIVE,
     okstra_home,
@@ -313,6 +314,20 @@ def runs_dir_of(task_root: Path) -> Path:
     return Path(task_root) / "runs"
 
 
+def task_manifest_file(task_root: Path) -> Path:
+    """task 의 lifecycle manifest 경로.
+
+    task-type 을 모르는 호출자(recap·time-report·error-report·work-categories)가
+    쓰는 진입점이다. `RunRef.manifest` 는 한 *run* 의 run-manifest 이고, `report_finalize.task_manifest_path`
+    는 run manifest 의 fallback 체인을 타는 해소기다 — 셋 다 다른 것이므로 이름을 나눈다."""
+    return Path(task_root) / TASK_MANIFEST_FILENAME
+
+
+def task_timeline_file(task_root: Path) -> Path:
+    """task 의 history timeline 경로."""
+    return Path(task_root) / "history" / "timeline.json"
+
+
 def container_paths(project_root: Path, task_group: str, task_id: str) -> dict:
     """container 산출물 경로 묶음(순수 계산, mkdir 금지).
 
@@ -415,14 +430,14 @@ def compute_run_paths(
     discovery_dir = project_root / DISCOVERY_RELATIVE
 
     task_root = tasks_root / task_group_segment / task_id_segment
-    task_manifest = task_root / "task-manifest.json"
+    task_manifest = task_manifest_file(task_root)
     task_index = task_root / "task-index.md"
     instruction_set = task_root / "instruction-set"
     analysis_packet = instruction_set / "analysis-packet.md"
     task_qa = task_root / "qa"
     runs_dir = runs_dir_of(task_root)
     history_dir = task_root / "history"
-    timeline_file = history_dir / "timeline.json"
+    timeline_file = task_timeline_file(task_root)
     recap_dir = task_root / "recap"
     recap_log = recap_dir / "recap-log.jsonl"
 

package/runtime/python/okstra_ctl/recap.py

@@ -12,6 +12,8 @@ import sys
 from pathlib import Path
 
 from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.paths import task_timeline_file
+from okstra_project import read_task_key
 from okstra_ctl.run_context import dir_flock
 from okstra_ctl.task_target import resolve_task_root, project_rel
 
@@ -19,7 +21,7 @@ NOTE_KINDS = ("verification-evidence", "decision-draft", "analysis-note")
 
 
 def _load_timeline(task_root: Path) -> list[dict]:
-    path = task_root / "history" / "timeline.json"
+    path = task_timeline_file(task_root)
     if not path.is_file():
         return []
     try:
@@ -30,15 +32,6 @@ def _load_timeline(task_root: Path) -> list[dict]:
     return runs if isinstance(runs, list) else []
 
 
-def _task_key(task_root: Path) -> str:
-    path = task_root / "task-manifest.json"
-    if not path.is_file():
-        return ""
-    try:
-        return json.loads(path.read_text(encoding="utf-8")).get("taskKey", "")
-    except Exception:
-        return ""
-
 
 def assemble_recap(task_root: Path, project_root: Path) -> dict:
     runs = _load_timeline(task_root)
@@ -65,7 +58,7 @@ def assemble_recap(task_root: Path, project_root: Path) -> dict:
         # 최신 상태인 양 보고하게 된다.
         latest_states = snap.get("phaseStates", {}) or {}
     return {
-        "taskKey": _task_key(task_root),
+        "taskKey": read_task_key(task_root),
         "runCount": len(runs),
         "transitions": transitions,
         "latestPhaseStates": latest_states,
@@ -128,7 +121,7 @@ def write_note(task_root, project_root, *, kind, slug, purpose, scope_note,
     if not slug_seg:
         raise ValueError("slug must contain at least one alphanumeric character")
     path = _note_path(notes_dir, slug_seg, created_at)
-    task_key = _task_key(task_root)
+    task_key = read_task_key(task_root)
     frontmatter = _note_frontmatter(
         task_key=task_key, kind=kind, created_at=created_at,
         purpose=purpose, scope_note=scope_note)

package/runtime/python/okstra_ctl/render.py

@@ -23,7 +23,7 @@ import re
 import sys
 from pathlib import Path
 
-from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
+from okstra_project.dirs import TASK_MANIFEST_FILENAME, OKSTRA_DIR_NAME, project_json_path
 
 # phase 시퀀스 / 기본 next-phase 매핑의 SSOT 는 workflow 모듈이다. 과거
 # render_task_manifest 가 동일한 리스트/딕셔너리를 로컬에 중복 정의했는데,
@@ -32,6 +32,7 @@ from . import fix_cycles
 from .paths import okstra_home
 from .lead_runtime import lead_runtime_info
 from .path_hints import compact_active_run_context, hydrate_run_context
+from .paths import task_timeline_file
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -589,7 +590,7 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
             return str(p)
 
     entries = []
-    for manifest_path in sorted(tasks_root.rglob("task-manifest.json")):
+    for manifest_path in sorted(tasks_root.rglob(TASK_MANIFEST_FILENAME)):
         try:
             manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
         except Exception:
@@ -601,15 +602,15 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
             continue
         task_root = manifest_path.parent
         timeline_relative = s(manifest, "historyTimelinePath").strip()
-        timeline_path = (
+        timeline_file = (
             (project_root / timeline_relative)
             if timeline_relative
-            else (task_root / "history" / "timeline.json")
+            else task_timeline_file(task_root)
         )
         latest_run = {}
-        if timeline_path.is_file():
+        if timeline_file.is_file():
             try:
-                payload = json.loads(timeline_path.read_text(encoding="utf-8"))
+                payload = json.loads(timeline_file.read_text(encoding="utf-8"))
             except Exception:
                 payload = {}
             runs = payload.get("runs", []) if isinstance(payload, dict) else []
@@ -675,7 +676,7 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
                 or s(latest_run, "reportPath"),
                 "latestResumeCommandPath": s(manifest, "latestResumeCommandPath")
                 or s(latest_run, "resumeCommandPath"),
-                "historyTimelinePath": timeline_relative or rel(timeline_path),
+                "historyTimelinePath": timeline_relative or rel(timeline_file),
                 "fixCycles": manifest.get("fixCycles")
                 or {"count": 0, "openCycleId": None, "latest": None},
             }
@@ -1525,14 +1526,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
     )
     phase_order = workflow.get("phaseSequence", [])
     if not isinstance(phase_order, list) or not phase_order:
-        phase_order = [
-            "requirements-discovery",
-            "error-analysis",
-            "implementation-planning",
-            "implementation",
-            "final-verification",
-            "release-handoff",
-        ]
+        phase_order = list(PHASE_SEQUENCE)
     phase_state_lines = [
         f"- `{phase}`: `{phase_states.get(phase, 'not-started')}`"
         for phase in phase_order
@@ -1954,10 +1948,15 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         "- Worker prompt paths in `task-manifest.json` are assigned prompt-history "
         "locations, not pre-rendered completion markers. An absent file means its "
         "dispatch history has not been materialized yet.\n"
-        "- Construct each required worker prompt and follow the lifecycle core plus "
-        "selected adapter to persist its assigned history through `write_artifact` "
-        "and start it through `dispatch_worker`. Existing-history handling must stay "
-        "idempotent under those contracts.\n"
+        "- Code-backed `dispatch_worker` mappings leave missing roster prompts to "
+        "`okstra_ctl.initial_prompt_materialization` and its canonical "
+        "`materialize_initial_prompts()` entry point. The selected adapter supplies "
+        "its declared delivery mode; do not construct or overwrite those prompts "
+        "manually.\n"
+        "- For native in-process dispatch, use the same canonical initial-prompt headers, "
+        "persist the assigned prompt history through `write_artifact`, and apply "
+        "the adapter-declared `lazy-path-reference` delivery mode before starting the "
+        "worker. This native path does not apply to reverify or critic dispatches.\n"
         "- Use `await_workers` through the selected adapter and confirm terminal state "
         "plus every required Result Path. File presence alone is never a signal to "
         "skip; worker selection and skipped status come from `team-state`.\n"

package/runtime/python/okstra_ctl/report_finalize.py

@@ -21,7 +21,7 @@ from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
 
 from .final_report_paths import final_report_data_path, final_report_markdown_path
-from .paths import task_dir
+from .paths import task_dir, task_manifest_file
 
 
 STEP_TOKEN_USAGE = "token-usage"
@@ -108,15 +108,19 @@ def run_seq(manifest: Mapping[str, Any]) -> str:
 
 
 def task_manifest_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
+    """Resolve a run manifest's task manifest, falling back through the identity.
+
+    Distinct from `paths.task_manifest_file`, which only names the file inside a
+    known task root — this one decides *which* task root applies.
+    """
     value = string_value(manifest.get("taskManifestPath"))
     if value:
         return resolve_project_path(project_root, value)
     task_root = string_value(manifest.get("taskRootPath"))
     if task_root:
-        return resolve_project_path(project_root, task_root) / "task-manifest.json"
-    return (
+        return task_manifest_file(resolve_project_path(project_root, task_root))
+    return task_manifest_file(
         task_dir(project_root, task_group(manifest), task_id(manifest))
-        / "task-manifest.json"
     )
 
 

package/runtime/python/okstra_ctl/report_language.py

@@ -0,0 +1,83 @@
+"""Report-language resolution for the report-writer prompt.
+
+Both dispatchers stamp `**Report Language:**` into the report-writer prompt, so
+the precedence (project config → global config → inferred from the task brief)
+lives here rather than in whichever dispatcher happened to need it first.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Mapping
+
+from .worker_prompt_body import instruction_path
+
+REPORT_LANGUAGE_VALUES = {"en", "ko", "auto"}
+
+# Below this many Hangul syllables a brief reads as incidental Korean in an
+# otherwise English document.
+_HANGUL_THRESHOLD = 10
+_BRIEF_SCAN_CHARS = 16000
+
+
+class ReportLanguageError(ValueError):
+    """A config file declares a reportLanguage outside the allowed values."""
+
+
+def resolve_report_language(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> str:
+    for value in _report_language_candidates(project_root):
+        if value == "auto":
+            return _infer_report_language(project_root, manifest, active_context)
+        if value:
+            return value
+    return _infer_report_language(project_root, manifest, active_context)
+
+
+def _report_language_candidates(project_root: Path) -> list[str]:
+    okstra_home = Path(os.environ.get("OKSTRA_HOME") or Path.home() / ".okstra")
+    return [
+        _read_report_language(project_root / ".okstra" / "project.json", "project"),
+        _read_report_language(okstra_home / "config.json", "global"),
+    ]
+
+
+def _read_report_language(path: Path, label: str) -> str:
+    if not path.is_file():
+        return ""
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ReportLanguageError(f"{label} config is unreadable: {path}") from exc
+    if not isinstance(payload, Mapping):
+        raise ReportLanguageError(f"{label} config must be a JSON object: {path}")
+    value = payload.get("reportLanguage")
+    if value in (None, ""):
+        return ""
+    if isinstance(value, str) and value in REPORT_LANGUAGE_VALUES:
+        return value
+    raise ReportLanguageError(
+        f"{label} config reportLanguage must be en, ko, or auto: {path}"
+    )
+
+
+def _infer_report_language(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> str:
+    task_brief = instruction_path(manifest, active_context, "taskBriefPath")
+    if not task_brief:
+        return "en"
+    path = Path(task_brief)
+    if not path.is_absolute():
+        path = project_root / path
+    if not path.is_file():
+        return "en"
+    text = path.read_text(encoding="utf-8", errors="replace")[:_BRIEF_SCAN_CHARS]
+    hangul = sum(1 for char in text if "가" <= char <= "힣")
+    return "ko" if hangul >= _HANGUL_THRESHOLD else "en"