okstra 0.64.1 → 0.65.0

package/runtime/python/okstra_ctl/context_cost.py

@@ -23,6 +23,22 @@ INPUT_FILES = (
     "reference-expectations.md",
     "clarification-response.md",
 )
+# Per-run hot-path instruction assets the lead/workers load OUTSIDE the task
+# bundle: the lifecycle skills (Phase 1 / 2-5 / 5.5 / 6-7) plus the worker
+# agent specs. These are the prompt-diet (perf plan v2 P2) targets; the
+# bundle-local metrics below cannot see them, so they get their own metric.
+HOT_PATH_SKILLS = (
+    "okstra-context-loader",
+    "okstra-team-contract",
+    "okstra-convergence",
+    "okstra-report-writer",
+)
+WORKER_AGENT_FILES = (
+    "claude-worker.md",
+    "codex-worker.md",
+    "gemini-worker.md",
+    "report-writer-worker.md",
+)
 TIMESTAMPED_ARTIFACT_RE = re.compile(r"\d{4}-\d{2}-\d{2}[_T]\d{2}-\d{2}-\d{2}")
 
 
@@ -30,6 +46,21 @@ def _file_size(path: Path) -> int:
     return path.stat().st_size if path.is_file() else 0
 
 
+def _estimate_tokens(paths: Iterable[Path]) -> int:
+    """Static token proxy: ~4 ASCII chars per token, non-ASCII (KR/CJK)
+    ~1 token per char. Heuristic — real billable cost is the token-usage
+    collector's job; this only ranks instruction surfaces against each other.
+    """
+    total = 0.0
+    for path in paths:
+        if not path.is_file():
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        ascii_chars = sum(1 for ch in text if ord(ch) < 128)
+        total += ascii_chars / 4 + (len(text) - ascii_chars)
+    return round(total)
+
+
 def _count_files(paths: Iterable[Path]) -> tuple[int, int]:
     file_count = 0
     byte_count = 0
@@ -118,6 +149,14 @@ def _is_timestamped_legacy_artifact(path: Path) -> bool:
     return bool(TIMESTAMPED_ARTIFACT_RE.search(path.name))
 
 
+def _installed_or_dev(installed: Path, dev_relative: str) -> Path:
+    """Prefer the user-machine install (what production runs read); fall back
+    to the repo dev tree when running from an uninstalled checkout."""
+    if installed.is_file():
+        return installed
+    return Path(__file__).resolve().parents[2] / dev_relative
+
+
 def _instruction_set_metric(task_root: Path, project_root: Path) -> dict:
     instruction_set = task_root / "instruction-set"
     files = _all_files(instruction_set)
@@ -128,11 +167,50 @@ def _instruction_set_metric(task_root: Path, project_root: Path) -> dict:
         "path": _project_rel(instruction_set, project_root),
         "fileCount": file_count,
         "bytes": byte_count,
+        "estimatedTokens": _estimate_tokens(files),
         "analysisPacketBytes": _file_size(packet),
         "legacyTaskPacketBytes": _file_size(legacy_packet),
     }
 
 
+def _skill_assets_metric() -> dict:
+    """Per-run hot-path instruction assets outside the task bundle: lifecycle
+    skill bodies + worker agent specs. These dominate the fixed per-run
+    instruction footprint and are the prompt-diet ranking input."""
+    entries = []
+    claude_home = Path.home() / ".claude"
+    for name in HOT_PATH_SKILLS:
+        path = _installed_or_dev(
+            claude_home / "skills" / name / "SKILL.md",
+            f"skills/{name}/SKILL.md",
+        )
+        entries.append((f"skill:{name}", path))
+    for fname in WORKER_AGENT_FILES:
+        path = _installed_or_dev(
+            claude_home / "agents" / fname,
+            f"agents/workers/{fname}",
+        )
+        entries.append((f"agent:{fname}", path))
+
+    files = []
+    for label, path in entries:
+        if not path.is_file():
+            continue
+        files.append({
+            "name": label,
+            "path": str(path),
+            "bytes": _file_size(path),
+            "estimatedTokens": _estimate_tokens([path]),
+        })
+    files.sort(key=lambda row: row["bytes"], reverse=True)
+    return {
+        "fileCount": len(files),
+        "bytes": sum(row["bytes"] for row in files),
+        "estimatedTokens": sum(row["estimatedTokens"] for row in files),
+        "files": files,
+    }
+
+
 def _lead_phase1_metric(
     task_root: Path, run_dir: Path | None, manifest: dict, project_root: Path
 ) -> dict:
@@ -181,6 +259,7 @@ def _lead_phase1_metric(
         "mode": mode,
         "fileCount": file_count,
         "bytes": byte_count,
+        "estimatedTokens": _estimate_tokens(files),
         "files": [_project_rel(path, project_root) for path in files if path.is_file()],
     }
 
@@ -188,14 +267,10 @@ def _lead_phase1_metric(
 def _analysis_worker_metric(task_root: Path, project_root: Path) -> dict:
     instruction_set = task_root / "instruction-set"
     full_contract_files = [instruction_set / name for name in INPUT_FILES]
-    preamble = Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"
-    if not preamble.is_file():
-        repo_preamble = (
-            Path(__file__).resolve().parents[2]
-            / "templates"
-            / "worker-prompt-preamble.md"
-        )
-        preamble = repo_preamble
+    preamble = _installed_or_dev(
+        Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md",
+        "templates/worker-prompt-preamble.md",
+    )
     full_contract_files.append(preamble)
     full_file_count, full_byte_count = _count_files(full_contract_files)
 
@@ -217,6 +292,7 @@ def _analysis_worker_metric(task_root: Path, project_root: Path) -> dict:
         "mode": mode,
         "fileCount": file_count,
         "bytesPerWorker": byte_count,
+        "estimatedTokensPerWorker": _estimate_tokens(current_files),
         "legacyFullContractBytesPerWorker": full_byte_count,
         "legacyFullContractFileCount": full_file_count,
         "estimatedPacketModeBytesPerWorker": packet_byte_count,
@@ -253,6 +329,7 @@ def _report_writer_metric(run_dir: Path | None, task_root: Path, project_root: P
         "mode": "raw-synthesis-inputs",
         "fileCount": file_count,
         "bytes": byte_count,
+        "estimatedTokens": _estimate_tokens(files),
         "files": [_project_rel(path, project_root) for path in files if path.is_file()],
     }
 
@@ -286,6 +363,7 @@ def analyze_task_bundle(task_root: Path, project_root: Path) -> dict:
         "leadPhase1": _lead_phase1_metric(task_root, run_dir, manifest, project_root),
         "analysisWorker": _analysis_worker_metric(task_root, project_root),
         "reportWriter": _report_writer_metric(run_dir, task_root, project_root),
+        "skillAssets": _skill_assets_metric(),
     }
 
 

package/runtime/python/okstra_ctl/locks.py

@@ -27,6 +27,38 @@ def central_lock(home):
         f.close()
 
 
+@contextlib.contextmanager
+def worktree_provision_mutex(home, project_id: str, task_group: str,
+                             task_id: str):
+    """task-key 단위 worktree 프로비저닝 임계구역
+    (`<home>/.locks/worktree-provision/<task-key>.lock` 위 fcntl LOCK_EX).
+
+    사전검사(registry lookup / 경로·브랜치 존재)·stage 선택·`git worktree add`·
+    registry reserve 가 락 없이 인터리브되면: 동시 `--stage auto` run 둘이 같은
+    stage 를 선택해 후발이 "reused" 경로로 같은 worktree 에 들어가고, 같은
+    경로·브랜치를 둔 git 경쟁이 비결정적으로 실패하며, 한쪽 rollback
+    (`git worktree remove --force`)이 다른 쪽 worktree 를 지울 수 있다.
+    stage worktree 도 같은 task-key 락을 공유한다 — 브랜치 네임스페이스와
+    common-anchor 계산이 task 단위로 묶여 있기 때문.
+
+    flock 은 재진입 불가: 이 락을 쥔 채 다시 acquire 하면 self-deadlock 이므로
+    provision 함수 내부가 아니라 호출자(run.py orchestration)가 1회 감싼다.
+    """
+    from pathlib import Path as _Path
+    locks_dir = _Path(home) / ".locks" / "worktree-provision"
+    locks_dir.mkdir(parents=True, exist_ok=True)
+    parts = [_escape_segment_for_join(_safe_fs_segment(s))
+             for s in (project_id, task_group, task_id)]
+    lockfile = locks_dir / ("-".join(parts) + ".lock")
+    lockfile.touch(exist_ok=True)
+    with lockfile.open("r+") as f:
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+
+
 def task_lock_filename(project_id: str, task_group: str, task_id: str,
                        task_type: str) -> str:
     """task-key + task-type 단위 mutex 파일명. ~/.okstra/.locks/ 아래에 위치한다.

package/runtime/python/okstra_ctl/migrate.py

@@ -24,6 +24,9 @@ from pathlib import Path
 from typing import Optional
 
 from okstra_ctl.worktree import is_git_work_tree
+# 모듈 import 인 이유: 이 파일의 공개 함수들이 `okstra_home` 이라는 파라미터
+# 이름을 쓰고 있어, 같은 이름의 함수를 직접 import 하면 가려진다.
+from okstra_project import dirs as project_dirs
 from okstra_project.dirs import (
     LEGACY_OKSTRA_DIR_NAME,
     LEGACY_OKSTRA_RELATIVE,
@@ -187,12 +190,7 @@ def apply_migration_plan(
 
 
 def _resolve_okstra_home(override: Optional[Path]) -> Path:
-    if override is not None:
-        return Path(override)
-    env = os.environ.get("OKSTRA_HOME", "").strip()
-    if env:
-        return Path(env)
-    return Path.home() / ".okstra"
+    return Path(override) if override is not None else project_dirs.okstra_home()
 
 
 def _would_be_empty_after_remove(parent: Path, child: Path) -> bool:
@@ -375,3 +373,44 @@ def _replace_in_project_rows(text: str, project_str: str) -> str:
     if not changed:
         return text
     return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    """`python3 -m okstra_ctl.migrate [--apply] [--cwd <dir>] [--quiet]`.
+
+    기본은 dry-run 미리보기(plan JSON 출력 후 종료). 거부 가드에 걸리면
+    stderr 메시지와 함께 exit 1 — `bin/okstra` 의 `migrate` 서브커맨드가
+    그대로 forward 한다.
+    """
+    import argparse
+    import sys
+
+    p = argparse.ArgumentParser(prog="okstra migrate")
+    p.add_argument("--apply", action="store_true",
+                   help="실제 실행 (기본: dry-run 미리보기)")
+    p.add_argument("--cwd", default=".",
+                   help="프로젝트 루트 (기본: 현재 디렉토리)")
+    p.add_argument("--quiet", action="store_true", help="한 줄 JSON 만 출력")
+    args = p.parse_args(argv)
+
+    try:
+        plan = prepare_migration_plan(Path(args.cwd))
+    except MigrationRefused as exc:
+        print(f"migrate refused: {exc}", file=sys.stderr)
+        return 1
+    result = apply_migration_plan(plan, dry_run=not args.apply)
+    payload = {"plan": plan.to_dict(), "result": result.to_dict()}
+    if args.quiet:
+        print(json.dumps(payload, ensure_ascii=False))
+    else:
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        if result.dry_run:
+            print("dry-run only — re-run with --apply to execute.",
+                  file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main())

package/runtime/python/okstra_ctl/pr_template.py

@@ -19,7 +19,7 @@ import os
 from dataclasses import dataclass
 from pathlib import Path
 
-from okstra_project.dirs import project_json_path
+from okstra_project.dirs import okstra_home, project_json_path
 
 _DEFAULT_FILENAME = "pr-body.template.md"
 
@@ -34,11 +34,6 @@ class ResolvedPrTemplate:
     source: str  # "override" | "project" | "global" | "default"
 
 
-def _okstra_home() -> Path:
-    override = os.environ.get("OKSTRA_HOME", "").strip()
-    return Path(override) if override else Path.home() / ".okstra"
-
-
 def _default_template_candidates() -> list[Path]:
     """디폴트 템플릿 후보 경로들 (우선순위 순)."""
     out: list[Path] = []
@@ -100,7 +95,7 @@ def resolve_pr_template_path(
         return ResolvedPrTemplate(path=p, source="project")
 
     # 3) global config
-    gc_path = _okstra_home() / "config.json"
+    gc_path = okstra_home() / "config.json"
     gv = _read_json_field(gc_path, "prTemplatePath")
     if gv:
         p = Path(gv).expanduser()

package/runtime/python/okstra_ctl/run.py

@@ -29,10 +29,7 @@ from pathlib import Path
 from okstra_project import project_json_path, upsert_project_json
 from okstra_project.state import slugify
 from .analysis_packet import build_analysis_packet
-from .clarification_items import (
-    section_1_present_but_unparsed,
-    unresolved_approval_blockers,
-)
+from .clarification_items import scan_approval_gate
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
     build_analysis_material,
@@ -58,7 +55,12 @@ from .render import (
     render_template_with_ctx,
     render_timeline,
 )
-from .run_context import compute_and_write_run_context, write_run_inputs
+from okstra_project.dirs import okstra_home
+
+from .run_context import (
+    compute_and_write_run_context,
+    write_run_inputs,
+)
 from .seeding import (
     SettingsLinkError,
     cleanup_obsolete_generated_docs,
@@ -78,6 +80,7 @@ from .workers import (
     validate_workers_against_profile,
 )
 from .workflow import compute_workflow_state
+from .locks import worktree_provision_mutex
 from .worktree import provision_task_worktree
 
 # Frontmatter approval-flag matcher.
@@ -344,15 +347,15 @@ def _validate_approved_plan(path: str) -> None:
     _validate_data_json_approval_consistency(p, markdown_approved=True)
     # frontmatter approved == true 상태. §1 Clarification Items 의
     # Blocks=approval 행이 아직 open/answered 면 승인을 무효화한다.
-    blockers = unresolved_approval_blockers(body)
-    if blockers is None and section_1_present_but_unparsed(body):
+    scan = scan_approval_gate(body)
+    if scan.unreadable_reason:
         raise PrepareError(
-            f"approved plan has a `## 1. Clarification Items` heading but its table "
-            f"could not be parsed (heading/anchor/format drift): {path}\n"
-            "  the approval gate cannot confirm there are no unresolved "
-            "`Blocks=approval` rows, so it refuses to soft-pass. Re-render the report "
-            "with scripts/okstra-render-final-report.py so §1 matches the schema, then retry."
+            f"approved plan §1 approval gate could not be read: {path}\n"
+            f"  {scan.unreadable_reason}.\n"
+            "  the gate refuses to soft-pass — re-render the report with "
+            "scripts/okstra-render-final-report.py so §1 matches the schema, then retry."
         )
+    blockers = scan.blockers
     if blockers:
         lines = [
             f"approved plan frontmatter has `approved: true` but §1 has {len(blockers)} "
@@ -843,9 +846,8 @@ def _record_start(
     import json as _json
     from datetime import datetime, timezone
     from okstra_ctl import record_start
-    from okstra_ctl.run_context import _okstra_home  # type: ignore
 
-    home = _okstra_home()
+    home = okstra_home()
     home.mkdir(mode=0o700, parents=True, exist_ok=True)
     os.chmod(home, 0o700)
     # bootstrap (okstra_central_bootstrap 와 동등) — 디렉터리·jsonl 파일 보장.
@@ -1741,38 +1743,50 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # ---- task worktree provisioning (every phase, every task-type) ----
     # One worktree per task-key: requirements-discovery, error-analysis,
     # implementation-planning and implementation phases of the same task
-    # all share this directory and branch. The global registry handles
-    # reservation across concurrent runs. Runs BEFORE run-path compute: its
+    # all share this directory and branch. Runs BEFORE run-path compute: its
     # degrade status (skipped-*) feeds implementation stage selection, and
     # the resolved stage namespaces the run path.
-    try:
-        worktree = provision_task_worktree(
-            task_type=inp.task_type,
-            project_root=project_root,
-            project_id=inp.project_id,
-            task_group_segment=task_group_segment,
-            task_id_segment=task_id_segment,
-            work_category=inp.work_category,
-            base_ref=inp.base_ref,
-            require_base_ref=True,
-        )
-    except RuntimeError as exc:
-        raise PrepareError(f"task worktree provisioning failed: {exc}") from exc
-
-    # ---- implementation stage selection (path-independent, reserves once) ----
-    # Resolve + provision the stage BEFORE run-path compute so RUN_DIR lands
-    # in runs/implementation/stage-<N>. The registry stage-key is reserved
-    # exactly once here (inside provision_stage_worktree). Non-implementation
-    # task-types skip this entirely → stage_arg stays None → identical paths.
-    if inp.task_type == "implementation":
-        impl_stage_selection = _select_and_provision_implementation_stage(
-            inp, ctx_stage_map, task_group_segment, task_id_segment,
-            task_key, worktree.status,
-        )
-        stage_arg = impl_stage_selection.stage
-    else:
-        impl_stage_selection = None
-        stage_arg = None
+    #
+    # The whole check→select→`git worktree add`→reserve sequence (task
+    # worktree AND implementation stage) is one critical section per
+    # task-key: the registry lock alone only covers the reserve row, so
+    # without this mutex two concurrent runs can pick the same stage or
+    # race the same path/branch at the git level (TOCTOU).
+    with worktree_provision_mutex(
+        okstra_home(), inp.project_id, task_group_segment, task_id_segment,
+    ):
+        try:
+            worktree = provision_task_worktree(
+                task_type=inp.task_type,
+                project_root=project_root,
+                project_id=inp.project_id,
+                task_group_segment=task_group_segment,
+                task_id_segment=task_id_segment,
+                work_category=inp.work_category,
+                base_ref=inp.base_ref,
+                require_base_ref=True,
+            )
+        except RuntimeError as exc:
+            raise PrepareError(
+                f"task worktree provisioning failed: {exc}"
+            ) from exc
+
+        # ---- implementation stage selection (path-independent) ----
+        # Resolve + provision the stage BEFORE run-path compute so RUN_DIR
+        # lands in runs/implementation/stage-<N>. The registry stage-key is
+        # reserved exactly once here (inside provision_stage_worktree), and
+        # the surrounding mutex makes the registry read in stage selection
+        # and that reserve atomic. Non-implementation task-types skip this
+        # entirely → stage_arg stays None → identical paths.
+        if inp.task_type == "implementation":
+            impl_stage_selection = _select_and_provision_implementation_stage(
+                inp, ctx_stage_map, task_group_segment, task_id_segment,
+                task_key, worktree.status,
+            )
+            stage_arg = impl_stage_selection.stage
+        else:
+            impl_stage_selection = None
+            stage_arg = None
 
     ctx = compute_and_write_run_context(
         workspace_root=workspace_root, project_root=project_root,

package/runtime/python/okstra_ctl/run_context.py

@@ -23,6 +23,8 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Iterator, Optional
 
+from okstra_project.dirs import okstra_home
+
 from .paths import compute_run_paths, task_runs_dir
 
 
@@ -78,16 +80,9 @@ def _now_task_date() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
 
 
-def _okstra_home() -> Path:
-    home = os.environ.get("OKSTRA_HOME")
-    if home:
-        return Path(home)
-    return Path.home() / ".okstra"
-
-
 def _task_lock_path(task_key: str) -> Path:
     """task-key 별 mutex 파일. central index 와는 별개로 task 단위 직렬화."""
-    home = _okstra_home()
+    home = okstra_home()
     locks = home / ".locks"
     locks.mkdir(parents=True, exist_ok=True)
     safe = task_key.replace("/", "_").replace(":", "_")

package/runtime/python/okstra_ctl/seeding.py

@@ -14,6 +14,8 @@ import time
 from pathlib import Path
 from typing import Optional
 
+from okstra_project.dirs import okstra_home
+
 
 class InstallationError(Exception):
     """okstra 가 깔아둔 런타임 자산이 누락됨."""
@@ -32,10 +34,10 @@ def installed_version() -> str:
     so that report readers can distinguish behaviour drift across upgrades
     without having to dig through git history.
 
-    The stamp lives at `_okstra_home() / "version"`. `OKSTRA_HOME` overrides
+    The stamp lives at `okstra_home() / "version"`. `OKSTRA_HOME` overrides
     the home directory for tests.
     """
-    version_file = _okstra_home() / "version"
+    version_file = okstra_home() / "version"
     try:
         return version_file.read_text(encoding="utf-8").strip()
     except OSError:
@@ -43,13 +45,18 @@ def installed_version() -> str:
 
 
 def required_install_paths() -> list[Path]:
-    """okstra install 이 채워야 하는 최소 자산 경로."""
-    okstra_home = Path.home() / ".okstra"
+    """okstra install 이 채워야 하는 최소 자산 경로.
+
+    `installed_version()` 과 동일하게 `okstra_home()` 을 기준으로 한다 —
+    `OKSTRA_HOME` 으로 홈을 격리한 테스트는 conftest 가 같은 자산을 시드해
+    설치 검사를 통과시킨다(개발 머신의 실제 `~/.okstra` 설치 여부와 무관).
+    """
+    home = okstra_home()
     return [
-        okstra_home / "lib" / "python" / "okstra_project",
-        okstra_home / "lib" / "python" / "okstra_ctl",
-        okstra_home / "bin" / "okstra.sh",
-        okstra_home / "version",
+        home / "lib" / "python" / "okstra_project",
+        home / "lib" / "python" / "okstra_ctl",
+        home / "bin" / "okstra.sh",
+        home / "version",
     ]
 
 
@@ -60,8 +67,16 @@ def verify_installation(workspace_root: Path) -> None:
     workspace_root 는 prompts/, templates/, validators/, agents/ 를 담은
     디렉터리(`<okstra-package>/runtime` 또는 dev-link 모드의 repo 루트)다.
     이 검사는 ~/.okstra 자산만을 본다; workspace_root 의 존재는 별도 검증.
+
+    `OKSTRA_SKIP_INSTALL_CHECK=1` 이면 설치 자산 검사를 건너뛴다 — 격리
+    OKSTRA_HOME 으로 subprocess 를 띄우는 테스트용 게이트(conftest 가 설정,
+    OKSTRA_CTL_SKIP_RECONCILE/BACKFILL 과 같은 패턴). workspace_root 검증은
+    게이트와 무관하게 항상 수행한다.
     """
-    missing = [p for p in required_install_paths() if not p.exists()]
+    if os.environ.get("OKSTRA_SKIP_INSTALL_CHECK", "").strip():
+        missing = []
+    else:
+        missing = [p for p in required_install_paths() if not p.exists()]
     if missing:
         msg_lines = [f"okstra runtime missing: {p}" for p in missing]
         msg_lines.append("")
@@ -108,17 +123,9 @@ def cleanup_obsolete_generated_docs(
             pass
 
 
-def _okstra_home() -> Path:
-    """`~/.okstra` 의 절대경로. 테스트에서 `OKSTRA_HOME` 으로 override 가능."""
-    override = os.environ.get("OKSTRA_HOME", "").strip()
-    if override:
-        return Path(override)
-    return Path.home() / ".okstra"
-
-
 def installed_settings_template_path() -> Path:
     """okstra install 이 만들어 둔 settings.local.json template 의 절대경로."""
-    return _okstra_home() / "templates" / "settings.local.json"
+    return okstra_home() / "templates" / "settings.local.json"
 
 
 def ensure_project_settings_symlink(*, project_root: Path) -> Optional[Path]:

package/runtime/python/okstra_ctl/wizard.py

@@ -31,10 +31,7 @@ from okstra_ctl.models import (
     UnknownModelError,
     resolve_model_metadata,
 )
-from okstra_ctl.clarification_items import (
-    section_1_present_but_unparsed,
-    unresolved_approval_blockers,
-)
+from okstra_ctl.clarification_items import scan_approval_gate
 from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
 from okstra_ctl.run import (
     APPROVED_FRONTMATTER_PATTERN,
@@ -485,14 +482,15 @@ def _classify_approved_plan(path_str: str, project_root: Path) -> tuple[Path, bo
     # A blocking gate or an open Blocks=approval row makes the plan UN-approvable
     # — these raise regardless of the current flag value.
     _reject_blocking_plan_body_gate(p, body, action="approved plan validation")
-    blockers = unresolved_approval_blockers(body)
-    if blockers is None and section_1_present_but_unparsed(body):
+    scan = scan_approval_gate(body)
+    if scan.unreadable_reason:
         raise WizardError(
-            f"approved plan has a `## 1. Clarification Items` heading but its table "
-            f"could not be parsed (heading/anchor/format drift): {p}\n"
-            "  the approval gate cannot confirm there are no unresolved "
-            "`Blocks=approval` rows — re-render the report so §1 matches the schema."
+            f"approved plan §1 approval gate could not be read: {p}\n"
+            f"  {scan.unreadable_reason}.\n"
+            "  the gate refuses to soft-pass — re-render the report so §1 "
+            "matches the schema."
         )
+    blockers = scan.blockers
     if blockers:
         lines = [
             f"approved plan §1 has {len(blockers)} unresolved `Blocks=approval` "

package/runtime/python/okstra_ctl/worktree.py

@@ -548,6 +548,12 @@ def provision_task_worktree(
     AskUserQuestion menu in the okstra-run skill). Subsequent phases
     ignore ``base_ref`` — the registered entry's base is reused.
 
+    Concurrency: callers must hold ``locks.worktree_provision_mutex`` for
+    this task-key (run.py's prepare flow does). The exists/branch pre-checks
+    and ``git worktree add`` here are not internally locked — only the
+    registry reserve row is — so unlocked concurrent calls race (TOCTOU).
+    flock is non-reentrant, hence the lock lives at the caller.
+
     Raises:
         RuntimeError when worktree creation fails (path clash on disk
         that the registry does not know about, branch clash with a
@@ -721,6 +727,13 @@ def provision_stage_worktree(
     `worktree_registry`; re-entry of the same stage-key returns the
     existing entry. Branch / on-disk conflicts roll back the worktree
     before re-raising so a retry is not blocked.
+
+    Concurrency: callers must hold ``locks.worktree_provision_mutex`` for
+    the task-key, acquired BEFORE stage selection reads the registry
+    (run.py does) — otherwise two `--stage auto` runs can select the same
+    stage and the loser silently enters the winner's worktree via the
+    "reused" path. flock is non-reentrant, hence the lock lives at the
+    caller.
     """
     if not base_commit:
         raise RuntimeError("provision_stage_worktree requires a base_commit")

package/runtime/python/okstra_project/dirs.py

@@ -9,11 +9,12 @@ DRY 위반의 비용: 이전에는 동일 path 문자열이 50+ Python·Shell·m
 중복으로 박혀 있었고, 디렉토리 이름을 바꾸려면 60+ 파일을 동시에 수정해야 했다.
 이 모듈은 그 비용을 한 줄 수정으로 줄인다.
 
-의존성 0 (Path only). `paths.py` 와 `state.py` 양쪽에서 import 되므로 순환 위험을
+의존성 0 (stdlib only). `paths.py` 와 `state.py` 양쪽에서 import 되므로 순환 위험을
 피하기 위해 다른 okstra 모듈을 import 하지 않는다.
 """
 from __future__ import annotations
 
+import os
 from pathlib import Path
 
 OKSTRA_DIR_NAME = ".okstra"
@@ -39,6 +40,14 @@ TASK_CATALOG_RELATIVE = DISCOVERY_RELATIVE / "task-catalog.json"
 LATEST_TASK_RELATIVE = DISCOVERY_RELATIVE / "latest-task.json"
 
 
+def okstra_home() -> Path:
+    """`~/.okstra` 절대 path. 테스트/설치 환경에서 `OKSTRA_HOME` env 로 override."""
+    override = os.environ.get("OKSTRA_HOME", "").strip()
+    if override:
+        return Path(override)
+    return Path.home() / ".okstra"
+
+
 def okstra_root(project_root: Path) -> Path:
     """`<project_root>/.okstra` 절대 path."""
     return Path(project_root) / OKSTRA_RELATIVE