okstra 0.97.0 → 0.98.0

package/README.kr.md

@@ -43,7 +43,7 @@ okstra/                          npm 패키지 = repo 루트
 ├── tools/build.mjs              runtime/ 동기화 스크립트 (prepack 에서 호출)
 ├── runtime/                     gitignored 설치 payload; ~/.okstra 로 복사
 ├── scripts/                     python + bash 런타임 소스
-├── skills/                      public 스킬 마크다운 소스 (사용자 노출 6종)
+├── skills/                      public 스킬 마크다운 소스 (사용자 노출 7종)
 ├── agents/                      worker agent 마크다운 소스
 ├── prompts/, schemas/, templates/, validators/
 ├── docs/kr/                     한국어 상세 매뉴얼 (architecture.md, cli.md)
@@ -78,7 +78,7 @@ okstra/                          npm 패키지 = repo 루트
 ~/.claude/skills/                Claude Code 가 자동 인식 (`~/.claude` 가 있을 때)
 ~/.codex/skills/                 Codex 호환 host 가 인식 (`~/.codex` 가 있을 때)
 ~/.omp/agent/skills/             둘 다 없을 때 OMP-native fallback skill target
-└── okstra-*/SKILL.md            사용자 노출 스킬 6종만 (setup/brief/run/memory/inspect/schedule)
+└── okstra-*/SKILL.md            사용자 노출 스킬 7종만 (setup/brief/run/memory/inspect/schedule/container)
 
 ~/.claude/agents/                Claude Code 가 자동 인식 (`~/.claude` 가 있을 때)
 └── {claude,codex,antigravity,report-writer}-worker.md   worker subagent 정의
@@ -161,8 +161,9 @@ Claude Code 세션 안에서 사용하는 슬래시 커맨드:
 | `/okstra-brief` | ticket, 요구사항 문서, 링크, 대화 내용을 `okstra-run`용 task brief로 변환 |
 | `/okstra-run` | 새 task 시작 (또는 기존 task 의 다음 phase 이어가기) |
 | `/okstra-memory` | `~/.okstra/memory-book` 전역 대화 메모리 저장·검색·보관 |
-| `/okstra-inspect` | 통합 read-side 스킬. sub-command: `status` (phase / 상태, workStatus 설정), `history` (과거 task / re-run / resume), `report` (final-report 조회·읽기), `time` (소요 시간 breakdown), `logs` (wrapper log sidecar 조회·정리 제안), `cost` (task bundle 컨텍스트/읽기 비용), `errors` (run 에러 로그를 리포트로 집계), `recap` (run 간 전/후 요약 + task 의 `.okstra` 산출물 위 자유 Q&A) |
+| `/okstra-inspect` | 통합 read-side 스킬. sub-command: `status` (phase / 상태, workStatus 설정), `history` (과거 task / re-run / resume), `report` (final-report 조회·읽기), `time` (소요 시간 breakdown), `logs` (wrapper log sidecar 조회·정리 제안), `cost` (task bundle 컨텍스트/읽기 비용), `errors` (run 에러 로그를 리포트로 집계), `error-zip` (cross-project 에러 로그를 익명화 zip 으로 수집·클러스터 요약), `recap` (run 간 전/후 요약 + task 의 `.okstra` 산출물 위 자유 Q&A) |
 | `/okstra-schedule` | task-group 전체에 대한 작업 계획표 생성 |
+| `/okstra-container` | 검증 완료된 task 의 코드를 로컬 docker compose 그룹으로 배포하고 컨테이너별 로그를 감시 (sub-command: `up` / `status` / `logs` / `stop-watcher` / `down`) |
 | `/okstra-setup` | 프로젝트별 부트스트랩 (§3.2) |
 
 lead 운영 계약과 지원 계약 — context-loader, team-contract, convergence, report-writer, 그리고 coding-preflight 팩 — 은 더 이상 agent 스킬로 설치되지 않습니다. okstra 런타임 리소스로 `~/.okstra/prompts/` (`prompts/lead/*.md`, `prompts/coding-preflight/*`) 아래에 배치되고, generated launch prompt 가 lead 에게 절대 경로를 전달합니다. 재설치 시 agent skill home 에 남은 과거 복사본은 prune 되므로 슬래시 커맨드로 노출되지 않습니다.

package/README.md

@@ -43,7 +43,7 @@ okstra/                          npm package = repo root
 ├── tools/build.mjs              runtime/ sync script (invoked by prepack)
 ├── runtime/                     gitignored install payload copied to ~/.okstra
 ├── scripts/                     python + bash runtime sources
-├── skills/                      public skill markdown sources (6 user-facing skills)
+├── skills/                      public skill markdown sources (7 user-facing skills)
 ├── agents/                      worker agent markdown sources
 ├── prompts/, schemas/, templates/, validators/
 ├── tests/, tests-e2e/
@@ -76,7 +76,7 @@ okstra/                          npm package = repo root
 ~/.claude/skills/                discovered automatically by Claude Code (if ~/.claude exists)
 ~/.codex/skills/                 discovered by Codex-compatible hosts (if ~/.codex exists)
 ~/.omp/agent/skills/             fallback OMP-native skill target when neither exists
-└── okstra-*/SKILL.md            user-facing skills only (setup/brief/run/memory/inspect/schedule)
+└── okstra-*/SKILL.md            user-facing skills only (setup/brief/run/memory/inspect/schedule/container)
 
 ~/.claude/agents/                discovered automatically by Claude Code (if ~/.claude exists)
 └── {claude,codex,antigravity,report-writer}-worker.md   subagent definitions
@@ -159,8 +159,9 @@ User-facing slash commands inside a Claude Code session:
 | `/okstra-brief` | Turn a ticket, requirements doc, link, or conversation into an `okstra-run` task brief |
 | `/okstra-run` | Start a new task (or resume the next phase of an existing one) |
 | `/okstra-memory` | Store/search/archive global conversation memory in `~/.okstra/memory-book` |
-| `/okstra-inspect` | Unified read-side. Sub-commands: `status` (phase / state, workStatus update), `history` (past runs, re-run, resume), `report` (find/read final-report), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory + cleanup), `cost` (task bundle context/read cost), `errors` (aggregate run error logs into a report), `recap` (run-to-run before/after summary + free-form Q&A over a task's `.okstra` artifacts) |
+| `/okstra-inspect` | Unified read-side. Sub-commands: `status` (phase / state, workStatus update), `history` (past runs, re-run, resume), `report` (find/read final-report), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory + cleanup), `cost` (task bundle context/read cost), `errors` (aggregate run error logs into a report), `error-zip` (collect cross-project error logs into an anonymized zip and summarize clusters), `recap` (run-to-run before/after summary + free-form Q&A over a task's `.okstra` artifacts) |
 | `/okstra-schedule` | Generate a work schedule for an entire task-group |
+| `/okstra-container` | Deploy a verified task's code as a local docker compose group and watch each container's logs (sub-commands: `up` / `status` / `logs` / `stop-watcher` / `down`) |
 | `/okstra-setup` | Per-project bootstrap (§3.2) |
 
 The lead operating contract and its support contracts — context-loader, team-contract, convergence, report-writer, and the coding-preflight pack — are **not** installed as agent skills. They ship as okstra runtime resources under `~/.okstra/prompts/` (`prompts/lead/*.md` and `prompts/coding-preflight/*`) and the generated launch prompt hands the lead their absolute paths. Reinstalling prunes any earlier copies of these from the agent skill homes, so they never appear as slash commands.

package/docs/kr/architecture.md

@@ -146,9 +146,9 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md) — main okstra lead contract. 런타임 리소스(`~/.okstra/prompts/lead/`)이며 agent skill 이 아닙니다.
 - [`skills/okstra-setup/SKILL.md`](../../skills/okstra-setup/SKILL.md) — **첫 실행 부트스트랩**. `okstra install` + `project.json` 생성.
 - [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) — **현재 claude 세션 안에서 okstra task 를 시작**하는 in-session 진입점. `prepare_task_bundle` 직접 호출.
-- 사용자 호출 가능 스킬은 `skills/okstra-{setup,brief,run,memory,inspect,schedule}/SKILL.md` 6종뿐이며, 이것만 agent skill home 으로 복사됩니다 — brief 작성, phase 진행, 전역 Memory Book 저장/검색, status/history/report/time/logs/cost/errors/recap read-side, schedule 보조. `okstra-inspect` 의 read-side facet 은 `skills/okstra-inspect/SKILL.md` 의 sub-command 표가 정본인 8종입니다. `okstra-inspect logs` 는 codex/antigravity wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내(read-only), `okstra-inspect cost` 는 `okstra context-cost` 결과 요약, `okstra-inspect errors` 는 task 의 okstra-run 에러 로그를 타임스탬프 markdown error-report 로 모아 렌더하고 요약을 출력, `okstra-inspect recap` 은 task 의 run 간 phase 전·후 요약에 더해 `.okstra` 산출물에 대한 자유 Q&A 까지 답합니다.
+- 사용자 호출 가능 스킬은 `skills/okstra-{setup,brief,run,memory,inspect,schedule,container}/SKILL.md` 7종뿐이며, 이것만 agent skill home 으로 복사됩니다 — brief 작성, phase 진행, 전역 Memory Book 저장/검색, status/history/report/time/logs/cost/errors/recap read-side, schedule 보조, 그리고 `okstra-container` 는 검증 완료된 task 코드를 docker compose 그룹으로 배포하고 컨테이너별 watcher 로 감시하는 비선형(PHASE_SEQUENCE 외부) 컨테이너 배포/감시 스킬. `okstra-inspect` 의 read-side facet 은 `skills/okstra-inspect/SKILL.md` 의 sub-command 표가 정본인 8종입니다. `okstra-inspect logs` 는 codex/antigravity wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내(read-only), `okstra-inspect cost` 는 `okstra context-cost` 결과 요약, `okstra-inspect errors` 는 task 의 okstra-run 에러 로그를 타임스탬프 markdown error-report 로 모아 렌더하고 요약을 출력, `okstra-inspect recap` 은 task 의 run 간 phase 전·후 요약에 더해 `.okstra` 산출물에 대한 자유 Q&A 까지 답합니다.
 - 내부 운영 계약 — `context-loader` / `team-contract` / `convergence` / `report-writer` 와 lead 계약 — 은 `prompts/lead/*.md` 로, 구현/검증 워커의 언어별 coding preflight 는 `prompts/coding-preflight/*` (overview 라우터 + clean-code + languages/frameworks/architectures 3단계 선택) 로 이동했습니다. 모두 `~/.okstra/prompts/` 에 설치되는 런타임 리소스이며 skill discovery 대상이 아닙니다. generated launch prompt 가 lead 에게 절대 경로를 제공하고, 재설치 시 과거 `okstra-context-loader` / `okstra-team-contract` / `okstra-convergence` / `okstra-report-writer` / `okstra-coding-preflight` / `okstra` skill 디렉터리는 exact-name prune 됩니다.
-- 플러그인 매니페스트: [`../../.claude-plugin/plugin.json`](../../.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 일반 셋업에는 `npx okstra@latest install` 을 사용한다. 플러그인 매니페스트는 사용자 진입점 6개(`okstra-setup`, `okstra-brief`, `okstra-run`, `okstra-memory`, `okstra-inspect`, `okstra-schedule`)만 노출한다.
+- 플러그인 매니페스트: [`../../.claude-plugin/plugin.json`](../../.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 일반 셋업에는 `npx okstra@latest install` 을 사용한다. 플러그인 매니페스트는 사용자 진입점 7개(`okstra-setup`, `okstra-brief`, `okstra-run`, `okstra-memory`, `okstra-inspect`, `okstra-schedule`, `okstra-container`)만 노출한다.
 - 설치 위치: `~/.claude/skills/<name>/SKILL.md`, `~/.codex/skills/<name>/SKILL.md`, 또는 fallback `~/.omp/agent/skills/<name>/SKILL.md`.
 - 릴리스 절차: [`../../RELEASING.md`](../../RELEASING.md) — npm publish 흐름과 release-please / manual fallback.
 

package/docs/kr/cli.md

@@ -1,6 +1,8 @@
 # okstra — CLI 인자 / 옵션 매뉴얼 (한국어)
 
 > 이 문서는 [README.kr.md](../../README.kr.md) 의 보충 문서입니다. 내부 아키텍처와 storage / workflow 계약은 [architecture.md](architecture.md) 를 참고하세요.
+>
+> 이 문서는 `okstra.sh` 의 phase 실행 플래그를 다룹니다. 별개 진입점인 `okstra container` 의 sub-command 레퍼런스는 [container.md](container.md) 를 참고하세요.
 
 ---
 

package/docs/kr/container.md

@@ -0,0 +1,122 @@
+# okstra container — CLI 레퍼런스 (한국어)
+
+> `okstra container` 는 검증된 task 의 코드를 로컬 docker compose 그룹으로 띄우고 컨테이너별로 감시하는 비선형 도구입니다. `okstra.sh` 의 phase 플래그와는 별개 진입점이라 [cli.md](cli.md) 가 아닌 이 문서에서 다룹니다. 내부 설계는 [스펙](../superpowers/specs/2026-06-21-okstra-container-local-user-test-design.md), 모듈 위치는 [project-structure-overview](../project-structure-overview.md) §4.3 을 참고하세요.
+
+---
+
+## 개요
+
+- **무엇인가:** 특정 task 의 통합된 코드를 그 task 전용 docker compose 컨테이너 그룹으로 배포(`up`)하고, 컨테이너별 watcher 로 로그를 상시 감시하며, `status`/`logs`/`stop-watcher`/`down` 으로 수명주기를 관리한다.
+- **오케스트레이션 전용(생성 안 함):** 대상 프로젝트가 이미 가진 `docker-compose.yml` 을 **재사용**한다. 설정 파일을 생성하지 않으며, `docker-compose.yml` 이 없으면 무엇이 없는지 알리고 중단한다(`Dockerfile` 단독도 동일).
+- **비선형:** `PHASE_SEQUENCE` 의 phase 가 아니다. 임의의 task-key 를 검증 통과 여부와 무관하게 띄울 수 있다.
+- **단일 진입점:** 스킬 `/okstra-container`, `bin okstra container`, python `okstra_ctl.container` 가 모두 [`scripts/okstra_ctl/container.py`](../../scripts/okstra_ctl/container.py) 의 `provision_container_group` 로 수렴한다.
+- **컨테이너 존재의 기준값(SSOT):** docker 라벨. `registry.json` 은 tmux 세션/pane/findings 만 담는 보조 인덱스다.
+
+## 사전 조건
+
+- `docker` / `docker compose` 가 설치·동작해야 한다. 미설치 환경에서는 `up` 이 실패하지만, `okstra doctor` 는 `[WARN]` 만 내고 종료 코드 0 을 유지한다(컨테이너 기능은 필수 아님).
+- 대상 task-key 의 코드가 task-key worktree HEAD 로 통합돼 있어야 한다. 미통합 stage 가 있으면 `up` 이 머지(stage 트리는 보존)한 뒤 진행하며, 충돌 시 충돌 파일을 알리고 중단한다.
+- worktree 루트에 `docker-compose.yml` 이 있어야 한다.
+
+## 명령 형식
+
+```
+okstra container <up|status|logs|stop-watcher|down> --project-root <PATH> --task-key <KEY> [옵션]
+```
+
+| sub-command | 동작 | 추가 옵션 |
+|---|---|---|
+| `up` | stage 통합 확인 → `docker-compose.yml` 검증 → env override 합성 → `docker compose -p <project> up -d` → 헬스체크 폴링 → 컨테이너별 tail/watcher pane 기동 | — |
+| `status` | docker 라벨 쿼리로 살아있는 컨테이너 그룹 현황 | — |
+| `logs` | 컨테이너 로그 조회 | `--service <NAME>` (생략 시 그룹 전체) |
+| `stop-watcher` | 해당 task 의 watcher pane 종료(컨테이너는 유지) | — |
+| `down` | 컨테이너 그룹 teardown + 딸린 watcher 종료 | `--all` |
+
+## 인자
+
+### `--project-root` (필수)
+대상 프로젝트 루트의 절대 경로. 모든 sub-command 에 필수.
+
+### `--task-key` (필수에 준함)
+배포 대상 task 식별자 `<project-id>:<task-group>:<task-id>`. 기본값은 빈 문자열이나, 실제 동작에는 유효한 task-key 가 필요하다.
+
+### `--service` (`logs` 전용)
+특정 compose 서비스의 로그만 조회. 생략하면 그룹 전체.
+
+### `--all` (`down` 전용)
+현재 project-root 의 `.okstra/` 범위 안에 있는 **모든** task 컨테이너 그룹과 watcher 를 정리한다. 경계는 `<project-root>/.okstra/` prefix 로 한정되어, 동시 세션의 **다른 프로젝트** pane 은 절대 건드리지 않는다. `--all` 없이 단일 `down` 은 해당 task 의 pane 만 정확히 회수한다.
+
+## `up` 의 동작 단계
+
+1. **소스 트리 해소** — task-key worktree HEAD. 미통합 stage 는 머지(`teardown=False`, stage worktree 보존). 충돌 시 충돌 파일 명시 후 중단(재시도는 already-merged 멱등이라 안전).
+2. **설정 파일 검증** — worktree 루트 `docker-compose.yml`. 없으면 누락 파일명 명시 후 중단(생성 안 함).
+3. **bind mount 스캔** — `docker compose config` 정규화 결과에서 worktree 밖(`../`·절대경로)을 가리키는 host path 가 있으면 **경고 후 진행**(중단하지 않음 — 컨테이너가 호스트에 파일을 쓸 수 있음을 알림).
+4. **env override 합성** — worktree 의 `.env`(okstra 소유 트리) 위에 task override 를 얹어 `env.override` 로 쓴 뒤 `--env-file <worktree .env> --env-file <env.override>` 순으로 전달(뒤가 우선).
+5. **배포** — `docker compose -p <project-name> ... up -d`. 서비스 목록은 `docker compose config --services`(정본)로 얻는다.
+6. **헬스체크 폴링** — `docker compose ps` 로 각 서비스 기동 확인. healthcheck 가 정의된 서비스는 healthy, 없는 서비스는 `running` 도달을 성공으로 본다.
+7. **감시 기동** — `tmux` 가용 시 detached 세션 `okstra-container-<slug>` 에 컨테이너별 tail pane + watcher 에이전트를 띄운다. 미가용 시 컨테이너만 띄우고 "감시 비활성(tmux 없음)" 을 결과에 명시한다.
+
+### 고정 기본값(현재 CLI 플래그 미노출)
+
+| 값 | 기본 | 의미 |
+|---|---|---|
+| healthcheck timeout | 120초 | 초과 시 미기동 서비스를 알리고 중단 |
+| healthcheck interval | 3초 | `docker compose ps` 폴링 간격 |
+| watcher scan interval | 5초 | watcher 로그 증분 스캔 주기 |
+
+> 이 값들은 `provision_container_group` 의 named 인자로 존재하지만 CLI 플래그로는 노출되지 않아 현재 고정값으로 동작한다.
+
+## watcher (에러 트리거 2단계)
+
+컨테이너당 watcher 1개가 detached 세션에서 동작한다.
+
+1. **경량 스캔** — `docker compose logs --since` 로 증분 로그를 가져와 정규식(`ERROR`/`FATAL`/`Exception`/`Traceback`/비정상 exit code 등)만 매칭. 매칭 0건이면 LLM 호출 없이 다음 주기 → 정상 구간 토큰 비용 0.
+2. **심층 분석** — 패턴 감지 시에만 watcher AI 가 해당 로그 윈도우를 분석해 `findings.md` 에 기록(append). 동일 에러 시그니처는 디바운스(HTTP status·exit code 등 의미 있는 숫자는 보존, 타임스탬프·pid 등 노이즈만 정규화). watcher 는 **탐지·보고만** 하며 코드/설정을 수정하지 않는다.
+
+watcher/tail pane 은 전용 `@okstra_container_run` 태그만 부착되어 Claude 세션 종료(SessionEnd `--reap`)에도 살아남는다. `stop-watcher` 또는 `down` 으로 종료한다.
+
+## 라벨과 산출물
+
+배포된 컨테이너에는 세 라벨이 부착되며, `status`/`down` 의 라벨 쿼리가 이를 기준으로 그룹을 찾는다.
+
+| 라벨 | 값 |
+|---|---|
+| `okstra.task-key` | `<project-id>:<task-group>:<task-id>` |
+| `okstra.project-name` | compose project name `okstra-<proj>-<group>-<task>` |
+| `okstra.run-trace` | container 세션명(`okstra-container-<slug>`) |
+
+okstra 산출물은 전부 `<project-root>/.okstra/tasks/<group>/<task-id>/container/` 아래에 둔다(원본 프로젝트 파일 불변):
+
+```
+container/
+├── env.override            # task 별 주입 변수(프로젝트 .env 위 레이어)
+├── registry.json           # tmux 세션/pane/findings (flock-guarded 보조 인덱스)
+├── deploy-state.json       # compose project name, 기동 컨테이너, 라벨
+└── watchers/<service>-findings.md   # watcher 별 에러 분석 로그
+```
+
+## 종료/출력
+
+각 sub-command 은 결과를 JSON 으로 stdout 에 출력하고 종료 코드 0 을 반환한다. 검증 실패(설정 파일 부재, 머지 충돌, 헬스체크 timeout 등)는 `PrepareError` 로 무엇이 잘못됐는지 명시하며 비정상 종료한다.
+
+## 사용 예
+
+```bash
+# 배포 + 감시 기동
+okstra container up --project-root /path/to/proj --task-key proj:auth:login-fix
+
+# 현황
+okstra container status --project-root /path/to/proj --task-key proj:auth:login-fix
+
+# 특정 서비스 로그
+okstra container logs --project-root /path/to/proj --task-key proj:auth:login-fix --service api
+
+# watcher 만 종료(컨테이너 유지)
+okstra container stop-watcher --project-root /path/to/proj --task-key proj:auth:login-fix
+
+# 그룹 teardown
+okstra container down --project-root /path/to/proj --task-key proj:auth:login-fix
+
+# 이 프로젝트의 모든 컨테이너 그룹 정리
+okstra container down --project-root /path/to/proj --all
+```

package/docs/project-structure-overview.md

@@ -124,7 +124,7 @@ Runtime/install asset changes follow this checklist:
 - `runtime/python/*` → `~/.okstra/lib/python/`
 - `runtime/bin/*` → `~/.okstra/bin/`
 - `runtime/templates/*` → `~/.okstra/templates/`
-- `runtime/skills/<name>` (the six user-facing skills only) → existing skill homes: `~/.claude/skills`, `~/.codex/skills`, or fallback `~/.omp/agent/skills`
+- `runtime/skills/<name>` (the seven user-facing skills only) → existing skill homes: `~/.claude/skills`, `~/.codex/skills`, or fallback `~/.omp/agent/skills`
 - `runtime/prompts/*` → `~/.okstra/prompts/` (lead contracts under `prompts/lead/`, coding-preflight pack under `prompts/coding-preflight/`)
 - `runtime/agents/workers/*.md` → `~/.claude/agents/*-worker.md` when `~/.claude` exists
 - install manifests → `~/.okstra/installed-skills.json` (target-aware), `~/.okstra/installed-agents.json`
@@ -163,6 +163,7 @@ Runtime/install asset changes follow this checklist:
 | `token-usage` | `src/commands/execute/token-usage.mjs` | Wrap installed Python token usage CLI |
 | `memory` | `src/commands/memory/memory.mjs` | Store/find global conversation memory under `~/.okstra/memory-book` |
 | `recap` | `src/commands/inspect/recap.mjs` | `okstra recap <assemble\|record>` Node wrapper backing the okstra-inspect `recap` facet |
+| `container` | `src/commands/inspect/container.mjs` | `bin okstra container` thin shim into `scripts/okstra_ctl/container.py` for the okstra-container skill |
 
 `src/lib/python-helper.mjs` centralizes Node → Python execution so command modules do not duplicate subprocess wiring.
 
@@ -211,9 +212,17 @@ Important modules:
 | `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Final-report data.json → Markdown → slim/HTML pipeline |
 | `wizard.py` | `okstra-run` prompt state machine; user-facing Korean strings live in `prompts/wizard/prompts.ko.json` |
 | `index.py`, `jsonl.py`, `reconcile.py`, `listing.py`, `batch.py`, `backfill.py` | `~/.okstra` run index and history operations |
+| `run_index_row.py` | `~/.okstra` run-index row 의 생성/축약(slim)/복원(hydrate) 단일 참조점 — runId SSOT, projectId raw 보존 |
+| `error_report.py`, `error_log_core.py`, `error_zip.py` | okstra-inspect errors/error-zip facet 백엔드 — `error_log_core` 는 `errors-*.jsonl` 글롭·파싱·집계 read-only 코어, `error_report` 는 errors facet 렌더, `error_zip` 은 cross-project run 디렉터리 수집·allowlist 익명화·클러스터 집계·zip 생성 |
+| `log_report.py`, `time_report.py` | okstra-inspect logs/time facet 의 read-side 백엔드 (`okstra log-report` 는 wrapper sidecar 로그 인벤토리, `okstra time-report` 는 task 단위 시간 집계) |
+| `stage_integrate.py` | whole-task stage 통합(머지)+worktree teardown 코어 (`integrate_stages`) — whole-task final-verification 진입·`okstra integrate-stages`·container up 이 공유 |
+| `resolve_task_key.py` | bare task-id → `task-catalog.json` 후보 entry 해석 skill 공용 helper (`okstra resolve-task-key`) |
 | `session.py`, `tmux.py`, `seeding.py`, `locks.py`, `invocation.py`, `sequence.py`, `ids.py`, `material.py` | Supporting lifecycle helpers |
 | `pane_reclaim.py` | 완료 trace pane 회수 대상 판정; 진행-중 status 집합을 `reconcile.NON_TERMINAL_RECENT_STATUSES` SSOT 에서 import |
 | `improvement_lenses.py` | improvement-discovery phase 의 lens enum SSOT + cap 상수 (DEFAULT 8, ABSOLUTE 12, MIN/MAX PRIORITY 1/4, SOURCE_WORKERS) |
+| `container.py` | okstra-container 수렴 entrypoint — `provision_container_group` + `up`/`status`/`logs`/`stop-watcher`/`down` 디스패치, env override 합성, compose argv 조립, 컨테이너별 watcher 기동 |
+| `container_registry.py` | flock-guarded 보조 인덱스 — 컨테이너 그룹별 tmux session/pane 및 watcher findings 추적 |
+| `plan_run_root.py` | `approved_plan_path` → `plan_run_root` 파생 + task-key 역추적 공유 헬퍼 |
 
 ### 4.4 `scripts/okstra_project/`
 
@@ -271,7 +280,7 @@ Token/cost accounting:
 
 ### 4.10 `skills/`
 
-6 user-facing skills (the only skills `okstra install` copies):
+7 user-facing skills (the only skills `okstra install` copies):
 
 | Skill | User-invocable | Role |
 |---|---:|---|
@@ -280,6 +289,7 @@ Token/cost accounting:
 | `okstra-memory` | yes | Store/search/archive global conversation memory under `~/.okstra/memory-book` |
 | `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup), `cost` (task bundle context/read cost) |
 | `okstra-schedule` | yes | Generate task-group schedule |
+| `okstra-container` | yes | Non-linear deploy tool — deploy a verified task's code as a docker compose group and watch each container (sub-commands `up` / `status` / `logs` / `stop-watcher` / `down`) |
 | `okstra-setup` | yes | Install/check runtime and register project |
 
 > The former internal skills — `context-loader`, `team-contract`, `convergence`, `report-writer`, `coding-preflight` — and the lead contract are no longer skills. They ship as runtime resources under `prompts/lead/*` and `prompts/coding-preflight/*` (installed to `~/.okstra/prompts/`); see §4.11.