okstra 0.135.0 → 0.137.0

package/docs/architecture/storage-model.md

@@ -236,7 +236,7 @@ Main contents:
 This document is only a quick summary and is not the source of truth.
 Always use `task-manifest.json` when checking canonical metadata.
 
-The rendered `task-index.md` is an English-literal artifact. The headings, field labels, and `## Notes` footnote of the template (`templates/project-docs/task-index.template.md`) ship as English literals regardless of the `reportLanguage` setting, matching the okstra-schedule-gen schedule contract. The docs-publication pipeline's Hangul check (`npm run docs:validate`) enforces this contract.
+The rendered `task-index.md` is an English-literal artifact. The headings, field labels, and `## Notes` footnote of the template (`templates/project-docs/task-index.template.md`) ship as English literals regardless of the `reportLanguage` setting, matching the okstra-schedule-gen schedule contract. `tests/contract/test_docs_runtime_contract.py` enforces this contract.
 
 ## Run manifest contract
 

package/docs/contributor-change-matrix.md

@@ -11,6 +11,6 @@ Use this matrix before changing high-risk repo contracts. Update the source file
 | Add phase | `scripts/okstra_ctl/workflow.py`, `prompts/profiles/`, `validators/`, `tests/` | workflow and validation contract tests |
 | Change worker roster | `prompts/profiles/*.md`, `scripts/okstra_ctl/workers.py`, `tests/contract/test_repo_contracts.py` | worker roster contract tests |
 | Change report section | `schemas/final-report-v1.0.schema.json`, `templates/reports/final-report.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
-| Change Markdown publication policy | `config/docs-publication.json`, `tools/docs_publication/`, affected public Markdown paths | `tests/docs_publication/`, `tests/contract/test_repo_contracts.py` |
+| Maintain Korean review mirrors | `config/korean-sources.json`, `tools/korean-sources/`, `.agents/skills/sync-korean-sources/`, `.claude/skills/sync-korean-sources/` | `tests-js/korean-sources-*.test.mjs` |
 
 `runtime/` is build output. Never edit it directly; change source files and rebuild the runtime payload instead.

package/docs/project-structure-overview.md

@@ -55,6 +55,10 @@ okstra/
 │   ├── lib/okstra/                  Bash helpers for okstra.sh
 │   └── lib/okstra-ctl/              Bash control-center subcommands
 ├── skills/                          Claude Code skills (13); `_fragments/` holds shared marker blocks
+├── .agents/skills/                  Codex repo-local maintainer skills
+├── .claude/skills/                  Claude Code project-only mirror-sync surface
+├── .claude/settings.json            Claude Code project-only mirror-sync surface
+├── .codex/hooks.json                Codex project lifecycle hooks
 ├── agents/                          lead SKILL.md + worker agent specs
 ├── prompts/                         launch template, phase profiles, wizard prompt JSON
 ├── schemas/                         JSON schema for final-report data.json
@@ -62,8 +66,8 @@ okstra/
 ├── validators/                      run / brief / schedule / view validators
 ├── tools/build.mjs                  source → runtime sync
 ├── tools/sync-skill-fragments.mjs   expand shared fragment blocks into skills/*/SKILL.md
-├── tools/docs_publication/          public-manual publication pipeline (build-time only; not shipped)
-├── config/docs-publication.json     publication inventory: every tracked Markdown path + classification
+├── tools/korean-sources/            maintainer-only Korean mirror sync engine
+├── config/korean-sources.json       configured English Markdown source roots
 ├── runtime/                         generated install payload; do not edit directly
 ├── tests/                           pytest unit suite
 ├── tests-e2e/                       Bash end-to-end scenarios
@@ -289,6 +293,7 @@ Important modules:
 | `team_reconcile.py` | stale team-member reconciliation at run-end teardown |
 | `worker_prompt_headers.py` | shared rendering of phase-aware worker prompt anchors (`worker_prompt_headers`): coding-preflight only for implementation and compact target identity for final-verification |
 | `worker_prompt_body.py` | provider-neutral initial analysis body/input renderer shared by Codex and external/team dispatch paths |
+| `report_language.py` | report-writer `**Report Language:**` resolution (`resolve_report_language`) — precedence project config → global config → task-brief inference, shared by both dispatchers so the stamped language does not depend on which dispatch path ran |
 | `worker_prompt_policy.py` | `PromptPlan` generating SSOT — resolves functional audience, equality group, packet-only input, coding-preflight eligibility, required headers, and size limits without consulting provider/model identity |
 | `worker_prompt_contract.py` | deterministic cross-task initial-prompt validator and normalized cross-worker equality SSOT, reused by dispatch adapters and the Phase 7 persisted-artifact validator |
 | `convergence_engine.py` | pure `ConvergenceEngine` reducer — seeds Round 0 working state, plans roster-aware rounds, applies structured outcomes and one critic-gap batch, finalizes schema v1.3, and validates replayable state without dispatch or filesystem ownership |
@@ -558,7 +563,7 @@ When changing code, keep these docs in sync:
 - New report field/section: update schema, template, report-writer worker, validator tests, this file's report model if user-visible.
 - New phase/profile behavior: update `prompts/profiles/*`, `docs/architecture.md`, `docs/cli.md`, and `README.md` if user-facing.
 
-`README.md`, `docs/cli.md`, `docs/architecture.md`, `docs/architecture/storage-model.md`, `docs/container.md`, and `docs/performance-improvement-plan-v2.md` are `translated` outputs in `config/docs-publication.json` — do **not** hand-edit them. Author the Korean source under the maintainer's Git-ignored `.project-docs/ko-source/`, then run the publication pipeline (`python3 -m tools.docs_publication prepare|validate|apply|record`), which keeps the source/output hashes in `.project-docs/doc-publishing/state.json` in step. Files classified `pending` — including this one, `CHANGES.md`, and `CHANGELOG.md` — are edited directly.
+Edit English canonical Markdown sources directly. After changing a path registered in `config/korean-sources.json`, process the local Korean mirror queue with `$sync-korean-sources` or `/sync-korean-sources`. `.project-docs/ko-sources/**` is maintainer-local only: it is neither published nor committed.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.135.0",
+  "version": "0.137.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",
@@ -35,10 +35,9 @@
   "scripts": {
     "build": "node tools/build.mjs",
     "prepack": "node tools/build.mjs",
-    "docs:validate": "python3 -m tools.docs_publication validate --repo .",
     "test:js": "node --test tests-js/*.test.mjs",
     "test:py": "python3 -m pytest tests/",
     "test:workflow": "bash validators/validate-workflow.sh",
-    "check": "npm run docs:validate && npm run build && npm run test:js && npm run test:py && npm run test:workflow"
+    "check": "npm run build && npm run test:js && npm run test:py && npm run test:workflow"
   }
 }

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.135.0",
-  "builtAt": "2026-07-25T13:20:54.916Z",
+  "package": "0.137.0",
+  "builtAt": "2026-07-26T18:44:34.234Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -11,19 +11,6 @@ is_interactive_session() {
   [[ -t 0 && -t 1 ]]
 }
 
-file_mtime() {
-  # Epoch mtime; portable across GNU (stat -c) and macOS/BSD (stat -f).
-  # Validate that the output is a bare integer before accepting it: GNU
-  # `stat -f %m` (a BSD-ism) does NOT fail cleanly — it succeeds with
-  # non-numeric filesystem output, so a plain `a || b` would return that
-  # garbage and later break `-gt`/`-eq` arithmetic under `set -u`.
-  local m=""
-  m="$(stat -c %Y "$1" 2>/dev/null)"
-  [[ "$m" =~ ^[0-9]+$ ]] || m="$(stat -f %m "$1" 2>/dev/null)"
-  [[ "$m" =~ ^[0-9]+$ ]] || m="0"
-  printf '%s' "$m"
-}
-
 split_task_key() {
   local raw_key=""
   raw_key="$(trim_whitespace "${TASK_KEY_INPUT-}")"
@@ -293,74 +280,44 @@ 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.
+  #
+  # 선택 규칙(mtime 최신, 동률이면 basename)과 산출물 위치 지식은
+  # okstra_ctl.paths.RunRef 가 정본이다. 과거 이 함수는 그 규칙을 bash 로
+  # 재구현해 python 쪽과 손으로 동기화해야 했다.
   local project_root="$1"
   local task_group="$2"
   local task_id="$3"
   local task_type_filter="$4"
 
+  # task-key 단축키 해소와 오타 진단(실제 task-key 목록 출력)은 이 resolver 가
+  # 소유한다. 최신 보고서 선택만 python 정본에 위임한다.
   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
-
-  # Pick the chronologically newest report (mtime first), matching the Python
-  # resume path (okstra_ctl.wizard's mtime-max). A pure basename sort conflates
-  # phases: across error-analysis/ and requirements-discovery/ dirs the filename
-  # embeds the task-type, so a lexicographic max always favors one phase
-  # regardless of which run is actually newer. Ties (same-second mtime within a
-  # phase dir) fall back to the greater basename so the highest seq/timestamp
-  # wins deterministically.
-  local best_path=""
-  local best_mtime=-1
-  local best_basename=""
-  local candidate=""
-  local candidate_mtime=""
-  local candidate_base=""
-  local d=""
-  for d in "${search_dirs[@]}"; do
-    [[ -d "$d" ]] || continue
-    while IFS= read -r candidate; do
-      candidate_mtime="$(file_mtime "$candidate")"
-      candidate_base="$(basename "$candidate")"
-      if [[ -z "$best_path" \
-            || "$candidate_mtime" -gt "$best_mtime" \
-            || ( "$candidate_mtime" -eq "$best_mtime" && "$candidate_base" > "$best_basename" ) ]]; then
-        best_path="$candidate"
-        best_mtime="$candidate_mtime"
-        best_basename="$candidate_base"
-      fi
-    done < <(find "$d" -maxdepth 1 -type f -name 'final-report-*.md' 2>/dev/null)
-  done
+  local found=""
+  found="$(PYTHONPATH="$WORKSPACE_ROOT/scripts:${PYTHONPATH-}" python3 - \
+             "$task_root" "$task_type_filter" <<'PY'
+import sys
+from okstra_ctl.paths import RunRef
+
+task_root, task_type_filter = sys.argv[1:3]
+types = ((task_type_filter,) if task_type_filter
+         else ("error-analysis", "requirements-discovery"))
+ref = RunRef.latest_under(task_root, types)
+if ref is not None:
+    sys.stdout.write(f"{ref.report}\t{ref.task_type}")
+PY
+)" || return 1
 
-  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
+  if [[ -z "$found" ]]; then
+    printf 'resume-clarification: no final-report-*.md found for task %s:%s under %s/runs\n' \
+      "$task_group" "$task_id" "$task_root" >&2
     return 1
   fi
-
-  local resolved_type=""
-  resolved_type="$(basename "$(dirname "$(dirname "$best_path")")")"
-  printf '%s\t%s\n' "$best_path" "$resolved_type"
+  printf '%s\n' "$found"
 }
 
 run_resume_clarification() {

package/runtime/bin/lib/okstra-ctl/cmd-rerun.sh

@@ -151,7 +151,7 @@ batch_reserved = {}
 for original in targets:
     row = find_row_by_run_id(home, original)
     # implementation 은 stage 격리 task-type 이다. 한 run = 런타임에 live
-    # registry/consumers 상태로 auto-resolve 되는 단일 stage(_resolve_effective_stages)
+    # registry/consumers 상태로 auto-resolve 되는 단일 stage(stage_targets.resolve_effective_stages)
     # 이므로, cmd-rerun 은 spawn 전에 어느 stage-<N> 가 선택될지 알 수 없어
     # runs/implementation/stage-<N> 경로도 per-stage run_seq 도 예측할 수 없다.
     # OKSTRA_RUN_SEQ_OVERRIDE(run 전체에 단일 seq) 는 per-stage seq 카운터와

package/runtime/bin/okstra-antigravity-exec.sh

@@ -290,15 +290,17 @@ if (( idle_timeout_secs > 0 )); then
     while kill -0 "$agy_pid" 2>/dev/null; do
       sleep "$poll_interval"
       kill -0 "$agy_pid" 2>/dev/null || exit 0
-      # GNU `stat -c` 우선 + 숫자 검증. BSD-ism `stat -f %m` 은 Linux 에서 깨끗이
-      # 실패하지 않고 비숫자 파일시스템 출력으로 성공해 아래 산술을 set -u 에서
-      # 깨뜨린다 — file_mtime(lib/okstra/interactive.sh) 와 동일 가드.
+      # Portable mtime probe: GNU (stat -c %Y) first, macOS/BSD (stat -f %m) as
+      # the fallback, 0 as the floor. Validate each result as a bare integer
+      # before accepting it — on Linux the BSD-ism `stat -f %m` does NOT fail
+      # cleanly; it succeeds and prints non-numeric filesystem output, which
+      # would break the arithmetic below under `set -u`.
       #
-      # `|| true` 는 필수다. macOS 에는 GNU `stat -c` 가 없어 exit 1 이고,
-      # `2>/dev/null` 은 stderr 만 막지 종료코드는 막지 못한다. 이 워치독은 명시적
-      # `( ) &` 서브셸이라 위쪽 `set -e` 를 상속하므로, 실패한 할당 하나가 첫 폴링에서
-      # 워치독을 통째로 죽인다 — 조용히, 로그 한 줄 없이. file_mtime 이 같은 코드로도
-      # 멀쩡한 것은 항상 `$( )` 안에서 호출돼 errexit 을 상속하지 않기 때문이다.
+      # `|| true` is mandatory. macOS has no GNU `stat -c`, so that call exits 1,
+      # and `2>/dev/null` suppresses stderr but not the exit code. This watchdog
+      # is an explicit `( ) &` subshell, so it inherits whatever errexit setting
+      # is in force; under `set -e` a single failed assignment kills the whole
+      # watchdog on the first poll — silently, without a log line.
       last_mtime="$(stat -c %Y "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime=0

package/runtime/bin/okstra-claude-exec.sh

@@ -132,15 +132,17 @@ if (( idle_timeout_secs > 0 )); then
     while kill -0 "$claude_pid" 2>/dev/null; do
       sleep "$poll_interval"
       kill -0 "$claude_pid" 2>/dev/null || exit 0
-      # GNU `stat -c` 우선 + 숫자 검증. BSD-ism `stat -f %m` 은 Linux 에서 깨끗이
-      # 실패하지 않고 비숫자 파일시스템 출력으로 성공해 아래 산술을 set -u 에서
-      # 깨뜨린다 — file_mtime(lib/okstra/interactive.sh) 와 동일 가드.
+      # Portable mtime probe: GNU (stat -c %Y) first, macOS/BSD (stat -f %m) as
+      # the fallback, 0 as the floor. Validate each result as a bare integer
+      # before accepting it — on Linux the BSD-ism `stat -f %m` does NOT fail
+      # cleanly; it succeeds and prints non-numeric filesystem output, which
+      # would break the arithmetic below under `set -u`.
       #
-      # `|| true` 는 필수다. macOS 에는 GNU `stat -c` 가 없어 exit 1 이고,
-      # `2>/dev/null` 은 stderr 만 막지 종료코드는 막지 못한다. 이 워치독은 명시적
-      # `( ) &` 서브셸이라 위쪽 `set -e` 를 상속하므로, 실패한 할당 하나가 첫 폴링에서
-      # 워치독을 통째로 죽인다 — 조용히, 로그 한 줄 없이. file_mtime 이 같은 코드로도
-      # 멀쩡한 것은 항상 `$( )` 안에서 호출돼 errexit 을 상속하지 않기 때문이다.
+      # `|| true` is mandatory. macOS has no GNU `stat -c`, so that call exits 1,
+      # and `2>/dev/null` suppresses stderr but not the exit code. This watchdog
+      # is an explicit `( ) &` subshell, so it inherits whatever errexit setting
+      # is in force; under `set -e` a single failed assignment kills the whole
+      # watchdog on the first poll — silently, without a log line.
       last_mtime="$(stat -c %Y "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime=0

package/runtime/bin/okstra-codex-exec.sh

@@ -421,15 +421,17 @@ if (( idle_timeout_secs > 0 )); then
     while kill -0 "$codex_pid" 2>/dev/null; do
       sleep "$poll_interval"
       kill -0 "$codex_pid" 2>/dev/null || exit 0
-      # GNU `stat -c` 우선 + 숫자 검증. BSD-ism `stat -f %m` 은 Linux 에서 깨끗이
-      # 실패하지 않고 비숫자 파일시스템 출력으로 성공해 아래 산술을 set -u 에서
-      # 깨뜨린다 — file_mtime(lib/okstra/interactive.sh) 와 동일 가드.
+      # Portable mtime probe: GNU (stat -c %Y) first, macOS/BSD (stat -f %m) as
+      # the fallback, 0 as the floor. Validate each result as a bare integer
+      # before accepting it — on Linux the BSD-ism `stat -f %m` does NOT fail
+      # cleanly; it succeeds and prints non-numeric filesystem output, which
+      # would break the arithmetic below under `set -u`.
       #
-      # `|| true` 는 필수다. macOS 에는 GNU `stat -c` 가 없어 exit 1 이고,
-      # `2>/dev/null` 은 stderr 만 막지 종료코드는 막지 못한다. 이 워치독은 명시적
-      # `( ) &` 서브셸이라 위쪽 `set -e` 를 상속하므로, 실패한 할당 하나가 첫 폴링에서
-      # 워치독을 통째로 죽인다 — 조용히, 로그 한 줄 없이. file_mtime 이 같은 코드로도
-      # 멀쩡한 것은 항상 `$( )` 안에서 호출돼 errexit 을 상속하지 않기 때문이다.
+      # `|| true` is mandatory. macOS has no GNU `stat -c`, so that call exits 1,
+      # and `2>/dev/null` suppresses stderr but not the exit code. This watchdog
+      # is an explicit `( ) &` subshell, so it inherits whatever errexit setting
+      # is in force; under `set -e` a single failed assignment kills the whole
+      # watchdog on the first poll — silently, without a log line.
       last_mtime="$(stat -c %Y "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime=0

package/runtime/bin/okstra-spawn-followups.py

@@ -51,19 +51,14 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 from okstra_ctl.final_report_paths import final_report_markdown_path  # noqa: E402
+from okstra_ctl.paths import task_manifest_file  # noqa: E402
+from okstra_ctl.workflow import PHASE_SEQUENCE  # noqa: E402
 from okstra_project.dirs import tasks_root  # noqa: E402
 
 
 SLUG_RE = re.compile(r"[^a-zA-Z0-9-]+")
 
-ALLOWED_TASK_TYPES = {
-    "requirements-discovery",
-    "error-analysis",
-    "implementation-planning",
-    "implementation",
-    "final-verification",
-    "release-handoff",
-}
+ALLOWED_TASK_TYPES = set(PHASE_SEQUENCE)
 ALLOWED_ORIGINS = {
     "phase-continuation",
     "out-of-plan",
@@ -193,7 +188,7 @@ def _spawn_one(
             "routingStatus": "follow-up-spawned",
         },
     }
-    _write_manifest(task_root / "task-manifest.json", manifest_payload)
+    _write_manifest(task_manifest_file(task_root), manifest_payload)
 
     brief_path = task_root / "instruction-set" / "task-brief.md"
     brief_path.parent.mkdir(parents=True, exist_ok=True)

package/runtime/prompts/lead/plan-body-verification.md

@@ -244,7 +244,7 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
 
 Required prompt anchor headers are identical to finding convergence (see [convergence](./convergence.md) §"Required reverify-prompt anchor headers"). The prompt body changes from F-* listing to P-* listing:
 
-```
+````
 You are <worker-role> performing plan-body verification for <task-key> (round 1).
 
 ## Instructions
@@ -342,7 +342,7 @@ rerun a free-form requirements analysis. Every DISAGREE includes Fixability.
 **Fixability** (DISAGREE only): planner-fixable | needs-user-input. Fixability is not applicable for `UNVERIFIABLE`.
 **Note**: <the falsification candidate considered and why it is excluded; required even for AGREE>
 **Explanation**: <2-3 sentences applying the disposition-specific rule>
-```
+````
 
 When `config.adversarial == true`, the lead prepends the adversarial framing from §"Adversarial plan-body posture" to the `## Instructions` block: the burden of proof is on the plan, the verifier opens and confirms every accessible cited path / command, and evidence that was opened but is insufficient yields the applicable `DISAGREE(<kind>)` rather than `AGREE`. Inability to inspect because of capability, credential, network, or service state yields `UNVERIFIABLE`, not DISAGREE. The verdict tokens, breakage kinds (a–f), classification, and the majority gate threshold are unchanged. This prepended framing supersedes the template's "Judge solely from plan internal consistency" instruction for the adversarial round.
 

package/runtime/python/okstra_ctl/backfill.py

@@ -10,6 +10,7 @@ from typing import List
 from okstra_project.dirs import tasks_root
 
 from .ids import build_run_id
+from .paths import runs_dir_of
 from .invocation import save_invocation
 from .jsonl import append_jsonl, read_jsonl, rotate_recent_if_needed
 from .project_meta import _project_meta_path
@@ -130,7 +131,7 @@ def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
     manifest_re = _re.compile(r"^run-manifest-(?P<tt>.+)-(?P<seq>\d+)\.json$")
     for group_dir in sorted(p for p in base.iterdir() if p.is_dir()):
         for task_dir in sorted(p for p in group_dir.iterdir() if p.is_dir()):
-            runs = task_dir / "runs"
+            runs = runs_dir_of(task_dir)
             if not runs.is_dir():
                 continue
             for manifests in _iter_manifest_dirs(runs):