okstra 0.36.1 → 0.37.0

package/runtime/python/okstra_ctl/migrate.py

@@ -0,0 +1,408 @@
+"""`okstra migrate` 코어 — `<PROJECT_ROOT>/.project-docs/okstra/` 산출물을
+`<PROJECT_ROOT>/.okstra/` 로 이전한다.
+
+설계 원칙
+---------
+- `prepare_migration_plan(project_root)` 는 부수효과 없이 변경 항목만 수집.
+- `apply_migration_plan(plan, *, dry_run=True)` 가 실제 실행. dry-run 이 default.
+- 가드: `.okstra/` 이미 존재 / `.project-docs/okstra/` 없음 / git 미사용 fallback.
+- 다음 다섯 가지 변경만 수행 (그 외 파일은 절대 건드리지 않음):
+    1. `git mv .project-docs/okstra .okstra` (git 없으면 일반 `mv`).
+    2. `.project-docs/` 가 비면 `rmdir .project-docs`.
+    3. `<PROJECT_ROOT>/CLAUDE.md` 의 `@.project-docs/okstra/CLAUDE.md` import
+       라인을 `@.okstra/CLAUDE.md` 로 교체.
+    4. `.gitignore` 의 `.project-docs/okstra/` 항목을 `.okstra/` 로 교체.
+    5. `~/.okstra/{recent,active}.jsonl` 와 `~/.okstra/worktrees/registry.json`
+       의 해당 프로젝트 path 항목 갱신 (project_root 가 정확히 일치하는 row 만).
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from okstra_project.dirs import (
+    CLAUDE_MD_IMPORT_LINE,
+    LEGACY_CLAUDE_MD_IMPORT_LINE,
+    LEGACY_OKSTRA_DIR_NAME,
+    LEGACY_OKSTRA_RELATIVE,
+    OKSTRA_DIR_NAME,
+    OKSTRA_RELATIVE,
+)
+
+
+class MigrationRefused(RuntimeError):
+    """Raised when the plan cannot be prepared safely (pre-condition fail)."""
+
+
+@dataclass
+class MigrationPlan:
+    """All work the migrator would perform, as a single inspectable record.
+
+    Render to JSON via `to_dict()` for dry-run output.
+    """
+
+    project_root: Path
+    source_dir: Path  # <project>/.project-docs/okstra
+    target_dir: Path  # <project>/.okstra
+    use_git: bool
+    remove_empty_parent: bool  # True if .project-docs would be empty after move
+    claude_md_path: Optional[Path]  # <project>/CLAUDE.md if import-line update needed
+    gitignore_path: Optional[Path]  # <project>/.gitignore if entry update needed
+    registry_updates: list[dict] = field(default_factory=list)
+    # Each registry entry: {"file": "<abs path>", "row_count": N, "scope": "..."}
+
+    def to_dict(self) -> dict:
+        return {
+            "projectRoot": str(self.project_root),
+            "sourceDir": str(self.source_dir),
+            "targetDir": str(self.target_dir),
+            "useGit": self.use_git,
+            "removeEmptyParent": self.remove_empty_parent,
+            "claudeMdPath": str(self.claude_md_path) if self.claude_md_path else None,
+            "gitignorePath": str(self.gitignore_path) if self.gitignore_path else None,
+            "registryUpdates": self.registry_updates,
+        }
+
+
+@dataclass
+class MigrationResult:
+    """What the apply step actually did. `dry_run=True` returns an unchanged copy
+    of the plan with all `applied_*` flags set to False.
+    """
+
+    dry_run: bool
+    moved: bool
+    parent_removed: bool
+    claude_md_updated: bool
+    gitignore_updated: bool
+    registry_rows_updated: int
+
+    def to_dict(self) -> dict:
+        return {
+            "dryRun": self.dry_run,
+            "moved": self.moved,
+            "parentRemoved": self.parent_removed,
+            "claudeMdUpdated": self.claude_md_updated,
+            "gitignoreUpdated": self.gitignore_updated,
+            "registryRowsUpdated": self.registry_rows_updated,
+        }
+
+
+def prepare_migration_plan(
+    project_root: Path,
+    *,
+    okstra_home: Optional[Path] = None,
+) -> MigrationPlan:
+    """Inspect `project_root` and report what the migration would do.
+
+    Raises `MigrationRefused` when the migration cannot proceed safely:
+    - `.okstra/` already exists (someone migrated, or a collision).
+    - `.project-docs/okstra/` is missing (nothing to migrate).
+    """
+    project_root = Path(project_root).resolve()
+    source = project_root / LEGACY_OKSTRA_RELATIVE
+    target = project_root / OKSTRA_RELATIVE
+
+    if not source.is_dir():
+        raise MigrationRefused(
+            f"no legacy {LEGACY_OKSTRA_DIR_NAME}/ under {project_root}. "
+            f"Either this project was never set up with okstra, or it has "
+            f"already been migrated. ({target}/ {'exists' if target.exists() else 'does not exist'}.)"
+        )
+    if target.exists():
+        raise MigrationRefused(
+            f"refusing to migrate: {target} already exists. "
+            f"Remove it manually if you intend to overwrite, then re-run."
+        )
+
+    use_git = _is_git_worktree(project_root)
+    parent = source.parent  # <project>/.project-docs
+    remove_empty_parent = _would_be_empty_after_remove(parent, source)
+
+    claude_md = project_root / "CLAUDE.md"
+    claude_md_path: Optional[Path] = None
+    if claude_md.is_file():
+        try:
+            text = claude_md.read_text(encoding="utf-8")
+        except OSError:
+            text = ""
+        if LEGACY_CLAUDE_MD_IMPORT_LINE in text:
+            claude_md_path = claude_md
+
+    gitignore = project_root / ".gitignore"
+    gitignore_path: Optional[Path] = None
+    if gitignore.is_file():
+        try:
+            text = gitignore.read_text(encoding="utf-8")
+        except OSError:
+            text = ""
+        if LEGACY_OKSTRA_DIR_NAME in text or f"{LEGACY_OKSTRA_DIR_NAME}/" in text:
+            gitignore_path = gitignore
+
+    registry_updates = _scan_registries(
+        project_root, okstra_home=_resolve_okstra_home(okstra_home)
+    )
+
+    return MigrationPlan(
+        project_root=project_root,
+        source_dir=source,
+        target_dir=target,
+        use_git=use_git,
+        remove_empty_parent=remove_empty_parent,
+        claude_md_path=claude_md_path,
+        gitignore_path=gitignore_path,
+        registry_updates=registry_updates,
+    )
+
+
+def apply_migration_plan(
+    plan: MigrationPlan,
+    *,
+    dry_run: bool = True,
+    okstra_home: Optional[Path] = None,
+) -> MigrationResult:
+    """Execute the migration. When `dry_run=True` (default), returns the
+    no-op result so callers can preview before opting in.
+
+    Failure during any step raises and leaves the project in whatever state
+    that step had reached. No automatic rollback — git mv is the only step
+    that touches the working tree, and a manual `git mv` reverse run is
+    trivial.
+    """
+    if dry_run:
+        return MigrationResult(
+            dry_run=True,
+            moved=False,
+            parent_removed=False,
+            claude_md_updated=False,
+            gitignore_updated=False,
+            registry_rows_updated=0,
+        )
+
+    _do_move(plan)
+    parent_removed = _maybe_remove_empty_parent(plan)
+    claude_md_updated = _update_claude_md(plan)
+    gitignore_updated = _update_gitignore(plan)
+    registry_rows_updated = _apply_registry_updates(
+        plan, okstra_home=_resolve_okstra_home(okstra_home)
+    )
+
+    return MigrationResult(
+        dry_run=False,
+        moved=True,
+        parent_removed=parent_removed,
+        claude_md_updated=claude_md_updated,
+        gitignore_updated=gitignore_updated,
+        registry_rows_updated=registry_rows_updated,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# helpers
+# --------------------------------------------------------------------------- #
+
+
+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"
+
+
+def _is_git_worktree(project_root: Path) -> bool:
+    try:
+        rc = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=str(project_root), capture_output=True, text=True, check=False,
+        )
+    except (OSError, FileNotFoundError):
+        return False
+    return rc.returncode == 0 and bool(rc.stdout.strip())
+
+
+def _would_be_empty_after_remove(parent: Path, child: Path) -> bool:
+    """Return True if `parent` would be empty after `child` is moved out."""
+    if not parent.is_dir():
+        return False
+    try:
+        entries = list(parent.iterdir())
+    except OSError:
+        return False
+    return all(p == child for p in entries)
+
+
+def _do_move(plan: MigrationPlan) -> None:
+    """`git mv` when possible, else regular `os.rename`."""
+    src = plan.source_dir
+    dst = plan.target_dir
+    if plan.use_git:
+        rc = subprocess.run(
+            ["git", "mv", str(src.relative_to(plan.project_root)), str(dst.relative_to(plan.project_root))],
+            cwd=str(plan.project_root), capture_output=True, text=True, check=False,
+        )
+        if rc.returncode != 0:
+            # Surface the actual git error so the user can decide. We do not
+            # fall back to plain mv when git mv fails — the user explicitly
+            # ran inside a git worktree and should see why the move was
+            # rejected (untracked files, conflicting moves, etc.).
+            raise MigrationRefused(
+                f"git mv failed: {rc.stderr.strip() or rc.stdout.strip()}"
+            )
+        return
+    shutil.move(str(src), str(dst))
+
+
+def _maybe_remove_empty_parent(plan: MigrationPlan) -> bool:
+    if not plan.remove_empty_parent:
+        return False
+    parent = plan.source_dir.parent
+    try:
+        if parent.is_dir() and not any(parent.iterdir()):
+            parent.rmdir()
+            return True
+    except OSError:
+        return False
+    return False
+
+
+def _update_claude_md(plan: MigrationPlan) -> bool:
+    if plan.claude_md_path is None:
+        return False
+    text = plan.claude_md_path.read_text(encoding="utf-8")
+    new_text = text.replace(LEGACY_CLAUDE_MD_IMPORT_LINE, CLAUDE_MD_IMPORT_LINE)
+    if new_text == text:
+        return False
+    plan.claude_md_path.write_text(new_text, encoding="utf-8")
+    return True
+
+
+def _update_gitignore(plan: MigrationPlan) -> bool:
+    if plan.gitignore_path is None:
+        return False
+    text = plan.gitignore_path.read_text(encoding="utf-8")
+    # Match both forms: with and without trailing slash. Use word-boundary-ish
+    # replacement by anchoring on the legacy prefix; downstream comment lines
+    # that mention the old path in narrative are left alone because they
+    # never start at line-start with the bare path.
+    new_lines = []
+    changed = False
+    for line in text.splitlines(keepends=True):
+        stripped = line.strip()
+        if stripped == LEGACY_OKSTRA_DIR_NAME or stripped == f"{LEGACY_OKSTRA_DIR_NAME}/":
+            indent = line[: len(line) - len(line.lstrip())]
+            new_lines.append(f"{indent}{OKSTRA_DIR_NAME}/\n")
+            changed = True
+        else:
+            new_lines.append(line)
+    if not changed:
+        return False
+    plan.gitignore_path.write_text("".join(new_lines), encoding="utf-8")
+    return True
+
+
+def _scan_registries(project_root: Path, *, okstra_home: Path) -> list[dict]:
+    """Find okstra-home registry files that reference this project's old path."""
+    project_str = str(project_root)
+    legacy_marker = str(project_root / LEGACY_OKSTRA_RELATIVE)
+    updates: list[dict] = []
+    for name in ("recent.jsonl", "active.jsonl"):
+        path = okstra_home / name
+        if not path.is_file():
+            continue
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except OSError:
+            continue
+        count = sum(
+            1 for ln in lines if legacy_marker in ln or project_str in ln and ".project-docs/okstra" in ln
+        )
+        if count > 0:
+            updates.append({"file": str(path), "rowCount": count, "scope": name})
+    registry = okstra_home / "worktrees" / "registry.json"
+    if registry.is_file():
+        try:
+            text = registry.read_text(encoding="utf-8")
+        except OSError:
+            text = ""
+        if ".project-docs/okstra" in text and project_str in text:
+            updates.append({"file": str(registry), "rowCount": text.count(".project-docs/okstra"), "scope": "worktrees-registry"})
+    return updates
+
+
+def _apply_registry_updates(plan: MigrationPlan, *, okstra_home: Path) -> int:
+    """Rewrite registry files in place. Replaces `.project-docs/okstra` with
+    `.okstra` only on lines that also mention this project's root, so we
+    never touch other projects' rows.
+    """
+    project_str = str(plan.project_root)
+    total = 0
+    for name in ("recent.jsonl", "active.jsonl"):
+        path = okstra_home / name
+        if not path.is_file():
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        new_lines: list[str] = []
+        changed = 0
+        for line in text.splitlines(keepends=True):
+            if project_str in line and LEGACY_OKSTRA_DIR_NAME in line:
+                new_lines.append(line.replace(LEGACY_OKSTRA_DIR_NAME, OKSTRA_DIR_NAME))
+                changed += 1
+            else:
+                new_lines.append(line)
+        if changed:
+            path.write_text("".join(new_lines), encoding="utf-8")
+            total += changed
+    registry = okstra_home / "worktrees" / "registry.json"
+    if registry.is_file():
+        try:
+            text = registry.read_text(encoding="utf-8")
+        except OSError:
+            text = ""
+        # Only mutate when this project's root appears anywhere in the file —
+        # otherwise leave it alone (covers the case where registry.json
+        # contains an unrelated `.project-docs/okstra` literal in someone
+        # else's row).
+        if project_str in text and LEGACY_OKSTRA_DIR_NAME in text:
+            new_text = _replace_in_project_rows(text, project_str)
+            if new_text != text:
+                registry.write_text(new_text, encoding="utf-8")
+                total += text.count(LEGACY_OKSTRA_DIR_NAME) - new_text.count(
+                    LEGACY_OKSTRA_DIR_NAME
+                )
+    return total
+
+
+def _replace_in_project_rows(text: str, project_str: str) -> str:
+    """For registry.json: replace `.project-docs/okstra` with `.okstra` only
+    inside rows that mention `project_str`. registry.json is structured JSON
+    (top-level object with task-key → row), so we operate at the JSON level
+    to avoid clobbering unrelated rows.
+    """
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return text
+    if not isinstance(data, dict):
+        return text
+    changed = False
+    for key, row in data.items():
+        row_text = json.dumps(row)
+        if project_str not in row_text or LEGACY_OKSTRA_DIR_NAME not in row_text:
+            continue
+        new_row_text = row_text.replace(LEGACY_OKSTRA_DIR_NAME, OKSTRA_DIR_NAME)
+        if new_row_text != row_text:
+            data[key] = json.loads(new_row_text)
+            changed = True
+    if not changed:
+        return text
+    return json.dumps(data, indent=2, ensure_ascii=False) + "\n"

package/runtime/python/okstra_ctl/paths.py

@@ -18,11 +18,20 @@ import re
 from pathlib import Path
 from typing import Optional
 
+from okstra_project.dirs import (
+    DISCOVERY_RELATIVE,
+    OKSTRA_RELATIVE,
+    TASKS_RELATIVE,
+)
 from okstra_project.state import slugify
 
-OKSTRA_RELATIVE = Path(".project-docs/okstra")
-TASKS_RELATIVE = OKSTRA_RELATIVE / "tasks"
-DISCOVERY_RELATIVE = OKSTRA_RELATIVE / "discovery"
+__all__ = [
+    "OKSTRA_RELATIVE",
+    "TASKS_RELATIVE",
+    "DISCOVERY_RELATIVE",
+    "compute_run_paths",
+    "next_run_seq",
+]
 
 
 def next_run_seq(run_seq_dir: Path, task_type_segment: str) -> int:

package/runtime/python/okstra_ctl/pr_template.py

@@ -4,7 +4,7 @@ release-handoff 단계에서 lead 가 PR 본문을 작성할 때 사용하는
 템플릿의 경로를 결정한다. 우선순위:
 
     1. per-run override (okstra-run Step 6 에서 입력)
-    2. project: <project_root>/.project-docs/okstra/project.json 의 ``prTemplatePath``
+    2. project: <project_root>/.okstra/project.json 의 ``prTemplatePath``
     3. global:  ~/.okstra/config.json 의 ``prTemplatePath``
     4. default: 스킬 설치 디렉터리의 ``okstra-run/templates/pr-body.template.md``
 
@@ -19,6 +19,8 @@ import os
 from dataclasses import dataclass
 from pathlib import Path
 
+from okstra_project.dirs import project_json_path
+
 _DEFAULT_FILENAME = "pr-body.template.md"
 
 
@@ -86,7 +88,7 @@ def resolve_pr_template_path(
         return ResolvedPrTemplate(path=p, source="override")
 
     # 2) project.json
-    pj_path = Path(project_root) / ".project-docs" / "okstra" / "project.json"
+    pj_path = project_json_path(project_root)
     pj_val = _read_json_field(pj_path, "prTemplatePath")
     if pj_val:
         p = _resolve_project_relative(pj_val, project_root)

package/runtime/python/okstra_ctl/render.py

@@ -22,6 +22,8 @@ import re
 import sys
 from pathlib import Path
 
+from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
+
 
 class TokenRenderError(Exception):
     """Raised when a template references a `{{TOKEN}}` not present in ctx.
@@ -1319,7 +1321,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
 
 
 _NO_MCP_SERVERS_LINE = (
-    "- No MCP servers are declared in `.project-docs/okstra/project.json`'s "
+    f"- No MCP servers are declared in `{OKSTRA_DIR_NAME}/project.json`'s "
     "`mcpServers` array. Treat MCP tools as unavailable for this run. To enable "
     "them, add entries shaped `{name, description, tools, notes?}` to that array "
     "and re-render the bundle."
@@ -1330,12 +1332,12 @@ def build_available_mcp_servers_block(project_root: Path) -> str:
     """Render the `## Available MCP Servers` first bullet from project.json.
 
     The MCP server list used to be hardcoded for one specific environment.
-    It now comes from the project's `.project-docs/okstra/project.json`
-    (`mcpServers` array), so each user/project declares the MCP surface
-    available to their lead+workers. Missing file or empty array yields a
-    generic "none declared" fallback.
+    It now comes from the project's okstra project.json (`mcpServers` array),
+    so each user/project declares the MCP surface available to their
+    lead+workers. Missing file or empty array yields a generic "none declared"
+    fallback.
     """
-    config_path = project_root / ".project-docs" / "okstra" / "project.json"
+    config_path = project_json_path(project_root)
     try:
         raw = json.loads(config_path.read_text(encoding="utf-8"))
     except (FileNotFoundError, json.JSONDecodeError):

package/runtime/python/okstra_ctl/render_final_report.py

@@ -74,7 +74,10 @@ def _format_duration_ms(value: Any) -> str:
     except (TypeError, ValueError):
         return "--"
     total_seconds = ms // 1000
-    minutes, seconds = divmod(total_seconds, 60)
+    hours, remainder = divmod(total_seconds, 3600)
+    minutes, seconds = divmod(remainder, 60)
+    if hours:
+        return f"{hours}h {minutes:02d}m {seconds:02d}s"
     return f"{minutes}m {seconds:02d}s"
 
 

package/runtime/python/okstra_ctl/run.py

@@ -26,7 +26,7 @@ from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
 
-from okstra_project import upsert_project_json
+from okstra_project import project_json_path, upsert_project_json
 from .clarification_items import unresolved_approval_blockers
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
@@ -624,13 +624,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # 쓰이므로 검증도 implementation 진입 시에만 수행한다. 다른 task-type 에서는
     # 잘못된 선언이 있어도 동작에 영향이 없어 fail-fast 할 이유가 없다.
     if inp.task_type == "implementation":
-        project_json_path = Path(project_root) / ".project-docs" / "okstra" / "project.json"
-        if project_json_path.is_file():
+        project_json = project_json_path(project_root)
+        if project_json.is_file():
             try:
-                project_meta = json.loads(project_json_path.read_text())
+                project_meta = json.loads(project_json.read_text())
             except (OSError, json.JSONDecodeError) as exc:
                 raise PrepareError(
-                    f"project.json read failed at {project_json_path}: {exc}"
+                    f"project.json read failed at {project_json}: {exc}"
                 ) from exc
             qa_errors = validate_qa_commands(project_meta.get("qaCommands"))
             if qa_errors:

package/runtime/python/okstra_ctl/seeding.py

@@ -14,6 +14,12 @@ import time
 from pathlib import Path
 from typing import Optional
 
+from okstra_project.dirs import (
+    CLAUDE_MD_IMPORT_LINE,
+    CLAUDE_MD_SYMLINK_RELATIVE,
+    OKSTRA_DIR_NAME,
+)
+
 
 class InstallationError(Exception):
     """okstra 가 깔아둔 런타임 자산이 누락됨."""
@@ -24,7 +30,7 @@ class SettingsLinkError(Exception):
 
 
 class ClaudeMdLinkError(Exception):
-    """`<project>/.project-docs/okstra/CLAUDE.md` symlink or import-block provisioning 실패."""
+    """okstra-relative `CLAUDE.md` symlink or import-block provisioning 실패."""
 
 
 class AgentsMdLinkError(Exception):
@@ -210,8 +216,8 @@ def installed_claude_md_template_path() -> Path:
     return _okstra_home() / "templates" / "okstra.CLAUDE.md"
 
 
-_CLAUDE_MD_SYMLINK_REL = Path(".project-docs") / "okstra" / "CLAUDE.md"
-_CLAUDE_MD_IMPORT_LINE = "@.project-docs/okstra/CLAUDE.md"
+_CLAUDE_MD_SYMLINK_REL = CLAUDE_MD_SYMLINK_RELATIVE
+_CLAUDE_MD_IMPORT_LINE = CLAUDE_MD_IMPORT_LINE
 _CLAUDE_MD_MARKER_BEGIN = (
     "<!-- okstra:claude-md:begin (managed by okstra setup — do not edit) -->"
 )
@@ -219,9 +225,9 @@ _CLAUDE_MD_MARKER_END = "<!-- okstra:claude-md:end -->"
 
 
 def ensure_project_claude_md(*, project_root: Path) -> Optional[Path]:
-    """`<project_root>/.project-docs/okstra/CLAUDE.md` 를 `~/.okstra/templates/okstra.CLAUDE.md`
+    """okstra-relative `CLAUDE.md` 를 `~/.okstra/templates/okstra.CLAUDE.md`
     로 가리키는 symlink 로 provisioning 하고, `<project_root>/CLAUDE.md` 에
-    `@.project-docs/okstra/CLAUDE.md` import block 을 멱등하게 주입한다.
+    import block 을 멱등하게 주입한다.
 
     Claude Code 가 해당 프로젝트에서 host 세션으로 실행될 때
     `<project_root>/CLAUDE.md` 가 자동 로드되므로, okstra 가 관리하는 본문
@@ -339,7 +345,7 @@ def ensure_project_agents_md(*, project_root: Path) -> Optional[Path]:
 
     AGENTS.md 는 codex / aider / 기타 agent 가 읽는 파일이고 @import 같은
     부분 포함 메커니즘이 없어, 파일 전체 내용이 곧 agent 가 보는 콘텐츠가
-    된다. 그래서 CLAUDE.md (`@.project-docs/okstra/CLAUDE.md` 마커 블록
+    된다. 그래서 CLAUDE.md (`@.okstra/CLAUDE.md` 마커 블록
     주입) 와 달리 "AGENTS.md 가 비어 있을 때만 만들고, 존재하면 절대
     건드리지 않는" 정책을 사용한다 — 사용자가 직접 작성한 AGENTS.md 를
     덮어쓰지 않는다.

package/runtime/python/okstra_ctl/sequence.py

@@ -5,6 +5,8 @@ import re as _re
 from pathlib import Path
 from typing import Optional
 
+from okstra_project.dirs import tasks_root
+
 from .ids import slugify_task_segment
 from .jsonl import read_jsonl
 
@@ -24,7 +26,7 @@ def predict_next_run_seq(project_root: Path, task_group: str, task_id: str,
     이 셋의 max + 1 이 안전한 다음 seq.
     """
     task_type_segment = slugify_task_segment(task_type)
-    base = (project_root / ".project-docs" / "okstra" / "tasks"
+    base = (tasks_root(project_root)
             / slugify_task_segment(task_group) / slugify_task_segment(task_id)
             / "runs" / task_type_segment)
     max_seq = 0