okstra 0.97.1 → 0.98.1

package/runtime/python/okstra_project/state.py

@@ -119,11 +119,51 @@ def find_task_root(project_root: Path, task_key: str) -> Optional[Path]:
     return None
 
 
-def list_project_tasks(project_root: Path) -> list[dict]:
+def resolve_task_id(
+    project_root: Path,
+    task_id: str,
+    *,
+    task_group: Optional[str] = None,
+) -> list[dict]:
+    """bare task-id(옵션 task-group)로 catalog 후보 entry 목록을 돌려준다.
+
+    full task-key 해석(find_task_root)이 다루지 않는 한 겹: skill markdown 이
+    복제하던 "catalog 를 case-insensitive 로 훑어 taskId(필요시 taskGroup)가
+    일치하는 entry 를 모은다" 를 단일 SSOT 로 노출한다. 매칭은 find_task_root
+    의 taskKey 비교와 동일한 .lower() 케이스무시 규칙. entry dict 를 그대로
+    반환하므로 호출자가 분기·경로조립에 바로 쓴다(0개=없음, 1개=확정, N개=모호).
+    """
+    wanted_id = (task_id or "").strip().lower()
+    if not wanted_id:
+        return []
+    wanted_group = task_group.strip().lower() if task_group else None
+    matches: list[dict] = []
+    for entry in read_task_catalog(Path(project_root)):
+        entry_id = entry.get("taskId")
+        if not isinstance(entry_id, str) or entry_id.lower() != wanted_id:
+            continue
+        if wanted_group is not None:
+            entry_group = entry.get("taskGroup")
+            if not isinstance(entry_group, str) or entry_group.lower() != wanted_group:
+                continue
+        matches.append(entry)
+    return matches
+
+
+def list_project_tasks(
+    project_root: Path,
+    *,
+    task_type: Optional[str] = None,
+    latest_run_status: Optional[str] = None,
+    task_group: Optional[str] = None,
+    limit: Optional[int] = None,
+) -> list[dict]:
     """skill UI 에 보여줄 task 후보 목록을 돌려준다.
 
     각 항목은 task-catalog.json 의 entry 그대로 + 디스크 존재 여부 확인.
-    존재하지 않는 task root 는 skip(stale catalog 항목)한다.
+    존재하지 않는 task root 는 skip(stale catalog 항목)한다. 선택 필터(taskType /
+    latestRunStatus / taskGroup)는 AND 결합, limit 은 카탈로그 순서(updatedAt desc
+    로 저장됨)에서 앞쪽 N개. 모든 필터 인자가 기본값이면 기존 전체 목록과 동일.
     """
     project_root = Path(project_root)
     out = []
@@ -131,10 +171,18 @@ def list_project_tasks(project_root: Path) -> list[dict]:
         entry_key = entry.get("taskKey") or ""
         if not isinstance(entry_key, str) or not entry_key:
             continue
+        if task_type and entry.get("taskType") != task_type:
+            continue
+        if latest_run_status and entry.get("latestRunStatus") != latest_run_status:
+            continue
+        if task_group and entry.get("taskGroup") != task_group:
+            continue
         root = find_task_root(project_root, entry_key)
         if root is None:
             continue
         out.append({**entry, "_resolvedTaskRoot": str(root)})
+    if limit is not None and limit >= 0:
+        out = out[:limit]
     return out
 
 

package/runtime/skills/okstra-brief/SKILL.md

@@ -121,6 +121,12 @@ as source material, and never writes them. Decision files (when raised by
 
 Reuse the same literal-token-first rule as `okstra-run`. Each command below is a **separate Bash tool call** starting with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call.
 
+```bash
+okstra ensure-installed --runtime claude-code
+```
+
+If this exits non-zero, tell the user: "okstra not installed — run `/okstra-setup` first." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
+
 ```bash
 okstra check-project --json
 ```
@@ -130,7 +136,7 @@ Parse the JSON from stdout:
 - `ok: true` → use `projectRoot` from the JSON output. Carry it as a literal string into the steps below.
 - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
 
-> If the `okstra` binary is not on `PATH` at all, the command above will not run. In that case tell the user verbatim: "okstra not installed — run `/okstra-setup` first." Do **not** try to invoke `npx -y okstra@latest ...` from this skill — `npx` is not on the literal-token allow-list this skill targets and will force a confirmation prompt on every subsequent call.
+> If the `okstra` binary is not on `PATH` at all, the commands above will not run. In that case tell the user verbatim: "okstra not installed — run `/okstra-setup` first." Do **not** try to invoke `npx -y okstra@latest ...` from this skill — `npx` is not on the literal-token allow-list this skill targets and will force a confirmation prompt on every subsequent call.
 
 ## Step 1: Choose input source
 
@@ -328,9 +334,9 @@ If the user picked `Codebase scan`, gather the codebase-scan-specific inputs:
 
 1. `AskUserQuestion` (free text):
    `"Scan scope — comma-separated paths inside the project (e.g. src/foo/, src/bar/baz.py)"` → `scan_scope` (CSV).
-2. `AskUserQuestion` (multi-select, options = the 8 lens enum values from `scripts/okstra_ctl/improvement_lenses.py`'s `LENSES`):
+2. `AskUserQuestion` (multi-select, options = the lens values from `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py`'s `LENSES` — code source: `scripts/okstra_ctl/improvement_lenses.py`):
    `"Priority lenses (pick 1–4)"` → `priority_lenses` (1..4 values from the enum).
-   Enum values: `performance`, `security`, `readability`, `architecture`, `test-coverage`, `dx`, `observability`, `accessibility`.
+   Current `LENSES` values (this list mirrors the module — if they diverge, the module wins; Step 6.6 `validate-brief` enforces the subset): `performance`, `security`, `readability`, `architecture`, `test-coverage`, `dx`, `observability`, `accessibility`.
 3. `AskUserQuestion` (free text):
    `"Out-of-scope paths (optional, comma-separated)"` → `out_of_scope` (CSV, empty allowed).
 4. `AskUserQuestion` (free text):
@@ -345,7 +351,7 @@ If the user picked `Codebase scan`, gather the codebase-scan-specific inputs:
 Validation (before Step 4 sharpening):
 
 - `scan_scope` 의 각 path 가 `<PROJECT_ROOT>` 안에 실제 존재하는지 `ls` 로 확인 — 없으면 한 질문으로 정정.
-- `priority_lenses` 가 `scripts/okstra_ctl/improvement_lenses.py` 의 `LENSES` 부분집합 (1–4) 인지 확인 — 위반 시 enum 표시 + 재선택.
+- `priority_lenses` 가 `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py` 의 `LENSES` 부분집합 (1–4) 인지 확인 — 위반 시 enum 표시 + 재선택. 최종 enforcement 는 Step 6.6 `validate-brief` (`check_codebase_scope`) 가 수행.
 - `candidate_cap` 이 1–12 정수인지 확인.
 
 Once validation passes, jump to Step 2 (task key).
@@ -604,7 +610,7 @@ rather than the original source.
 
 1. **scan-scope 경로 존재 검증.** 각 path 를 `ls` / `Read` 로 확인. 없으면 한 질문으로 정정 (path 의 가장 가까운 후보를 `Recommended:` 로 제시).
 2. **모호 path narrowing.** `"백엔드"`, `"결제 모듈"` 같은 추상 path 는 구체 디렉토리 1개 이상으로 narrowing. codebase-first 추측 후 한 질문으로 확정.
-3. **priority-lenses 화이트리스트 검증.** `scripts/okstra_ctl/improvement_lenses.py` 의 `LENSES` 부분집합인지 확인. out-of-enum 이면 enum 내 가장 가까운 값을 `Recommended:` 로 제시.
+3. **priority-lenses 화이트리스트 검증.** `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py` 의 `LENSES` 부분집합인지 확인. out-of-enum 이면 enum 내 가장 가까운 값을 `Recommended:` 로 제시.
 4. **out-of-scope 일관성.** `out-of-scope` 의 각 path 가 `scan-scope` 의 부분집합인지 확인. 무관한 path 면 한 질문으로 제거 또는 scan-scope 에 흡수.
 5. **lens 우선순위 근거 1줄.** 각 priority lens 가 *왜* 이 scope 에서 우선인지 brief 본문에 한 줄 없으면, codebase 1차 훑은 결과를 `Recommended:` 로 제시 후 한 질문.
 
@@ -811,13 +817,17 @@ Inspect the finalized brief and recommend the next `okstra-run` task-type:
 | Heuristic | Recommendation |
 |---|---|
 | `Problem / Symptom` describes a repro / log / stack trace / observable error | `error-analysis` |
+| `Source Material` is okstra error-zip anonymized records (variant 1.C, no `scope`) | `error-analysis` |
 | `Open Questions` is large or `Desired Outcome` is ambiguous / needs classification | `requirements-discovery` |
 | `scope: codebase` frontmatter | `improvement-discovery` |
 | Both / ambiguous | `requirements-discovery` (safe default — the phase itself decides branching) |
 
 Write the chosen recommendation into the `Recommended next phase:` header
-line of the brief file (Step 5). Do NOT auto-spawn `okstra-run` — leave the
-trigger to the user.
+line of the brief file (Step 5). The template placeholder may enumerate only a
+subset (e.g. `<requirements-discovery | error-analysis>`); always write the
+value chosen from the full Step 6 enum (`requirements-discovery` |
+`error-analysis` | `improvement-discovery`), even when the placeholder omits it.
+Do NOT auto-spawn `okstra-run` — leave the trigger to the user.
 
 ## Step 6.5: Reporter batch confirmation (option B precondition)
 

package/runtime/skills/okstra-container/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: okstra-container
+description: |
+  Use to bring up, inspect, or tear down the okstra user-test container runtime for an implementation task — the docker-compose group okstra deploys from a task's worktree so a human can poke at the running build. Trigger words include "okstra container", "okstra container up", "okstra container down", "컨테이너 띄워", "컨테이너 올려", "컨테이너 내려", "컨테이너 상태", "컨테이너 로그", "유저 테스트 환경", "user test environment", "docker compose 띄워줘", "이 task 컨테이너로 띄워", "watcher 멈춰", "stop watcher", "감시 종료".
+---
+
+# OKSTRA Container
+
+Single entry point for the okstra user-test container runtime. okstra provisions a docker-compose group from an `implementation` task's worktree (the `docker-compose.yml` at the worktree root), labels it with the task's run-trace so later sub-commands can find the group, and tails it through a tmux watcher pane. This skill drives that lifecycle. Sub-commands:
+
+| Sub-command | What it does |
+|---|---|
+| `up` | Integrate the task's stages into the worktree, run `docker compose up -d`, poll healthchecks, and attach a watcher pane. |
+| `status` | Query the running containers (by run-trace label) plus the watcher metadata for a task-key. |
+| `logs` | Point at the watcher findings dir and per-service watcher state (logs live in the tmux pane, not a file). |
+| `stop-watcher` | Reap the watcher/tail panes only — the containers keep running. |
+| `down` | Tear down the containers (label query) and reap orphan watcher panes; `--all` covers every container group in the project. |
+
+## Step 0: Verify okstra runtime + project setup (shared)
+
+Before any sub-command, run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
+
+1. `okstra ensure-installed --runtime claude-code`
+   If this exits non-zero, tell the user: "okstra not installed — run `/okstra-setup` first." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
+
+2. `okstra check-project --json`
+   Reads the project from the current working directory. Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId}`.
+
+   - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
+   - `ok: true` → carry `projectRoot` as a literal string and pass it as `--project-root <projectRoot>` to every `okstra container` call below.
+
+Docker itself must be installed and running for `up`/`status`/`down` to work. If a sub-command fails with a docker connection error, tell the user to start Docker (Desktop / daemon) and retry — do not try to start docker yourself.
+
+Subsequent `okstra container <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
+
+## Step 1: Dispatch by intent
+
+Classify the user's request into one sub-command using the trigger table above.
+
+- Clear verbs route directly: "띄워/올려/up" → `up`; "상태/status" → `status`; "로그/logs" → `logs`; "watcher 멈춰/stop-watcher" → `stop-watcher`; "내려/down" → `down`.
+- If the request is ambiguous (e.g. "okstra container 좀 봐줘"), present a numbered picker. Recommend the 1–2 most likely facets first, and make the **last option always "직접 입력"** so the user can name any facet:
+
+  ```
+  무엇을 할까요?
+  1. status — 실행 중인 컨테이너 / watcher 상태 확인 (추천)
+  2. up — 이 task 의 컨테이너를 띄우기
+  3. 직접 입력 (up / status / logs / stop-watcher / down 중에서)
+  ```
+
+  The full facet list is the `Sub-command | What it does` table above — never hide a facet; if the user picks "직접 입력", let them name any row.
+
+When the user chains multiple facets in one message (e.g. "올렸다가 상태 보여줘"), execute them sequentially — Step 0 runs once, each sub-command section runs once.
+
+Every sub-command needs a **task-key** (`<project-id>:<task-group>:<task-id>`) — the container group is bound to one implementation task's worktree. Resolve it the same way across sub-commands:
+
+1. If the user gave a full task-key, use it.
+2. If the user gave only a task-id, resolve it via `okstra resolve-task-key <task-id> --project-root <projectRoot> --json` and branch on the stdout `matches[]`: single → use its `taskKey`; multiple → list candidates and ask (3-option picker); none → report not found.
+3. `down --all` is the only call that does not need a task-key (see `down`).
+
+---
+
+## up
+
+Trigger phrases: "okstra container up", "컨테이너 띄워", "컨테이너 올려", "유저 테스트 환경 띄워", "docker compose 올려줘", "이 task 컨테이너로 띄워".
+
+Brings up the task's container group: integrates the implementation stages into the task worktree, synthesizes the compose env override, runs `docker compose up -d`, polls healthchecks, and attaches a tmux watcher pane.
+
+**Preconditions** (state them if unmet, do not guess):
+- The task must be an `implementation` task whose worktree is registered in `~/.okstra/worktrees/registry.json`. If `up` fails with "task worktree 가 registry 에 없" → the task has no implementation worktree yet; tell the user to run the `implementation` phase first.
+- The worktree root must contain a `docker-compose.yml`. If `up` fails with "worktree 루트에 ... 가 없습니다" → no compose file shipped with this task; surface the message verbatim.
+- Every stage declared in the approved plan's Stage Map must be `done`. `up` integrates the whole task, so a partially-finished task (e.g. only stage 1 of 3 done) is refused rather than deployed as if complete (gate in `stage_targets.py`, shared with whole-task `final-verification`). If `up` fails with `final-verification(whole-task): stage N not done — run implementation --stage N first`, surface that message verbatim and tell the user to finish the named stage via the `implementation` phase with `--stage N`.
+
+Run:
+
+```bash
+okstra container up --project-root <projectRoot> --task-key <task-key>
+```
+
+Parse the stdout JSON and report the provisioned services and the watcher pane. If a service failed its healthcheck, the call surfaces the failing services and the `docker compose ... logs` line to inspect — relay that line; do not invent your own.
+
+After a successful `up`, tell the user how to reach the running build (the compose file's published ports) and that `okstra container status <task-key>` / `okstra container down <task-key>` manage it from here.
+
+---
+
+## status
+
+Trigger phrases: "okstra container status", "컨테이너 상태", "컨테이너 떠 있어?", "container status".
+
+Reports the running containers (queried by run-trace label — the source of truth for "is it up") plus the watcher metadata recorded in the registry.
+
+```bash
+okstra container status --project-root <projectRoot> --task-key <task-key>
+```
+
+Parse the stdout JSON (`{projectName, containers, watchers}`) and report:
+
+| Field | Meaning |
+|---|---|
+| `projectName` | the compose project name (label group) |
+| `containers` | running containers found by label — empty array means nothing is up |
+| `watchers` | per-service watcher metadata from the registry (auxiliary; may lag the label query) |
+
+If `containers` is empty, say the group is not running and offer `up`. Treat the label query — not the registry `watchers` — as authoritative for whether containers are alive.
+
+---
+
+## logs
+
+Trigger phrases: "okstra container logs", "컨테이너 로그", "container logs", "로그 어디서 봐".
+
+The live log stream lives in the tmux watcher pane, not in a file. This sub-command points at the watcher findings directory and the per-service watcher state.
+
+```bash
+okstra container logs --project-root <projectRoot> --task-key <task-key>
+```
+
+Add `--service <name>` to scope to one service:
+
+```bash
+okstra container logs --project-root <projectRoot> --task-key <task-key> --service <service>
+```
+
+Parse the stdout JSON (`{watchersDir, watchers}`). Report the `watchersDir` host path (under `~/.okstra/...`-style project artifacts — display the absolute path the CLI returns) and the watcher entries. Explain that the live stream is in the attached tmux pane; to see raw container logs the user runs `docker compose -p <projectName> logs -f <service>` (get `<projectName>` from `status`).
+
+---
+
+## stop-watcher
+
+Trigger phrases: "okstra container stop-watcher", "watcher 멈춰", "감시 종료", "stop watcher", "watcher 만 꺼줘".
+
+Reaps the watcher/tail tmux panes for the task **without stopping the containers**. Use when the user wants to silence the monitor but keep the build running.
+
+```bash
+okstra container stop-watcher --project-root <projectRoot> --task-key <task-key>
+```
+
+Parse the stdout JSON (`{reapedPanes, note}`). Confirm which panes were reaped and that the containers are still running (the `note` says so). If the user actually wants the containers gone, route to `down`.
+
+---
+
+## down
+
+Trigger phrases: "okstra container down", "컨테이너 내려", "컨테이너 종료", "container down", "전부 내려줘".
+
+Tears down the container group (removes containers found by the run-trace label) and reaps orphan watcher panes.
+
+Single task:
+
+```bash
+okstra container down --project-root <projectRoot> --task-key <task-key>
+```
+
+Every container group in the project (no task-key needed):
+
+```bash
+okstra container down --project-root <projectRoot> --all
+```
+
+Parse the stdout JSON (`{downed, orphanPanesReaped}`). Report each torn-down `projectName` and the orphan panes reaped. `down` removes containers with `docker rm -f` — confirm with the user before running `--all`, since it takes down every okstra container group in the project at once. A single-task `down` is safe to run directly once the task-key is resolved.
+
+---
+
+## Output Rules (shared)
+
+- Responses should be concise and written in Korean unless the user requests otherwise.
+- The stdout JSON from each `okstra container` call is the source of truth — do not run raw `docker` commands to second-guess it unless the CLI fails and the user explicitly asks for a manual fallback.
+- Show the resolved `<task-key>` in the heading so the user can confirm disambiguation.
+- Surface failure messages from the CLI verbatim (compose-up failures, missing worktree/compose file) — do not paraphrase the remediation line.
+- Display container/service states as-is from the JSON; do not normalize or remap.