okstra 0.34.1 → 0.36.1

package/runtime/python/okstra_ctl/run_context.py

@@ -50,6 +50,15 @@ def _task_lock_path(task_key: str) -> Path:
     return locks / f"{safe}.lock"
 
 
+def _consumers_lock_path(plan_task_key: str) -> Path:
+    """plan-task-key 별 consumers.jsonl append mutex."""
+    home = _okstra_home()
+    locks = home / ".locks"
+    locks.mkdir(parents=True, exist_ok=True)
+    safe = plan_task_key.replace("/", "_").replace(":", "_")
+    return locks / f"{safe}.consumers.lock"
+
+
 @contextmanager
 def task_mutex(task_key: str) -> Iterator[None]:
     """task-key per-process mutex. 동시 호출은 락 안에서 직렬화된다."""
@@ -63,6 +72,19 @@ def task_mutex(task_key: str) -> Iterator[None]:
             fcntl.flock(f.fileno(), fcntl.LOCK_UN)
 
 
+@contextmanager
+def consumers_mutex(plan_task_key: str) -> Iterator[None]:
+    """plan-task-key 별 consumers.jsonl append mutex."""
+    path = _consumers_lock_path(plan_task_key)
+    path.touch(exist_ok=True)
+    with path.open("r+") as f:
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+
+
 def _atomic_write_json(path: Path, payload: dict) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     tmp = path.with_suffix(path.suffix + ".tmp")

package/runtime/python/okstra_ctl/seeding.py

@@ -23,6 +23,14 @@ class SettingsLinkError(Exception):
     """`<project>/.claude/settings.local.json` symlink provisioning 실패."""
 
 
+class ClaudeMdLinkError(Exception):
+    """`<project>/.project-docs/okstra/CLAUDE.md` symlink or import-block provisioning 실패."""
+
+
+class AgentsMdLinkError(Exception):
+    """`<project>/AGENTS.md` symlink provisioning 실패."""
+
+
 def installed_version() -> str:
     """Read the version stamp written by `okstra install` to `~/.okstra/version`.
 
@@ -195,3 +203,181 @@ def _backup_and_replace(target: Path, template: Path) -> None:
         raise SettingsLinkError(
             f"failed to create symlink {target} -> {template} after backup: {exc}"
         ) from exc
+
+
+def installed_claude_md_template_path() -> Path:
+    """okstra install 이 만들어 둔 okstra.CLAUDE.md template 의 절대경로."""
+    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_MARKER_BEGIN = (
+    "<!-- okstra:claude-md:begin (managed by okstra setup — do not edit) -->"
+)
+_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`
+    로 가리키는 symlink 로 provisioning 하고, `<project_root>/CLAUDE.md` 에
+    `@.project-docs/okstra/CLAUDE.md` import block 을 멱등하게 주입한다.
+
+    Claude Code 가 해당 프로젝트에서 host 세션으로 실행될 때
+    `<project_root>/CLAUDE.md` 가 자동 로드되므로, okstra 가 관리하는 본문
+    (slash command catalog, workflow guidance, ...) 도 같이 surface 된다.
+
+    반환값:
+      - symlink Path: 신규 생성됐거나 이미 올바른 target 을 가리키고 있을 때.
+      - None: install 이 아직 CLAUDE.md template 을 깔지 않았을 때 (구버전
+        okstra install). 상위에서 경고로 흘려보낸다.
+
+    상위 호출자는 `ClaudeMdLinkError` 만 처리하면 된다.
+    """
+    project_root = Path(project_root)
+    template = installed_claude_md_template_path()
+    if not template.exists():
+        return None
+
+    target = project_root / _CLAUDE_MD_SYMLINK_REL
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    if target.is_symlink():
+        try:
+            current = os.readlink(target)
+        except OSError as exc:
+            raise ClaudeMdLinkError(
+                f"failed to read existing symlink {target}: {exc}"
+            ) from exc
+        current_path = Path(current)
+        if current_path == template or (target.parent / current_path).resolve() == template.resolve():
+            _ensure_claude_md_import(project_root)
+            return target
+        _backup_and_replace_claude_md(target, template)
+        _ensure_claude_md_import(project_root)
+        return target
+
+    if target.exists():
+        _backup_and_replace_claude_md(target, template)
+        _ensure_claude_md_import(project_root)
+        return target
+
+    try:
+        target.symlink_to(template)
+    except OSError as exc:
+        raise ClaudeMdLinkError(
+            f"failed to create symlink {target} -> {template}: {exc}"
+        ) from exc
+    _ensure_claude_md_import(project_root)
+    return target
+
+
+def _ensure_claude_md_import(project_root: Path) -> bool:
+    """`<project_root>/CLAUDE.md` 에 import block 이 없으면 append, 있으면 no-op.
+
+    반환: 새로 주입했을 때 True, 이미 있었을 때 False.
+    """
+    claude_md = project_root / "CLAUDE.md"
+    block = f"{_CLAUDE_MD_MARKER_BEGIN}\n{_CLAUDE_MD_IMPORT_LINE}\n{_CLAUDE_MD_MARKER_END}\n"
+
+    try:
+        existing = claude_md.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        try:
+            claude_md.write_text(block, encoding="utf-8")
+        except OSError as exc:
+            raise ClaudeMdLinkError(
+                f"failed to create {claude_md}: {exc}"
+            ) from exc
+        return True
+    except OSError as exc:
+        raise ClaudeMdLinkError(f"failed to read {claude_md}: {exc}") from exc
+
+    if _CLAUDE_MD_MARKER_BEGIN in existing and _CLAUDE_MD_MARKER_END in existing:
+        return False
+
+    separator = _block_separator_for(existing)
+    try:
+        claude_md.write_text(existing + separator + block, encoding="utf-8")
+    except OSError as exc:
+        raise ClaudeMdLinkError(f"failed to update {claude_md}: {exc}") from exc
+    return True
+
+
+def _block_separator_for(existing: str) -> str:
+    """기존 파일 끝과 import block 사이의 공백 결정 — 가독성 보장 목적."""
+    if not existing:
+        return ""
+    if existing.endswith("\n\n"):
+        return ""
+    if existing.endswith("\n"):
+        return "\n"
+    return "\n\n"
+
+
+def _backup_and_replace_claude_md(target: Path, template: Path) -> None:
+    """기존 파일/심볼릭링크를 timestamped backup 으로 옮기고 새 symlink 생성."""
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    backup = target.with_name(f"{target.name}.bak.{stamp}")
+    try:
+        target.rename(backup)
+    except OSError as exc:
+        raise ClaudeMdLinkError(
+            f"failed to back up existing {target} to {backup}: {exc}"
+        ) from exc
+    try:
+        target.symlink_to(template)
+    except OSError as exc:
+        raise ClaudeMdLinkError(
+            f"failed to create symlink {target} -> {template} after backup: {exc}"
+        ) from exc
+
+
+def ensure_project_agents_md(*, project_root: Path) -> Optional[Path]:
+    """`<project_root>/AGENTS.md` 가 없을 때만 `~/.okstra/templates/okstra.CLAUDE.md`
+    로의 심링크로 생성한다.
+
+    AGENTS.md 는 codex / aider / 기타 agent 가 읽는 파일이고 @import 같은
+    부분 포함 메커니즘이 없어, 파일 전체 내용이 곧 agent 가 보는 콘텐츠가
+    된다. 그래서 CLAUDE.md (`@.project-docs/okstra/CLAUDE.md` 마커 블록
+    주입) 와 달리 "AGENTS.md 가 비어 있을 때만 만들고, 존재하면 절대
+    건드리지 않는" 정책을 사용한다 — 사용자가 직접 작성한 AGENTS.md 를
+    덮어쓰지 않는다.
+
+    반환값:
+      - target Path: 신규 심링크 생성, 또는 이미 우리 템플릿을 가리키고
+        있던 심링크가 idempotent 하게 확인된 경우.
+      - None: install 이 아직 CLAUDE.md template 을 깔지 않았거나,
+        AGENTS.md 가 이미 사용자 콘텐츠 (regular file) 거나 우리가
+        만들지 않은 다른 심링크로 존재하는 경우. 후자 두 케이스는
+        사용자의 의도로 간주하고 건드리지 않는다.
+
+    상위 호출자는 `AgentsMdLinkError` 만 처리하면 된다.
+    """
+    project_root = Path(project_root)
+    template = installed_claude_md_template_path()
+    if not template.exists():
+        return None
+
+    target = project_root / "AGENTS.md"
+
+    if target.is_symlink():
+        try:
+            current = os.readlink(target)
+        except OSError:
+            return None
+        current_path = Path(current)
+        if current_path == template or (target.parent / current_path).resolve() == template.resolve():
+            return target
+        return None  # foreign symlink — respect user
+
+    if target.exists():
+        return None  # regular file — respect user content
+
+    try:
+        target.symlink_to(template)
+    except OSError as exc:
+        raise AgentsMdLinkError(
+            f"failed to create symlink {target} -> {template}: {exc}"
+        ) from exc
+    return target

package/runtime/python/okstra_ctl/session.py

@@ -49,18 +49,76 @@ def resolve_inproc_lead_session_id(project_root: Path) -> str:
 
 
 def write_claude_resume_command_file(
-    *, resume_command_path: Path, project_root: Path, claude_session_id: str,
+    *,
+    resume_command_path: Path,
+    project_root: Path,
+    claude_session_id: str,
+    task_key: str,
+    task_type: str,
+    phase_state: str,
+    worker_prompts_dir_relative: str,
+    prompt_seq: str,
 ) -> None:
     """`bash claude-resume-*.sh` 를 실행하면 task 의 claude 세션을 resume
     하도록 shell 스크립트를 작성하고 chmod +x.
+
+    `claude --resume` 자체는 직전 세션 context 만 복구하고 lead 는
+    사용자 입력 대기 상태로 멈춘다. 따라서 사용자가 resume 후 무엇을
+    입력해야 하는지를 안내하는 guidance 블록을 sh 안에 inline 한다 —
+    sh 가 실행될 때 worker prompt 디스크 존재 여부를 직접 검사해
+    Phase 2 부터 / Phase 3 부터 중 알맞은 다음 명령을 추천한다.
     """
     resume_command_path = Path(resume_command_path)
     resume_command_path.parent.mkdir(parents=True, exist_ok=True)
-    body = (
-        "#!/usr/bin/env bash\n"
-        "# Generated by okstra. Resume the prepared Claude session for this run.\n"
-        f'cd "{project_root}"\n'
-        f'exec claude --resume "{claude_session_id}"\n'
-    )
+    body = f"""#!/usr/bin/env bash
+# Generated by okstra. Resume the prepared Claude session for this run.
+
+TASK_KEY={_sh_single_quote(task_key)}
+TASK_TYPE={_sh_single_quote(task_type)}
+PHASE_STATE={_sh_single_quote(phase_state)}
+PROJECT_ROOT={_sh_single_quote(str(project_root))}
+WORKER_PROMPTS_DIR="$PROJECT_ROOT/{worker_prompts_dir_relative}"
+PROMPT_SEQ={_sh_single_quote(prompt_seq)}
+SESSION_ID={_sh_single_quote(claude_session_id)}
+
+cat >&2 <<EOF
+============================================================
+okstra resume — $TASK_KEY
+Phase: $TASK_TYPE ($PHASE_STATE)
+============================================================
+
+이 스크립트는 Claude 세션 context 만 복구합니다.
+Lead 는 resume 직후 자동으로 진행하지 않으니, 첫 메시지로 다음을
+그대로 (또는 상황에 맞게 수정해서) 입력하세요:
+
+EOF
+
+if compgen -G "$WORKER_PROMPTS_DIR/*-worker-prompt-$TASK_TYPE-$PROMPT_SEQ.md" > /dev/null 2>&1; then
+  cat >&2 <<EOF
+  Phase 3 부터 진행 — TeamCreate 후 Phase 4 worker dispatch 까지.
+  Worker prompts (이미 작성·저장됨):
+    $WORKER_PROMPTS_DIR/*-worker-prompt-$TASK_TYPE-$PROMPT_SEQ.md
+EOF
+else
+  cat >&2 <<EOF
+  Phase 2 부터 진행 — worker prompts 작성·저장 후 Phase 3 진행.
+  Prompts directory (현재 비어 있음):
+    $WORKER_PROMPTS_DIR
+EOF
+fi
+
+cat >&2 <<EOF
+
+============================================================
+EOF
+
+cd "$PROJECT_ROOT"
+exec claude --resume "$SESSION_ID"
+"""
     resume_command_path.write_text(body, encoding="utf-8")
     os.chmod(resume_command_path, 0o755)
+
+
+def _sh_single_quote(value: str) -> str:
+    """POSIX-safe single-quote: `it's` → `'it'"'"'s'`."""
+    return "'" + value.replace("'", "'\"'\"'") + "'"