okstra 0.97.1 → 0.98.0

package/docs/superpowers/plans/2026-06-21-okstra-container-local-user-test.md

@@ -0,0 +1,714 @@
+# okstra-container 로컬 유저-테스트 컨테이너 오케스트레이션 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 검증된(또는 임의) task-id 의 코드를 기존 `docker-compose.yml` 을 재사용해 task 별 컨테이너 그룹으로 띄우고, detached tmux 세션에서 컨테이너별 watcher 로 상시 감시하는 비선형 스킬 `okstra-container` 를 추가한다.
+
+**Architecture:** PHASE_SEQUENCE 밖의 sub-command 디스패치 스킬(`okstra-inspect` 골격 복제). 모든 진입(스킬/`bin okstra`/`okstra.sh`)은 신규 python entrypoint `scripts/okstra_ctl/container.py::provision_container_group()` 로 수렴(단일 참조점). 산출물은 전부 `.okstra/tasks/<group>/<task-id>/container/` 아래. 컨테이너 존재 SSOT 는 docker 라벨, `registry.json` 은 보조 인덱스.
+
+**Tech Stack:** Python 3 (`scripts/okstra_ctl/`), Node ESM (`src/commands/`), Bash (e2e), docker compose, tmux.
+
+**관련 스펙:** [2026-06-21-okstra-container-local-user-test-design.md](../specs/2026-06-21-okstra-container-local-user-test-design.md)
+
+## Global Constraints
+
+- **오케스트레이션형(B):** 설정 파일을 **절대 생성하지 않는다.** `docker-compose.yml` 부재 시 무엇이 없는지 명시하고 `PrepareError` 로 중단. Dockerfile 단독도 동일 중단.
+- **단일 참조점:** 스킬/`bin okstra`/`okstra.sh` 는 모두 `provision_container_group()` (및 sub-command 디스패치)로 수렴. 한 진입점이 다른 진입점을 래핑 금지.
+- **artifact-home:** okstra 산출물은 전부 `<PROJECT_ROOT>/.okstra/` 아래. 원본 프로젝트 파일 변경 금지. compose 입력 `.env` 는 worktree(okstra 소유) 기준으로 해소.
+- **explicit args over env:** 모든 튜닝 값(`scan_interval_seconds`, `healthcheck_timeout_seconds`, `healthcheck_interval_seconds`)은 named 인자. env var 금지.
+- **미러 트리:** python 로직은 `scripts/okstra_ctl/` 만 편집하고 `npm run build` 가 `runtime/python/okstra_ctl/` 를 재생성. **모든 task 완료 전 `npm run build` 1회 필수.** (테스트는 `scripts/` 를 직접 import 하므로 build 누락이 단위 테스트로 안 잡힌다.)
+- **CI = `npm run check`:** 완료 선언 전 `npm run check` 가 exit 0 이어야 한다(test:js 실패 시 test:py 안 돔).
+- **함수 길이:** 신규/대폭 수정 함수는 유효 50줄 이하. 초과 시 분할.
+- **tmux 가용성 SSOT:** `tmux_available()` ([scripts/okstra_ctl/tmux.py:42](../../../scripts/okstra_ctl/tmux.py)) 한 곳. `process.env.TMUX` 판정 금지.
+
+---
+
+## File Structure
+
+**신규 (python):**
+- `scripts/okstra_ctl/container.py` — entrypoint(`provision_container_group`, sub-command `main`), env override 합성, compose argv, watcher loop.
+- `scripts/okstra_ctl/container_registry.py` — flock-guarded 보조 인덱스(session/pane/findings).
+
+**수정 (python):**
+- `scripts/okstra_ctl/paths.py` — `container_paths()` 순수 경로 계산.
+- `scripts/okstra_ctl/ids.py` — `compose_project_name()`, `build_container_session_name()`.
+- `scripts/okstra_ctl/stage_integrate.py` — `integrate_stages(..., teardown=True)` 토글.
+- `scripts/okstra_ctl/stage_targets.py` — `resolve_and_integrate_whole_task()` 공유 헬퍼.
+- `scripts/okstra_ctl/run.py` — final-verification 분기를 공유 헬퍼 호출로 치환.
+- `scripts/okstra_ctl/tmux.py` — `new_detached_session()`, `split_container_pane()`(신규 `@okstra_container_run` 태그).
+
+**신규/수정 (Node):**
+- `src/commands/inspect/container.mjs` — thin shim → python 위임.
+- `src/cli-registry.mjs` — `container` 명령 등록.
+- `src/lib/skill-catalog.mjs` — `USER_SKILL_NAMES` 에 `okstra-container`.
+- `.claude-plugin/plugin.json` — skills 배열에 동순서 추가.
+- `src/commands/lifecycle/doctor.mjs` — docker WARN 점검(별도 변수).
+- `templates/reports/settings.template.json` — docker 권한 시드.
+
+**신규 (스킬/문서):**
+- `skills/okstra-container/SKILL.md`
+
+**신규 (테스트):**
+- `tests/container/test_*.py` (신규 도메인 폴더)
+- `tests-js/cli-registry.test.mjs` 등 카운트 갱신
+- `tests-e2e/scenario-15-okstra-container-up-down.sh`
+
+---
+
+## Task 1: container 경로/네이밍 순수 헬퍼
+
+**Files:**
+- Modify: `scripts/okstra_ctl/paths.py` (참고: `task_dir` 정의부, `compute_run_paths` 반환 dict 패턴)
+- Modify: `scripts/okstra_ctl/ids.py` (참고: `slugify_task_segment` ≈ line 82, `_safe_fs_segment` ≈ line 48)
+- Test: `tests/container/test_okstra_container_paths.py`
+
+**Interfaces:**
+- Produces:
+  - `container_paths(project_root, task_group, task_id) -> dict` — keys: `container_dir`, `env_override`, `registry`, `registry_lock`, `deploy_state`, `watchers_dir` (모두 `pathlib.Path`).
+  - `compose_project_name(project_id, task_group, task_id) -> str` — `^[a-z0-9][a-z0-9_-]*$`, 길이 상한 `CONTAINER_PROJECT_NAME_MAX = 60`.
+
+- [ ] **Step 1: 실패 테스트 작성** — `tests/container/test_okstra_container_paths.py`
+
+```python
+import sys
+from pathlib import Path
+from _paths import REPO_ROOT  # tests/_paths.py 의 헤더 패턴 그대로
+
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from okstra_ctl import paths, ids  # noqa: E402
+
+
+def test_container_paths_under_task_root(tmp_path):
+    p = paths.container_paths(tmp_path, "Auth Work", "TASK-42")
+    base = tmp_path / ".okstra" / "tasks" / "auth-work" / "task-42" / "container"
+    assert p["container_dir"] == base
+    assert p["env_override"] == base / "env.override"
+    assert p["registry"] == base / "registry.json"
+    assert p["registry_lock"] == base / "registry.json.lock"
+    assert p["deploy_state"] == base / "deploy-state.json"
+    assert p["watchers_dir"] == base / "watchers"
+
+
+def test_compose_project_name_is_docker_safe():
+    name = ids.compose_project_name("proj", "grp", "task-1")
+    assert name == "okstra-proj-grp-task-1"
+    import re
+    assert re.fullmatch(r"[a-z0-9][a-z0-9_-]*", name)
+
+
+def test_compose_project_name_truncates_preserving_task(tmp_path):
+    name = ids.compose_project_name("p" * 40, "g" * 40, "task-keep")
+    assert len(name) <= ids.CONTAINER_PROJECT_NAME_MAX
+    assert name.endswith("task-keep")
+    import re
+    assert re.fullmatch(r"[a-z0-9][a-z0-9_-]*", name)
+
+
+def test_compose_project_name_all_nonalnum_segments():
+    name = ids.compose_project_name("***", "###", "ok")
+    import re
+    assert re.fullmatch(r"[a-z0-9][a-z0-9_-]*", name)  # 빈 슬러그/연속 하이픈 없음
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/container/test_okstra_container_paths.py -v`
+Expected: FAIL (`AttributeError: module 'okstra_ctl.paths' has no attribute 'container_paths'`)
+
+- [ ] **Step 3: `container_paths` 구현** — `scripts/okstra_ctl/paths.py` 에 추가. 기존 `task_dir`/slug 헬퍼를 재사용한다(레포의 실제 `task_dir` 시그니처를 먼저 확인하고 그 슬러그 규칙을 그대로 통과시킬 것 — 라벨↔경로 일치를 위해).
+
+```python
+def container_paths(project_root, task_group, task_id):
+    """container 산출물 경로 묶음(순수 계산, mkdir 금지)."""
+    base = task_dir(project_root, task_group, task_id) / "container"
+    return {
+        "container_dir": base,
+        "env_override": base / "env.override",
+        "registry": base / "registry.json",
+        "registry_lock": base / "registry.json.lock",
+        "deploy_state": base / "deploy-state.json",
+        "watchers_dir": base / "watchers",
+    }
+```
+
+- [ ] **Step 4: `compose_project_name` 구현** — `scripts/okstra_ctl/ids.py` 에 추가. **세그먼트 정규화는 `task_dir` 가 쓰는 slug 함수와 동일 함수**를 사용해 라벨↔경로 일치를 보장한다(리뷰 minor: slug 분기 방지).
+
+```python
+CONTAINER_PROJECT_NAME_MAX = 60
+
+
+def compose_project_name(project_id, task_group, task_id):
+    def seg(v):
+        s = slugify_task_segment(v)  # task_dir 가 쓰는 동일 slug 함수 사용
+        return s or "x"  # 빈 슬러그 방지(docker 는 비어있지 않은 [a-z0-9] 시작 요구)
+    proj, grp, task = seg(project_id), seg(task_group), seg(task_id)
+    name = f"okstra-{proj}-{grp}-{task}"
+    if len(name) <= CONTAINER_PROJECT_NAME_MAX:
+        return name
+    # task-id 세그먼트 우선 보존: 뒤에서부터 채우고 앞 세그먼트를 깎는다
+    tail = f"-{task}"
+    budget = CONTAINER_PROJECT_NAME_MAX - len("okstra") - len(tail)
+    head = f"-{proj}-{grp}"[:max(budget, 0)].rstrip("-")
+    return f"okstra{head}{tail}"
+```
+
+- [ ] **Step 5: 통과 확인 + slug 일치 회귀 단언 추가** — 두 slug 함수가 같은 입력에 같은 출력을 내는지 단언을 테스트에 추가(리뷰 minor).
+
+Run: `python3 -m pytest tests/container/test_okstra_container_paths.py -v`
+Expected: PASS (4 tests)
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/paths.py scripts/okstra_ctl/ids.py tests/container/test_okstra_container_paths.py
+git commit -m "feat(container): container 경로/compose project name 순수 헬퍼"
+```
+
+---
+
+## Task 2: whole-task 통합 공유 헬퍼 추출 (단일 참조점)
+
+**배경:** final-verification 의 whole-task stage 통합은 `run.py` 의 `_reserve_final_verification_target` else 분기(≈1519-1543, [run.py](../../../scripts/okstra_ctl/run.py))에 인라인돼 있고 `ctx`/`PrepareInputs` 에 강결합돼 직접 호출 불가. 그대로 래핑하면 단일 참조점 위반 → 순수 헬퍼로 추출한다. `integrate_stages` 는 Phase B 에서 stage worktree teardown 까지 수행하므로 컨테이너용 `teardown=False` 토글이 필요(스펙 §10: 컨테이너는 머지만, stage 트리 보존).
+
+**Files:**
+- Modify: `scripts/okstra_ctl/stage_integrate.py` (`integrate_stages` / `_teardown_all`)
+- Modify: `scripts/okstra_ctl/stage_targets.py` (`resolve_whole_task_target`, `is_dirty_excluding_okstra`)
+- Modify: `scripts/okstra_ctl/run.py` (`_reserve_final_verification_target` else 분기)
+- Test: `tests/container/test_resolve_and_integrate_whole_task.py`
+
+**Interfaces:**
+- Produces:
+  - `integrate_stages(..., teardown: bool = True)` — `False` 면 Phase B(`_teardown_all`) skip. 기존 호출부 행위 불변(기본 True).
+  - `resolve_and_integrate_whole_task(*, project_id, task_group, task_id, task_worktree_path, stage_map, done_rows, anchor_base, teardown) -> dict` — `{head_commit, merged_stage_map, target_ref}` 등. 충돌 시 `PrepareError`, dirty 시 거부.
+
+- [ ] **Step 1: `teardown` 토글 실패 테스트** — `tests/container/test_resolve_and_integrate_whole_task.py`
+
+```python
+import sys
+from _paths import REPO_ROOT
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from okstra_ctl import stage_integrate  # noqa: E402
+import inspect
+
+
+def test_integrate_stages_has_teardown_toggle():
+    sig = inspect.signature(stage_integrate.integrate_stages)
+    assert "teardown" in sig.parameters
+    assert sig.parameters["teardown"].default is True
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/container/test_resolve_and_integrate_whole_task.py -v`
+Expected: FAIL (`teardown` 파라미터 없음)
+
+- [ ] **Step 3: `teardown` 토글 추가** — `scripts/okstra_ctl/stage_integrate.py`. `integrate_stages` 시그니처에 `teardown: bool = True` 추가, Phase B 직전에 `if teardown:` 가드. 기존 `run.py` 호출은 기본값으로 행위 불변.
+
+- [ ] **Step 4: `resolve_and_integrate_whole_task` 실패 테스트(통합 동작)** — 임시 git worktree + stage 더미 fixture 로:
+
+```python
+def test_whole_task_keeps_stage_trees_when_teardown_false(container_task_fixture):
+    res = stage_targets.resolve_and_integrate_whole_task(
+        teardown=False, **container_task_fixture.kwargs)
+    assert res["head_commit"]
+    assert container_task_fixture.stage_worktree.exists()  # 보존
+
+
+def test_whole_task_rejects_dirty_non_okstra(container_task_fixture):
+    container_task_fixture.write_dirty("src/x.py")
+    with pytest.raises(stage_targets.PrepareError):
+        stage_targets.resolve_and_integrate_whole_task(
+            teardown=False, **container_task_fixture.kwargs)
+```
+
+> fixture(`container_task_fixture`)는 `tests/conftest.py` 격리 홈 패턴을 따르고, `git init` 한 task worktree + 1개 done stage 를 만든다. 충돌 케이스는 같은 파일을 두 stage 가 다르게 수정해 머지 충돌을 유도.
+
+- [ ] **Step 5: 실패 확인**
+
+Run: `python3 -m pytest tests/container/test_resolve_and_integrate_whole_task.py -v`
+Expected: FAIL (`resolve_and_integrate_whole_task` 없음)
+
+- [ ] **Step 6: 헬퍼 구현** — `scripts/okstra_ctl/stage_targets.py`. `integrate_stages(teardown=...)` 호출 → `IntegrateError`→`PrepareError` 변환 → `git rev-parse HEAD` → done `head_commit` ancestor 기반 merged map 계산(run.py 의 ground-truth 패턴 그대로) → `resolve_whole_task_target` 게이트 강제 → `is_dirty_excluding_okstra` 거부 게이트. 50줄 초과 시 ancestor-map 계산을 작은 헬퍼로 분리.
+
+- [ ] **Step 7: `run.py` 분기 치환** — `_reserve_final_verification_target` else 분기의 인라인 로직을 `resolve_and_integrate_whole_task(teardown=True, ...)` 호출로 치환. `ctx` 주입은 run.py 측 유지(ctx 결합은 run 전용).
+
+- [ ] **Step 8: 통과 + final-verification 회귀 확인**
+
+Run: `python3 -m pytest tests/container/test_resolve_and_integrate_whole_task.py tests/run/ -v`
+Expected: PASS (신규 + 기존 final-verification 테스트 회귀 없음)
+
+- [ ] **Step 9: 커밋**
+
+```bash
+git add scripts/okstra_ctl/stage_integrate.py scripts/okstra_ctl/stage_targets.py scripts/okstra_ctl/run.py tests/container/test_resolve_and_integrate_whole_task.py
+git commit -m "refactor(container): whole-task 통합을 teardown 토글 공유 헬퍼로 추출"
+```
+
+---
+
+## Task 3: container registry (flock-guarded 보조 인덱스)
+
+**Files:**
+- Create: `scripts/okstra_ctl/container_registry.py` (참고: `worktree_registry.py` 의 `_registry_lock`/`_load`/`_save` ≈80-122 — fcntl.flock LOCK_EX contextmanager + tmp+`os.replace` 원자 쓰기)
+- Test: `tests/container/test_okstra_container_registry.py`
+
+**Interfaces:**
+- Consumes: `paths.container_paths()` (Task 1) 의 `registry`, `registry_lock`.
+- Produces:
+  - `reserve(project_root, group, task_id, service, *, session_name, pane_id, findings_path) -> None`
+  - `lookup(project_root, group, task_id) -> dict` — `{"services": {svc: {session_name, pane_id, findings_path}}}`
+  - `release(project_root, group, task_id, service) -> None`
+  - `clear(project_root, group, task_id) -> None`
+
+- [ ] **Step 1: 왕복 실패 테스트** — `tests/container/test_okstra_container_registry.py`
+
+```python
+import sys
+from _paths import REPO_ROOT
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from okstra_ctl import container_registry as cr  # noqa: E402
+
+
+def test_reserve_then_lookup_roundtrip(tmp_path):
+    cr.reserve(tmp_path, "g", "t1", "web",
+               session_name="okstra-container-t1", pane_id="%5",
+               findings_path="/x/web-findings.md")
+    got = cr.lookup(tmp_path, "g", "t1")
+    assert got["services"]["web"]["pane_id"] == "%5"
+
+
+def test_release_removes_service(tmp_path):
+    cr.reserve(tmp_path, "g", "t1", "web", session_name="s", pane_id="%1", findings_path="f")
+    cr.release(tmp_path, "g", "t1", "web")
+    assert "web" not in cr.lookup(tmp_path, "g", "t1")["services"]
+
+
+def test_clear_empties_registry(tmp_path):
+    cr.reserve(tmp_path, "g", "t1", "web", session_name="s", pane_id="%1", findings_path="f")
+    cr.clear(tmp_path, "g", "t1")
+    assert cr.lookup(tmp_path, "g", "t1")["services"] == {}
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/container/test_okstra_container_registry.py -v`
+Expected: FAIL (모듈 없음)
+
+- [ ] **Step 3: 구현** — `worktree_registry.py` 의 flock + 원자 쓰기 패턴을 복제하되, lock/registry 경로는 `container_paths()` 로 해소(전역 `worktrees/registry.json` 과 분리). 가벼운 dict 구조만 사용(무거운 dataclass 금지). 누락 파일은 `{"services": {}}` 로 초기화.
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/container/test_okstra_container_registry.py -v`
+Expected: PASS (3 tests)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/container_registry.py tests/container/test_okstra_container_registry.py
+git commit -m "feat(container): flock-guarded container registry 보조 인덱스"
+```
+
+---
+
+## Task 4: env.override 합성 + compose argv (순수 함수)
+
+**Files:**
+- Create: `scripts/okstra_ctl/container.py` (이 task 는 순수 함수 스켈레톤만)
+- Test: `tests/container/test_container_compose_argv.py`
+
+**Interfaces:**
+- Consumes: Task 1 `container_paths`, `compose_project_name`.
+- Produces:
+  - `merge_env(base_env: dict, override: dict) -> dict` — override 가 동일 키를 덮어씀(순수).
+  - `build_compose_up_argv(*, project_name, worktree_env_path, override_env_path, labels: dict) -> list[str]` — `--env-file` 순서 = worktree → override, 라벨 인자 포함.
+  - `OKSTRA_LABEL_KEYS = ("okstra.task-key", "okstra.project-name", "okstra.run-trace")`
+
+- [ ] **Step 1: 실패 테스트** — `tests/container/test_container_compose_argv.py`
+
+```python
+import sys
+from _paths import REPO_ROOT
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from okstra_ctl import container  # noqa: E402
+
+
+def test_merge_env_override_wins():
+    assert container.merge_env({"A": "1", "B": "2"}, {"B": "9"}) == {"A": "1", "B": "9"}
+
+
+def test_compose_argv_env_file_order():
+    argv = container.build_compose_up_argv(
+        project_name="okstra-p-g-t", worktree_env_path="/wt/.env",
+        override_env_path="/ok/env.override",
+        labels={"okstra.task-key": "p:g:t"})
+    i = argv.index("--env-file")
+    assert argv[i + 1] == "/wt/.env"
+    j = argv.index("--env-file", i + 1)
+    assert argv[j + 1] == "/ok/env.override"  # override 가 나중(우선)
+    assert "-p" in argv and "okstra-p-g-t" in argv
+
+
+def test_compose_argv_carries_okstra_labels():
+    argv = container.build_compose_up_argv(
+        project_name="n", worktree_env_path="a", override_env_path="b",
+        labels={k: "v" for k in container.OKSTRA_LABEL_KEYS})
+    joined = " ".join(argv)
+    for k in container.OKSTRA_LABEL_KEYS:
+        assert f"{k}=v" in joined
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/container/test_container_compose_argv.py -v`
+Expected: FAIL (모듈/함수 없음)
+
+- [ ] **Step 3: 구현** — `scripts/okstra_ctl/container.py` 생성. `merge_env`, `build_compose_up_argv`(`["docker","compose","-p",name,"--env-file",wt,"--env-file",override,"up","-d"]` + 라벨 `--label k=v`), `OKSTRA_LABEL_KEYS`. 라벨은 compose 의 프로젝트 레벨이 아니라 서비스 컨테이너에 붙어야 하므로, compose 가 라벨 주입을 직접 지원 안 하면 `up` 후 `docker compose ps -q` → `docker label` 대신 compose override 파일(`-f`)로 `labels:` 주입하는 방식을 택한다(구현 시 docker compose 버전 동작을 context7/docs 로 확인 — 라벨 주입 메커니즘이 버전 의존적).
+
+> ⚠️ 구현 노트: compose 의 컨테이너 라벨 주입 방식(`x-` 확장 vs override `-f` vs `up --label` 미지원)을 실제 docker compose 문서로 확인할 것. SSOT 가 라벨이므로 라벨이 실제로 컨테이너에 붙는지가 핵심.
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/container/test_container_compose_argv.py -v`
+Expected: PASS (3 tests)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/container.py tests/container/test_container_compose_argv.py
+git commit -m "feat(container): env override 합성 + compose up argv 순수 함수"
+```
+
+---
+
+## Task 5: detached 세션 + watcher/tail pane 헬퍼
+
+**배경(리뷰 blocker):** `tag_pane()` 의 기본 옵션이 `@okstra_worker_run` 이고([tmux.py](../../../scripts/okstra_ctl/tmux.py) ≈145), reap scope([scripts/okstra-trace-cleanup.sh](../../../scripts/okstra-trace-cleanup.sh) ≈147 `_tag_in_scope`)는 `@okstra_trace_run` **OR** `@okstra_worker_run` 둘 다 본다. watcher pane 에 둘 중 하나라도 붙으면 SessionEnd `--reap` 이 Claude 종료 시 watcher 를 죽여 "세션 후 생존" 요구를 위반한다. → 신규 `@okstra_container_run` 태그만 사용.
+
+**Files:**
+- Modify: `scripts/okstra_ctl/tmux.py` (`tmux_available` ≈42, `tag_pane` ≈134-151, `split_worker_pane`)
+- Modify: `scripts/okstra_ctl/ids.py`
+- Test: `tests/container/test_container_session_name.py`, `tests/container/test_container_pane_tag.py`
+
+**Interfaces:**
+- Produces:
+  - `ids.build_container_session_name(project_id, group, task_id) -> "okstra-container-<slug>"`
+  - `tmux.new_detached_session(session_name, cwd, first_cmd) -> str` (session/pane id)
+  - `tmux.split_container_pane(session_pane, cwd, command, title, scope_value, kind) -> str|None` — 새 pane 을 `-t` 로 명시 지정, `set-pane -T <title>`, `@okstra_container_run <scope_value>` 태그만 부착. `session_pane` 가 빈값/None 이면 silently skip + 로그경로 반환(degrade).
+
+- [ ] **Step 1: 세션명 + 태그 분리 실패 테스트**
+
+```python
+# tests/container/test_container_session_name.py
+def test_container_session_name_prefix():
+    from okstra_ctl import ids
+    assert ids.build_container_session_name("p", "g", "t-1") == "okstra-container-p-g-t-1"
+```
+
+```python
+# tests/container/test_container_pane_tag.py — reap 태그 미사용을 정적으로 보장
+def test_split_container_pane_uses_container_tag_only():
+    import inspect
+    from okstra_ctl import tmux
+    src = inspect.getsource(tmux.split_container_pane)
+    assert "@okstra_container_run" in src
+    assert "@okstra_trace_run" not in src
+    assert "@okstra_worker_run" not in src
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/container/test_container_session_name.py tests/container/test_container_pane_tag.py -v`
+Expected: FAIL
+
+- [ ] **Step 3: `build_container_session_name` 구현** — `ids.py`, `slugify_task_segment` 재사용.
+
+- [ ] **Step 4: `new_detached_session` + `split_container_pane` 구현** — `tmux.py`. `new_detached_session` 은 `cmd-rerun.sh` 의 detached spawn 패턴을 python 으로(`tmux new-session -d -s <name> -c <cwd> <cmd>`). `split_container_pane` 은 임의 `command` 를 받고 신규 `@okstra_container_run` 태그만 부착(`tag_pane` 의 기본 `@okstra_worker_run` 을 절대 거치지 않도록 옵션 명시 또는 별도 경로). watcher pane 제목은 `okstra-watcher-<service>` 규약 — `*-worker` 토큰 금지(리뷰 minor: title-allowlist reap 회피).
+
+- [ ] **Step 5: 통과 확인**
+
+Run: `python3 -m pytest tests/container/test_container_session_name.py tests/container/test_container_pane_tag.py -v`
+Expected: PASS
+
+- [ ] **Step 6: reap scope 회귀 grep** — `@okstra_container_run` 이 `okstra-trace-cleanup.sh` 의 reap scope 에 **포함되지 않음**을 확인.
+
+Run: `rg -n '@okstra_container_run' scripts/okstra-trace-cleanup.sh; echo "exit=$?"`
+Expected: 매치 없음 (exit=1)
+
+- [ ] **Step 7: 커밋**
+
+```bash
+git add scripts/okstra_ctl/tmux.py scripts/okstra_ctl/ids.py tests/container/test_container_session_name.py tests/container/test_container_pane_tag.py
+git commit -m "feat(container): detached 세션 + container 전용 태그 pane 헬퍼"
+```
+
+---
+
+## Task 6: watcher (에러 트리거 2단계 스캔)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/container.py` (watcher loop entrypoint)
+- Test: `tests/container/test_container_watcher_scan.py`
+
+**Interfaces:**
+- Consumes: Task 1 `container_paths().watchers_dir`.
+- Produces:
+  - `ERROR_PATTERNS` (정규식 화이트리스트), `scan_log_chunk(text, patterns) -> list[str]` (매칭 라인, 순수).
+  - `error_signature(line) -> str` (디바운스 키).
+  - `watcher_step(*, log_chunk, seen_signatures, findings_path, analyze) -> int` — 새 시그니처 수만큼 `analyze` 호출, findings append. `analyze` 는 주입(테스트 스텁 가능 = LLM 무의존).
+  - `run_watcher_loop(*, service, project_name, findings_path, scan_interval_seconds, analyze)` — 사용자 종료까지 지속.
+
+- [ ] **Step 1: 실패 테스트**
+
+```python
+# tests/container/test_container_watcher_scan.py
+from okstra_ctl import container
+
+
+def test_clean_logs_trigger_no_analysis(tmp_path):
+    calls = []
+    n = container.watcher_step(
+        log_chunk="all good\nrequest 200 ok\n", seen_signatures=set(),
+        findings_path=tmp_path / "f.md", analyze=lambda w: calls.append(w))
+    assert n == 0 and calls == []
+
+
+def test_error_triggers_single_analysis(tmp_path):
+    calls = []
+    n = container.watcher_step(
+        log_chunk="ERROR boom at db\n", seen_signatures=set(),
+        findings_path=tmp_path / "f.md", analyze=lambda w: calls.append(w))
+    assert n == 1 and len(calls) == 1
+    assert (tmp_path / "f.md").exists()
+
+
+def test_same_signature_debounced(tmp_path):
+    seen = set()
+    container.watcher_step(log_chunk="ERROR boom\n", seen_signatures=seen,
+                           findings_path=tmp_path / "f.md", analyze=lambda w: None)
+    calls = []
+    container.watcher_step(log_chunk="ERROR boom\n", seen_signatures=seen,
+                           findings_path=tmp_path / "f.md", analyze=lambda w: calls.append(w))
+    assert calls == []  # 2번째 동일 시그니처 skip
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/container/test_container_watcher_scan.py -v`
+Expected: FAIL
+
+- [ ] **Step 3: 구현** — `scan_log_chunk`(정규식 매칭), `error_signature`(라인 정규화 후 해시/축약), `watcher_step`(새 시그니처만 `analyze` 호출 + findings append), `run_watcher_loop`(`docker compose logs --since <last>` 증분 fetch + `time.sleep(scan_interval_seconds)`). `analyze` 기본 구현은 codex/antigravity-worker 와 동일 pane 메커니즘으로 AI 에이전트 기동하되 **findings append 만 허용(read-only 보고 계약)** — 코드/설정 Edit/Write 금지를 프롬프트로 강제(스펙 §9 enforcement).
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/container/test_container_watcher_scan.py -v`
+Expected: PASS (3 tests)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/container.py tests/container/test_container_watcher_scan.py
+git commit -m "feat(container): 에러 트리거 2단계 watcher 스캔"
+```
+
+---
+
+## Task 7: provision_container_group() 수렴 entrypoint + sub-command 디스패치
+
+**Files:**
+- Modify: `scripts/okstra_ctl/container.py` (`main`, `provision_container_group`, status/logs/stop-watcher/down)
+- Modify: `scripts/okstra_ctl/__init__.py` (필요 헬퍼만 export)
+- Test: `tests/container/test_container_up_gate.py`
+
+**Interfaces:**
+- Consumes: Task 2 `resolve_and_integrate_whole_task(teardown=False)`, Task 3 registry, Task 4 argv, Task 5 pane 헬퍼 + `tmux_available()`, Task 6 watcher.
+- Produces:
+  - `provision_container_group(*, project_root, task_key, healthcheck_timeout_seconds=120, healthcheck_interval_seconds=3, scan_interval_seconds=...) -> dict`
+  - `main(argv) -> int` — argparse add_subparsers(`up`/`status`/`logs`/`stop-watcher`/`down`), `print(json.dumps(result))`, `__main__` 진입. (참고: `recap.py` ≈94-135 패턴)
+
+- [ ] **Step 1: 게이트 실패 테스트(생성 금지·중단)**
+
+```python
+# tests/container/test_container_up_gate.py
+import pytest
+from okstra_ctl import container
+
+
+def test_up_aborts_when_no_compose(container_task_fixture):
+    # worktree 에 docker-compose.yml 없음
+    with pytest.raises(container.PrepareError) as e:
+        container.provision_container_group(**container_task_fixture.up_kwargs)
+    assert "docker-compose.yml" in str(e.value)
+
+
+def test_up_aborts_with_dockerfile_only(container_task_fixture):
+    container_task_fixture.write_worktree_file("Dockerfile", "FROM scratch\n")
+    with pytest.raises(container.PrepareError) as e:
+        container.provision_container_group(**container_task_fixture.up_kwargs)
+    assert "docker-compose.yml" in str(e.value)  # compose 없음으로 중단
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/container/test_container_up_gate.py -v`
+Expected: FAIL
+
+- [ ] **Step 3: `provision_container_group` 구현(오케스트레이션, ≤50줄, 단계별 헬퍼 분리)** — 순서: ① `resolve_and_integrate_whole_task(teardown=False)` 로 소스트리/미통합 stage 머지(충돌 시 부분통합 상태 + 충돌파일 + 재시도 안전(already_merged 멱등) 안내 메시지로 `PrepareError`) → ② worktree 루트 `docker-compose.yml` 존재 검증(없으면 누락 파일명 명시·중단) → ③ bind mount/volume 스캔, worktree 밖 경로는 **경고 후 진행**(스펙 §6) → ④ env.override 합성(입력 `.env` 는 worktree 기준, Task 4) → ⑤ `build_compose_up_argv` 로 compose up → ⑥ healthcheck 폴링(`docker compose ps --format json`, `healthcheck_timeout_seconds`/`interval`, healthcheck 미정의 서비스는 `running` 종료조건, timeout 시 미기동 서비스 명시 중단) → ⑦ `tmux_available()` 면 detached 세션 + 서비스별 tail/watcher pane 스폰(부재 시 skip + "감시 비활성" 명시) → ⑧ registry 기록 + deploy-state.json.
+
+- [ ] **Step 4: `main` 디스패치 + status/down 구현** — argparse 5 sub-command. `status`/`down`/`stop-watcher` 는 **docker 라벨 쿼리가 컨테이너 SSOT**. `down`/`down all` 은 라벨 쿼리와 **별개로** `@okstra_container_run` 태그/세션을 tmux 실측 스캔해 orphan watcher 회수(리뷰 major: registry drift). `plan_run_root`/`done_rows` 역추적 resolver 는 task-key 로 implementation-planning run-root 를 찾되 다중 run 시 최신 done 보유 run 선택, 모호하면 중단(스펙 §11).
+
+- [ ] **Step 5: 통과 확인**
+
+Run: `python3 -m pytest tests/container/ -v`
+Expected: PASS (전체)
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/container.py scripts/okstra_ctl/__init__.py tests/container/test_container_up_gate.py
+git commit -m "feat(container): provision_container_group 수렴 entrypoint + sub-command 디스패치"
+```
+
+---
+
+## Task 8: Node thin shim + CLI 레지스트리
+
+**배경(리뷰 major):** shim 은 `src/commands/inspect/container.mjs` (introspection 계열 디렉터리), `cli-registry.mjs` 의 module 도 `./commands/inspect/container.mjs`. `recap.mjs` 가 실제로 `src/commands/inspect/recap.mjs` 에 있다.
+
+**Files:**
+- Create: `src/commands/inspect/container.mjs` (참고: `src/commands/inspect/recap.mjs` thin shim)
+- Modify: `src/cli-registry.mjs` (참고: recap 등록 행)
+- Modify: `tests-js/cli-registry.test.mjs` (카운트)
+- Test: `node --test tests-js/cli-registry.test.mjs`
+
+**Interfaces:**
+- Produces: `run(args) -> Promise<number>` — `runPythonModule({module:'okstra_ctl.container', args, ...})` 위임.
+
+- [ ] **Step 1: 카운트 갱신 + 등록** — `cli-registry.mjs` `COMMAND_REGISTRY` 에 `{name:'container', module:'./commands/inspect/container.mjs', export:'run', category:'introspection', summary:[...]}`.
+
+- [ ] **Step 2: shim 작성** — `src/commands/inspect/container.mjs`, `recap.mjs` 패턴 그대로(`runPythonModule` 한 통로). import 경로 `../../lib/python-helper.mjs`.
+
+- [ ] **Step 3: 테스트 카운트 정정(리뷰 blocker/major)** — `tests-js/cli-registry.test.mjs` 의 하드코딩 카운트를 **실제 라인 전수 갱신**: 총 `33→34` (테스트명 문자열, `registryNames.length`, `COMMANDS.size`, `seen.size` 등 33 이 나오는 **모든** 라인), introspection `21→22` (실제 라인 좌표 확인 후). 구현 시 `rg -n '\b33\b|\b21\b' tests-js/cli-registry.test.mjs` 로 전수 확인.
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `node --test tests-js/cli-registry.test.mjs`
+Expected: PASS (모든 카운트 단언 통과)
+
+- [ ] **Step 5: smoke**
+
+Run: `npm run build && node bin/okstra container --help`
+Expected: container sub-command usage 출력, exit 0
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add src/commands/inspect/container.mjs src/cli-registry.mjs tests-js/cli-registry.test.mjs
+git commit -m "feat(container): bin okstra container thin shim + CLI 등록"
+```
+
+---
+
+## Task 9: SKILL.md + 스킬/권한 등록
+
+**Files:**
+- Create: `skills/okstra-container/SKILL.md` (참고: `skills/okstra-inspect/SKILL.md` 디스패치 골격)
+- Modify: `src/lib/skill-catalog.mjs` (`USER_SKILL_NAMES`)
+- Modify: `.claude-plugin/plugin.json` (skills 배열, 동일 인덱스/순서)
+- Modify: `templates/reports/settings.template.json` (docker 권한)
+- Test: `node --test tests-js/skill-catalog.test.mjs`
+
+- [ ] **Step 1: SKILL.md 작성** — frontmatter `description` 에 트리거 한 줄(자연어 + 명시 명령: "okstra container", "컨테이너 띄워", "유저 테스트 환경"). 본문 상단 표(`up`/`status`/`logs`/`stop-watcher`/`down` = 메뉴 SSOT). Step 0 부트스트랩: `okstra ensure-installed --runtime claude-code` + `okstra check-project --json` 두 줄을 각각 단독 Bash 호출(리터럴 `okstra` 시작, `$()`/`VAR=`/`&&`/`npx` fallback 금지). Step 1 dispatch: 트리거 표 분류, 모호 시 numbered 메뉴 + 마지막 "직접 입력"(3-옵션 picker, MEMORY: 추천 + 직접입력). 실행/Read 경로는 host 기준(`~/.okstra/...`), 코드 출처 포인터만 레포 경로.
+
+- [ ] **Step 2: 스킬 카탈로그 등록** — `USER_SKILL_NAMES` 에 `'okstra-container'` 추가(SSOT).
+
+- [ ] **Step 3: plugin.json 등록** — skills 배열에 `./skills/okstra-container` 를 `USER_SKILL_NAMES` 와 **동일 인덱스/순서**로 추가(`skill-catalog.test.mjs` deepEqual 순서 가드).
+
+- [ ] **Step 4: docker 권한 시드** — `templates/reports/settings.template.json` `permissions.allow` 의 `Bash(claude:*)` 직후에 `Bash(docker)`, `Bash(docker:*)` 추가(직전 항목 트레일링 콤마). **`Bash(docker compose:*)` 는 `Bash(docker:*)` prefix-match 로 커버되는지 확인 후 중복이면 제외**(리뷰 minor, allowlist 중복 제거).
+
+- [ ] **Step 5: 통과 확인**
+
+Run: `node --test tests-js/skill-catalog.test.mjs tests-js/install-runtime.test.mjs`
+Expected: PASS (deepEqual 순서 가드 통과)
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add skills/okstra-container/SKILL.md src/lib/skill-catalog.mjs .claude-plugin/plugin.json templates/reports/settings.template.json
+git commit -m "feat(container): okstra-container SKILL + 스킬/docker 권한 등록"
+```
+
+---
+
+## Task 10: doctor docker WARN + e2e 시나리오
+
+**배경(리뷰 blocker):** `doctor.mjs` 의 `allOk = results.every(r => r.ok)` 때문에 `results` 에 넣는 항목은 무엇이든 `allOk` 를 뒤집어 `[FAIL]` 로 렌더된다. docker 점검을 `results` 에 넣으면 docker 미설치 사용자가 `exit 1` 회귀 → `runtimeResolution` 처럼 **별도 변수 + `[WARN]`** 으로 출력하고 `allOk` 에서 제외.
+
+**Files:**
+- Modify: `src/commands/lifecycle/doctor.mjs` (참고: `runtimeResolution` WARN 출력 ≈200-203, `allOk` ≈245, JSON 모드 ≈246-261)
+- Create: `tests-e2e/scenario-15-okstra-container-up-down.sh` (참고: `scenario-01`, `scenario-14`)
+- Modify: `tests-e2e/README.md` (Index of scenarios)
+- Test: `node --test tests-js/doctor-runtime.test.mjs`
+
+- [ ] **Step 1: doctor docker WARN 추가** — `results` 배열에 넣지 말 것. `runProcess('docker', ['compose', 'version'])` 결과를 별도 변수(`dockerWarning`)로 두고 `[WARN]` 한 줄만 출력, `allOk` 비반영. JSON 모드엔 별도 키(`dockerWarning`)로 노출. `REQUIRED_SKILLS` 불변(okstra-container 강제 점검 금지).
+
+- [ ] **Step 2: doctor 회귀 테스트 통과**
+
+Run: `node --test tests-js/doctor-runtime.test.mjs`
+Expected: PASS (REQUIRED_SKILLS 불변, docker 미설치 시 exit 0 유지)
+
+- [ ] **Step 3: e2e 시나리오 작성** — `tests-e2e/scenario-15-okstra-container-up-down.sh`. `set -euo pipefail`, `mktemp -d` 로 `OKSTRA_HOME` + `PROJECT_ROOT`(`docker-compose.yml`/`.env` 시드), sandbox `bin/` 에 docker stub(argv 기록) + PATH prepend. `up <task-id>` 후 stub argv 에 okstra 라벨·두 `--env-file`·`-p <project-name>` grep, `down` 후 정리 확인, `trap cleanup EXIT`, 마지막 `echo PASS`. `OKSTRA_CTL_SKIP_*` 설정 금지(e2e 규약), `--project-root` 직접 전달.
+
+- [ ] **Step 4: e2e 수동 PASS**
+
+Run: `bash tests-e2e/scenario-15-okstra-container-up-down.sh`
+Expected: 마지막 `PASS` 출력, exit 0
+
+- [ ] **Step 5: README 인덱스 갱신** — `tests-e2e/README.md` 표에 scenario-15 행 추가.
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add src/commands/lifecycle/doctor.mjs tests-e2e/scenario-15-okstra-container-up-down.sh tests-e2e/README.md
+git commit -m "feat(container): doctor docker WARN degrade + e2e 시나리오"
+```
+
+---
+
+## Task 11: 빌드 동기화 + 전체 CI 게이트
+
+**Files:** (없음 — 검증 전용)
+
+- [ ] **Step 1: runtime 미러 재생성**
+
+Run: `npm run build`
+Expected: `runtime/python/okstra_ctl/container.py` 등 신규 파일이 미러에 반영(exit 0)
+
+- [ ] **Step 2: 전체 CI**
+
+Run: `npm run check`
+Expected: PASS (test:js → test:py 순서로 모두 exit 0)
+
+- [ ] **Step 3: 설치 경로 smoke**
+
+Run: `node bin/okstra doctor`
+Expected: exit 0 (docker 미설치 시 `[WARN]` 한 줄, FAIL 아님)
+
+- [ ] **Step 4: phase 계약 검증 회귀**
+
+Run: `bash validators/validate-workflow.sh`
+Expected: PASS (PHASE_SEQUENCE 미변경 확인)
+
+- [ ] **Step 5: 최종 커밋(빌드 산출물 제외 — runtime/ 은 gitignore)**
+
+```bash
+git status   # runtime/ 변경이 staged 되지 않음을 확인(.gitignore)
+git log --oneline -11   # T1~T10 + 검증 커밋 확인
+```
+
+---
+
+## Self-Review (작성자 체크리스트 결과)
+
+- **Spec coverage:** §1~§9 전부 task 매핑됨(B/비선형=T7·T9, sub-command=T7·T8·T9, up 플로우=T7, 지속성/태그=T5, env/artifact-home=T4·T7, 네이밍/SSOT=T1·T7, 단일참조점/등록=T2·T7·T8·T9, YAGNI=Global Constraints). §10 확정사항 전부 반영(watcher=T6, healthcheck=T7, Dockerfile중단=T7, tmux degrade=T7, bind mount경고=T7, stage보존=T2, doctor WARN=T10). §11 잔여항목(plan-run-root resolver=T7 Step4, orphan reconcile=T7 Step4, truncation 형식=T1)도 task 내 명시.
+- **Placeholder scan:** 모든 코드 step 에 실제 테스트/구현 코드 블록 포함. 기존 파일 내부는 anchor(file:line)로 참조하고 신규 코드는 전문 기재.
+- **Type consistency:** `container_paths`/`compose_project_name`(T1) → T3·T4·T7 소비, `resolve_and_integrate_whole_task`(T2) → T7, `build_compose_up_argv`/`merge_env`(T4) → T7, `split_container_pane`/`new_detached_session`(T5) → T7, `watcher_step`/`run_watcher_loop`(T6) → T7. 시그니처 일치 확인.