okstra 0.36.0 → 0.36.2

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

@@ -0,0 +1,581 @@
+---
+name: okstra-inspect
+description: |
+  Use for any read-side okstra inspection or status mutation. Single skill dispatches by sub-command to five facets — status, history, report, time, logs. Trigger words include "okstra status", "task status", "current phase", "next phase", "okstra status set", "okstra mark", "<task-id> done|in-progress|진행중|완료", "okstra history", "past runs", "re-run", "resume", "list tasks", "find report", "show report for", "read the okstra report", "continue from report", "작업 시간", "소요 시간", "time summary", "duration", "elapsed", "얼마나 걸렸", "시간 분석", "okstra logs", "로그 현황", "로그 파일", "log files", "log size", "log status", "로그 정리", "log cleanup".
+---
+
+# OKSTRA Inspect
+
+Single read-side entry point for okstra runtime inspection plus the one write-side mutation that belongs here (`workStatus`). Sub-commands:
+
+| Sub-command | What it does |
+|---|---|
+| `status` | Task / phase status, blockers, approval state. Also writes `workStatus` on user request. |
+| `history` | List past okstra runs; assemble re-run or resume command. |
+| `report` | Resolve final-report path for a task-key. Optionally read it. |
+| `time` | Per-task-type and per-worker duration breakdown for a task. |
+| `logs` | Inventory codex/gemini wrapper `.log` sidecars; emit cleanup commands. |
+
+## 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`
+   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." 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 use it as the base for sub-command steps.
+
+Subsequent `okstra <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. If ambiguous (e.g. "okstra 보여줘"), ask which facet — do not silently default. After routing, the chosen sub-command's section below governs the rest of the response.
+
+When the user chains multiple facets in one message (e.g. "status, and then time for DEV-9047"), execute them sequentially — Step 0 runs once, each sub-command section runs once.
+
+---
+
+## status
+
+Trigger phrases: "okstra status", "task status", "current phase", "next phase", "what is pending", "resume point", "okstra status set", "okstra mark", "<task-id> done", "<task-id> in-progress", "<task-id> 진행중", "<task-id> 완료".
+
+### status.1 — Overall project status
+
+Read `.project-docs/okstra/discovery/task-catalog.json`. The catalog is the authoritative source — every field listed below (including `workStatus`, `workStatusUpdatedAt`, `workStatusNote`) is projected directly from each `task-manifest.json` by `scripts/okstra_ctl/render.py :: render_task_catalog_discovery`. Do NOT re-open individual manifests for the overview.
+
+| Field | Description |
+|------|------|
+| `taskKey` | `<project-id>:<task-group>:<task-id>` |
+| `taskType` | latest task type |
+| `workCategory` | bugfix / feature / improvement / refactor / ops-change / unknown. Display `unknown` as-is, but flag with `(unset)` annotation so the reader knows the requirements-discovery classification was skipped or no `--work-category` flag was passed. |
+| `currentStatus` | task-level status |
+| `currentPhase` | lifecycle current phase |
+| `currentPhaseState` | lifecycle phase state |
+| `nextRecommendedPhase` | next recommended phase |
+| `routingStatus` | routing decision status |
+| `awaitingApproval` | approval 대기 여부 |
+| `latestRunStatus` | latest run status |
+| `latestReportPath` | latest report path |
+| `latestResumeCommandPath` | latest resume command |
+| `workStatus` | user-managed work status (todo / in-progress / blocked / done; default in-progress) |
+| `updatedAt` | last update time |
+
+Sort by `updatedAt` desc, then `taskKey`.
+
+The overview table is intentionally narrow so it renders cleanly in a terminal. Only six columns are shown; for any task that needs a closer look (phase state, routing, approval gate, last run status, resume path, etc.) tell the user to run `okstra status <task-key>` (or `/okstra-inspect status <task-key>`) for the detail view in `status.2`.
+
+If `awaitingApproval` is true OR `routingStatus == "pending"`, append a `*` to the `Next` cell and explain the marker once below the table.
+
+```markdown
+## okstra Status — <project-id>
+
+| # | Task Key | Category | Phase | workStatus | Next |
+|---|----------|----------|-------|------------|------|
+| 1 | proj:group:id | bugfix | error-analysis | in-progress | implementation-planning |
+| 2 | proj:group:id2 | feature | requirements-discovery | done | pending-routing-decision* |
+
+`*` = awaiting user approval or pending routing decision. Run `okstra status <task-key>` for details.
+```
+
+### status.2 — Specific task status
+
+Given a specific `task-key` or `task-group + task-id`:
+
+1. If possible, quickly look it up in `task-catalog.json`.
+2. If necessary, read `.project-docs/okstra/tasks/<task-group>/<task-id>/task-manifest.json` directly.
+3. If you need the latest run information, read `history/timeline.json` along with the latest run manifest.
+
+Required fields: `taskKey`, `taskType`, `workCategory`, `currentStatus`, `latestRunStatus`, `workflow.{currentPhase, currentPhaseState, phaseStates, lastCompletedPhase, nextRecommendedPhase, awaitingApproval, routingStatus, lastSafeCheckpoint}`, `workStatus`, `workStatusUpdatedAt`, `workStatusNote`, `latestReportPath`, `latestResumeCommandPath`, `historyTimelinePath`.
+
+```markdown
+## okstra Task Status — <task-key>
+
+- Work category: `<category>`
+- Current phase: `<phase>`
+- Current phase state: `<phase-state>`
+- Last completed phase: `<phase-or-->`
+- Next recommended phase: `<phase>`
+- Awaiting approval: `<yes|no>`
+- Routing status: `<routing-status>`
+- Task status: `<task-status>`
+- Latest run status: `<run-status>`
+- Latest report: `<relative-path-or-->`
+- Resume command: `<relative-path-or-->`
+- workStatus: `<todo|in-progress|blocked|done>` (updated `<workStatusUpdatedAt-or-->`)
+- workStatus note: `<workStatusNote-or-->`
+
+### Phase States
+
+- `requirements-discovery`: `<state>`
+- `error-analysis`: `<state>`
+- `implementation-planning`: `<state>`
+- `implementation`: `<state>`
+- `final-verification`: `<state>`
+- `release-handoff`: `<state>`
+
+### Safe Resume Checkpoint
+
+- Label: `<checkpoint-label>`
+- Run manifest: `<relative-path-or-->`
+- Team state: `<relative-path-or-->`
+- Report: `<relative-path-or-->`
+- Resume command: `<relative-path-or-->`
+```
+
+### status.3 — Resume / next-step guidance
+
+The status response always includes one of:
+
+1. **Resume current run** — if `latestResumeCommandPath` exists, display that path.
+2. **Restart current phase** — task can be re-run with the same `task-key` and current `taskType`.
+3. **Start next phase** — if `workflow.nextRecommendedPhase` is one of `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`, that phase is proposed. If `nextRecommendedPhase` is `pending-release-handoff`, surface as verdict-gated and propose `release-handoff` only when the cited verdict is `accepted`.
+4. **Need more information** — if `nextRecommendedPhase` is `pending-routing-decision` or `routingStatus` is `pending`.
+5. **Task complete (terminal)** — if `nextRecommendedPhase` is `done-or-follow-up`, the task lifecycle has reached its terminal signal. This is **not** a "next phase" — do not propose a new okstra run. Surface the latest report and ask the user whether any follow-up task should be opened separately.
+
+### status.4 — Update workStatus (write)
+
+Recognize requests to change a task's `workStatus` and update the corresponding `task-manifest.json`.
+
+**Trigger patterns** (recognize both):
+
+Natural language: "DEV-6827 done으로 바꿔줘", "PROD-1623을 blocked로 표시", "DEV-9047 진행중", "Mark DEV-6827 as done".
+
+Explicit command:
+- `okstra status set <task-id> <status>`
+- `okstra status set <task-group> <task-id> <status>` (disambiguation)
+- `okstra mark <task-id> <status>`
+- `okstra status set <task-id> <status> --note "<note>"`
+
+Accepted `<status>` values: `todo`, `in-progress`, `blocked`, `done`.
+
+**Procedure:**
+
+1. **Validate status value.** If not in the enum, output an error and the allowed values list. Do not modify any file.
+2. **Look up the task** in `.project-docs/okstra/discovery/task-catalog.json` by `task-id` (case-insensitive on both `task-id` and `task-group`).
+   - If the user provided `<task-group>` explicitly, scope the lookup to that group (case-insensitive).
+   - Single match → proceed. Multiple matches across different groups → list and ask user to retry with explicit form (`okstra status set <task-group> <TASK-ID> <status>`). No match → `<TASK-ID>를 찾을 수 없습니다.` and stop.
+3. **Open the matching `task-manifest.json`** at `.project-docs/okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json`. Assemble the path from the catalog entry's `taskGroupPathSegment` and `taskIdPathSegment` fields (filesystem-safe segments emitted by the renderer) — NOT from the raw user-supplied strings, which may differ in case or contain characters normalized when the manifest was created. Prefer the `taskManifestPath` field directly when present.
+4. **Update fields at the manifest root:**
+   - `workStatus` ← new status value
+   - `workStatusUpdatedAt` ← current ISO-8601 UTC timestamp (`2026-05-01T10:23:45Z`)
+   - `workStatusNote`: if `--note` provided, set to its value; if not provided, leave any existing value untouched (do not delete, do not blank). If the field did not exist before, do not create it.
+
+   **Manifest preservation (critical):**
+   - Use a targeted in-place edit (Edit tool with old_string/new_string anchors).
+   - Do NOT round-trip the file through `JSON.parse` + `JSON.stringify` — that reorders keys, drops trailing newlines, normalizes spacing.
+   - Preserve existing key order, indentation, and trailing newline exactly.
+
+5. **Confirm in Korean:**
+   ```
+   ✓ <TASK-ID> workStatus: <previous> → <new>
+   ✓ task-manifest.json 업데이트됨
+   ```
+   `<previous>` = `(없음)` if the field was absent before.
+
+**Default value convention:** if `workStatus` is missing or empty, infer the display value from lifecycle state (DO NOT default to a static `in-progress`):
+
+| Manifest state | Inferred display |
+|---|---|
+| `currentStatus == "completed"` AND `workflow.nextRecommendedPhase == "done-or-follow-up"` | `done` (inferred) |
+| `currentStatus == "completed"` AND `workflow.currentPhaseState == "completed"` | `phase-done` (inferred) |
+| `currentStatus == "contract-violated"` OR `workflow.currentPhaseState == "blocked"` | `blocked` (inferred) |
+| anything else | `in-progress` (default) |
+
+Annotate inferred values with `(inferred)` or `(default)`. Do not back-fill on read; only write when the user explicitly issues an update.
+
+**Catalog sync note:** this sub-command updates `task-manifest.json` only. `discovery/task-catalog.json` may become stale until regenerated. Downstream consumers (e.g. `okstra-schedule`) should re-read each manifest directly.
+
+---
+
+## history
+
+Trigger phrases: "okstra history", "past runs", "run history", "re-run", "list tasks", "다시 실행", "resume", "이어서".
+
+**Re-run vs Resume — decide upfront.** Re-run = start a fresh run (new run-seq, new manifest, new report) reusing an old run's parameters → `history.3`. Resume = continue an interrupted Claude session for an existing run, no new run-seq → `history.4`. If the user is ambiguous, ask — defaulting to the wrong one either wastes a fresh run-seq or silently abandons a recoverable session.
+
+### history.1 — Read the task catalog
+
+1. Read `.project-docs/okstra/discovery/task-catalog.json`.
+2. Apply filters from user input (all optional, AND-combined):
+   - `--task-type <type>` → keep entries whose `taskType` matches.
+   - `--latest-run-status <status>` → keep entries whose `latestRunStatus` matches (`completed`, `contract-violated`, `error`).
+   - `--task-group <group>` → keep entries whose `taskGroup` matches.
+3. Sort by `updatedAt` desc.
+4. Page: default `--limit 20`. If truncated, add `... <N> more (pass --limit <N> to see all)`.
+5. Extract: `taskKey`, `taskType`, `currentStatus`, `latestRunStatus`, `latestRunManifestPath`, `updatedAt`, `latestReportPath`, `latestResumeCommandPath`, `historyTimelinePath`.
+
+```markdown
+## okstra Task History — <project-id>
+
+| # | Task Key | Type | currentStatus | latestRunStatus | Last Run | Report |
+|---|----------|------|---------------|------------------|----------|--------|
+| 1 | proj:group:id | error-analysis | completed | completed | 2026-04-05 22:59 | .project-docs/.../final-report-*.md |
+| 2 | proj:group:id2 | final-verification | todo | error | 2026-04-04 15:30 | -- |
+```
+
+**Catalog absent — fallback.** Do NOT bail out. Manifests on disk are the source of truth.
+
+1. Glob `<projectRoot>/.project-docs/okstra/tasks/*/*/task-manifest.json`.
+2. For each manifest, read the same fields as above.
+3. Apply the same filters/sort/limit and print the same table, prefixed with: `note: task-catalog.json missing; reconstructed from task manifests on disk.`
+4. Only if the glob yields zero manifests: `There is no okstra execution history yet.`
+
+### history.2 — Run history by task
+
+When a user selects a specific task:
+
+1. Retrieve `historyTimelinePath`, read `runs` array.
+2. Extract: `runTimestamp`, `runDateTimeSegment`, `taskType`, `status`, `runManifestPath`, `reportPath`, `resumeCommandPath`, `relatedTasks`.
+
+```markdown
+## Runs for <task-key>
+
+| # | Timestamp | Type | Status | Report |
+|---|-----------|------|--------|--------|
+| 1 | 2026-04-05 22:59 | error-analysis | completed | .../final-report-*.md |
+| 2 | 2026-04-04 15:30 | error-analysis | error | -- |
+```
+
+### history.3 — Re-run (NEW run from old parameters)
+
+Builds a fresh run — new run-seq, new manifest, new report — using parameters from a previous `run-manifest-*.json`. Does NOT touch old artifacts; use `history.4` to continue an interrupted session.
+
+1. Pick the source run-manifest: `runManifestPath` from `history.2`, or task's `latestRunManifestPath` from `history.1`.
+2. Read the manifest and extract required arguments:
+   - `projectId` → `--project-id`
+   - `taskGroup` → `--task-group`
+   - `taskId` → `--task-id`
+   - `taskType` → `--task-type`
+   - `taskBriefPath` → `--task-brief`
+3. Optional arguments (include only when present in source):
+   - `recommendedWorkers` → `--workers` (comma-separated)
+   - `relatedTasks` → `--related-tasks`
+   - model overrides → `--claude-model`, `--codex-model`, `--gemini-model`
+   - for `taskType: implementation`: `teamContract.executor.provider` → `--executor <claude|codex|gemini>` when different from `claude`.
+4. **`taskType: implementation` only — resolve `--base-ref`:** base ref is NOT in the run-manifest; it lives in the worktree registry at `~/.okstra/worktrees/registry.json`. If a worktree is already registered, existing branch & base are reused — omit `--base-ref` unless the user explicitly wants a different starting point. If no worktree is registered (cleaned up), `--base-ref` is mandatory — ask the user before running.
+5. Display the assembled command:
+   ```bash
+   okstra.sh \
+     --project-id <project-id> \
+     --task-group <task-group> \
+     --task-id <task-id> \
+     --task-type <task-type> \
+     --task-brief <brief-path> \
+     --workers <worker-list>
+   ```
+6. Once the user confirms, execute it.
+
+### history.4 — Resume (continue an interrupted run)
+
+Continues an existing Claude session for an unfinished run. Does NOT create a new run-seq — for a fresh dispatch use `history.3`.
+
+1. Read `latestResumeCommandPath` from `history.1` (or `resumeCommandPath` from a `history.2` timeline entry).
+2. Verify the file exists on disk.
+3. If present: `bash <resume-command-path>`.
+4. If absent: `No resume script available for this run. Use 'history.3' to start a fresh run instead.`
+
+---
+
+## report
+
+Trigger phrases: "find report", "show report for", "read the okstra report", "continue from report".
+
+### report.1 — Resolve report path
+
+task-key format: `<project-id>:<task-group>:<task-id>`.
+
+**Normalization:** task-key matching is lowercase. Disk segments are slugified (lowercase + non-alphanumeric runs → `-`) per `scripts/lib/okstra/interactive.sh:147`. Catalog lookup is case-insensitive; file path assembly uses slugified segments.
+
+Lookup methods (in priority order):
+
+A. **`task-catalog.json` (fast):** read `.project-docs/okstra/discovery/task-catalog.json`, match `taskKey` lowercase. `latestReportPath` is task-type-agnostic "most recent report".
+
+B. **`task-manifest.json` (direct):** if catalog missing, slugify task-group / task-id, read `.project-docs/okstra/tasks/<group-segment>/<id-segment>/task-manifest.json`, use `latestReportPath` (task-type-agnostic).
+
+C. **`timeline.json` (specific run):** for a specific date or run, read `.project-docs/okstra/tasks/<group-segment>/<id-segment>/history/timeline.json`, filter `runs[]` by `runTimestamp` / `status` / `taskType`, use `runs[].reportPath`.
+
+D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic. For a specific task-type's latest report, look under `.project-docs/okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.md` per `scripts/okstra_ctl/sequence.py:31`. Highest seq is latest. Cross-verify with `timeline.json`'s `runs[].taskType` filter.
+
+### report.2 — Confirm existence
+
+1. Verify `latestReportPath` is non-empty AND the file exists on disk. Either signal indicates report presence (tolerant).
+2. If present, display the path and ask the user whether to read it.
+3. If absent, check `task-manifest.json` signals:
+   - `latestReportPath` empty/missing AND `currentStatus != completed` AND `workStatus != done` AND `workflow.routingStatus` not completion-like → `이 task는 아직 완료되지 않았습니다 (currentStatus: <currentStatus>, workStatus: <workStatus>).`
+   - Any signal indicates completion but the file is missing → `보고서 파일이 존재하지 않습니다: <path>`
+
+`workStatus` enum: `todo | in-progress | blocked | done`. `currentStatus`: `completed` / `contract-violated` etc. `"completed"` string does NOT exist in `workStatus` — do not confuse the two.
+
+### report.3 — Read + next-step guidance
+
+After reading the report, surface follow-up options:
+
+1. **구현 진행:** based on the report's "권장 다음 단계" section.
+2. **추가 검증:** new okstra run with the same task-key:
+   ```bash
+   scripts/okstra.sh --task-key <task-key> --task-type <task-type>
+   ```
+   For richer options (base-ref, workers, render-only), use the `history` sub-command.
+3. **관련 task 확인:** if the report references related task-keys, fetch their reports too.
+
+### report — Output template
+
+```markdown
+## Report for <task-key>
+
+| Field        | Value                                              |
+| ------------ | -------------------------------------------------- |
+| Status       | `<status>`                                         |
+| Task type    | `<task-type>`                                      |
+| Run seq      | `<NNN>`                                            |
+| Run date     | `<runTimestamp ISO-8601>`                          |
+| Report (rel) | `<relative-path-from-project-root>`                |
+| Report (abs) | `<absolute-path>`                                  |
+```
+
+---
+
+## time
+
+Trigger phrases: "작업 시간", "소요 시간", "time summary", "duration", "elapsed", "얼마나 걸렸", "시간 분석".
+
+Aggregate elapsed work time for a given task, grouped by **task type** and broken down by **worker** (lead, claude, codex, gemini, report-writer).
+
+**Data sources** (both collected by okstra):
+
+1. `.project-docs/okstra/tasks/<task-group>/<task-id>/history/timeline.json` — `runs` array with `runTimestamp`, `taskType`, `status`, `teamStatePath`, `taskRootPath`. Both path fields may be either project-root-relative or task-root-relative depending on which `render.py` version wrote the manifest.
+2. Each run's `.../runs/<task-type>/state/team-state-<suffix>.json` — populated by `scripts/okstra-token-usage.py` at Phase 7. Contains `leadUsage.{startedAt, endedAt, durationMs}` and `workers[].{workerId, agent, usage.{startedAt, endedAt, durationMs}}`.
+
+If a run never reached Phase 7, its `team-state` lacks `durationMs`. Mark such runs as `unavailable` rather than guessing.
+
+### time.1 — Resolve task-id → timeline path
+
+1. If the user gave a full `task-key`, use it directly.
+2. Otherwise read `.project-docs/okstra/discovery/task-catalog.json` and find the entry whose `taskId` matches.
+3. Multiple matches → list candidates (`taskKey`, `taskType`, `updatedAt`) and ask the user to pick.
+4. Read `historyTimelinePath` from the chosen entry.
+
+If `task-catalog.json` is missing: `No okstra history found. Run scripts/okstra.sh first.`
+
+### time.2 — Walk runs and collect durations
+
+For each entry in `timeline.json`'s `runs` array:
+
+1. Resolve the `team-state` file via two-step lookup:
+   a. First try `<projectRoot>/<teamStatePath>`.
+   b. If that file does not exist, fall back to `<projectRoot>/<taskRootPath>/<teamStatePath>` (the manifest's `taskRootPath` is task-root relative to project root; `teamStatePath` written by `render.py` is task-root-relative in many runs).
+   If neither resolves, treat the run as `unavailable`.
+2. Extract `taskType` from the timeline entry (authoritative), `leadUsage.durationMs` and `leadUsage.{startedAt,endedAt}`, and for each `worker` in `workers[]`: `workerId`, `agent`, `usage.durationMs`. Read defensively — `usage` (and `leadUsage`) may be:
+   - a normal `usage_block` with `durationMs >= 0`,
+   - a `na_block` with `{"source": "unavailable", "durationMs": 0, "note": ...}` when Phase 7 collection failed,
+   - missing entirely (older team-state files), or `None`.
+   Normalize via `(block or {}).get("durationMs", 0) or 0`, and treat `source == "unavailable"` as zero contribution.
+3. If the team-state file is missing, or every `durationMs` for the run is `0`/absent, record the run under `unavailable` with its `runTimestamp` and `taskType`.
+
+### time.3 — Aggregate
+
+**A. Per task-type summary:**
+
+| Column | Computation |
+|--------|-------------|
+| `Runs` | count of runs of that task type that contributed any duration |
+| `CPU sum` | sum of (lead + all workers) across those runs |
+| `Lead` | sum of `leadUsage.durationMs` |
+| `Workers` | sum of all `workers[].usage.durationMs` |
+
+Add a final `Grand total` row.
+
+**Note on `CPU sum` vs wall-clock:** workers run as children of the lead session, so the lead's `durationMs` window OVERLAPS its workers' windows. `CPU sum = Lead + Workers` is an additive CPU-style sum, not the wall-clock elapsed time the user actually waited.
+
+Worked example for one run with three concurrent workers:
+
+```
+lead       [================================]  durationMs = 1800000 (30:00)
+claude       [============]                     durationMs =  720000 (12:00)
+codex        [==============]                   durationMs =  840000 (14:00)
+gemini       [========]                         durationMs =  480000 (08:00)
+```
+
+- `CPU sum` for the run = `1800000 + 720000 + 840000 + 480000` = `3840000` (`01:04:00`)
+- Wall-clock for the run = `max(endedAt) − min(startedAt)` ≈ `30:00`
+
+Always report `CPU sum` in the by-task-type table. If the user explicitly asks for wall-clock, compute it per run as `max(leadUsage.endedAt, max(workers[].usage.endedAt)) − min(leadUsage.startedAt, min(workers[].usage.startedAt))` and surface it separately — never silently substitute.
+
+**B. Per worker breakdown (per task type):**
+
+For each task type, list one row per `workerId` actually present, plus `lead`. Aggregate `durationMs` across all runs of that task type.
+
+| Worker | Runs | Total | Avg/run |
+|--------|------|-------|---------|
+
+- `Runs` denominator = number of runs of this task type in which this worker recorded a **nonzero** `durationMs`. A run where the worker's block was `na_block`, missing, or `0` does NOT count.
+- If `Runs == 0` for a worker, **omit the row entirely** rather than dividing by zero.
+- `Avg/run = Total / Runs` (integer ms, then format to `HH:MM:SS`).
+
+Use the `workerId` from team-state. Valid enum: `lead, claude, codex, gemini, report-writer`.
+
+Display rule for `workerId` vs `agent`:
+- If every run of this task type used `agent == workerId` for this row, display the bare `workerId`.
+- If `agent` differs (e.g. a `claude` worker slot ran with `agent == "sonnet-eval"`), display `workerId (agent)`. Multiple distinct agents across runs → comma-join: `claude (sonnet-eval, opus-eval)`.
+
+Never write `claude (claude)` — the parenthesized agent is shown only when it adds information.
+
+**Timestamp parsing:** for `startedAt` / `endedAt`, normalize ISO-8601: replace trailing `Z` with `+00:00`, accept explicit offsets as-is, parse via `datetime.fromisoformat(s.replace("Z", "+00:00"))`. Strings without an offset are assumed UTC. Mixed-form comparisons must be done as `datetime` objects, never raw strings.
+
+### time.4 — Format output
+
+- Convert `durationMs` to `HH:MM:SS` (zero-pad). Example: `7384000ms` → `02:03:04`.
+- Sort task types by order of first appearance in the timeline (chronological, not alphabetical).
+- If any runs were `unavailable`, append a final note listing them with reason.
+
+```markdown
+## Time summary — <task-key>
+
+### By task type
+
+| Task type              | Runs | CPU sum   | Lead     | Workers  |
+|------------------------|------|-----------|----------|----------|
+| requirements-discovery | 2    | 00:33:12  | 00:12:08 | 00:21:04 |
+| error-analysis         | 1    | 00:18:45  | 00:08:11 | 00:10:34 |
+| implementation         | 3    | 02:11:09  | 00:45:30 | 01:25:39 |
+| **Grand total**        | 6    | **03:03:06** | 01:05:49 | 01:57:17 |
+
+`CPU sum` adds the lead window to each worker window even though they overlap; it is not a wall-clock total.
+
+### Per worker — requirements-discovery
+
+| Worker         | Runs | Total    | Avg/run  |
+|----------------|------|----------|----------|
+| lead           | 2    | 00:12:08 | 00:06:04 |
+| claude         | 2    | 00:09:12 | 00:04:36 |
+| codex          | 2    | 00:07:40 | 00:03:50 |
+| gemini         | 2    | 00:03:12 | 00:01:36 |
+| report-writer  | 2    | 00:01:00 | 00:00:30 |
+
+> Unavailable: 1 run (implementation / 2026-04-30_03-03-48) — team-state has no durationMs (Phase 7 not reached)
+```
+
+**Rules:**
+- Always render durations as `HH:MM:SS`; never raw milliseconds.
+- Never invent or estimate `durationMs`. Missing → `--`.
+- Never sum across `unavailable` runs into the totals — those are reported only in the trailing note.
+- Show the resolved `<task-key>` in the heading so the user can confirm disambiguation.
+
+---
+
+## logs
+
+Trigger phrases: "okstra logs", "로그 현황", "로그 파일", "log files", "log size", "log status", "로그 정리", "log cleanup".
+
+Read-only inventory of codex/gemini wrapper log files written next to each prompt history file (`<prompt>.log`). Reports sizes, ages, totals, and suggests cleanup commands. **Does not delete** — the user runs whichever `find … -delete` line they like.
+
+**Background:** codex/gemini wrappers (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`) write a sidecar log next to each prompt history file:
+
+```
+.project-docs/okstra/tasks/<task-group>/<task-id>/runs/<phase>/prompts/
+  <worker>-prompt-<phase>-<seq>.md    <-- prompt (git-tracked)
+  <worker>-prompt-<phase>-<seq>.log   <-- live stdout+stderr mirror
+```
+
+The log is truncated at each dispatch (`: > "$log_path"`) — only the latest run for a given seq is preserved. Different seqs keep separate files. Long-running implementation dispatches can produce multi-MB logs; analysis-phase dispatches are typically smaller.
+
+### logs.1 — Inventory
+
+Construct the logs root by appending `/.project-docs/okstra/tasks` to the literal `projectRoot` value parsed in Step 0; paste as a literal absolute path in place of `<LOGS_ROOT>` below (no shell variables, no `$(...)`):
+
+```bash
+find <LOGS_ROOT> -type f -path '*/runs/*/prompts/*.log' \
+  -printf '%s\t%T@\t%p\n' 2>/dev/null \
+  | sort -k1,1nr
+```
+
+Columns: `size_bytes | mtime_epoch | path`.
+
+On macOS, `find -printf` is unavailable. Fall back to `-exec stat`:
+
+```bash
+find <LOGS_ROOT> -type f -path '*/runs/*/prompts/*.log' -exec stat -f '%z%t%m%t%N' {} + 2>/dev/null | sort -k1,1nr
+```
+
+If empty, report `No wrapper log files found under <projectRoot>` and exit.
+
+### logs.2 — Summary tables
+
+**Table A — Top 20 largest logs:**
+
+| # | Task | Phase | Worker | Seq | Size | Age | Path |
+|---|------|-------|--------|-----|------|-----|------|
+
+Parse fields from the path: task-group / task-id from the `tasks/<task-group>/<task-id>/` segment; phase from `runs/<phase>/`; worker from filename prefix before `-prompt-`; seq from filename suffix (last 3-digit segment). Format sizes as KB/MB. Format age as `Nd` (days) or `Nh` (hours) from `mtime` relative to "now".
+
+**Table B — Per-task totals:**
+
+| Task Key | Files | Total Size | Oldest | Newest |
+|----------|-------|-----------:|--------|--------|
+
+Sort by total size desc. "Task Key" = `<project-id>:<task-group>:<task-id>` for consistency with other sub-commands.
+
+**Footer:** `Total: N files, X.X MB across M tasks under <PROJECT_ROOT>`.
+
+### logs.3 — Suggested cleanup commands
+
+Emit a fenced bash block the user can copy-paste. Do NOT execute. Each block pairs a dry-run preview (`-print`) with the destructive (`-delete`) command:
+
+```markdown
+## Cleanup options (manual)
+
+# 7일 이상 된 로그만 삭제
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +7 -print    # dry-run
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +7 -delete
+
+# 30일 이상 된 로그만 삭제
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +30 -print   # dry-run
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +30 -delete
+
+# 특정 task-group 의 로그 일괄 삭제 (예: dev-9388)
+find <PROJECT_ROOT>/.project-docs/okstra/tasks/dev-9388 \
+  -type f -name '*.log' -print    # dry-run
+find <PROJECT_ROOT>/.project-docs/okstra/tasks/dev-9388 \
+  -type f -name '*.log' -delete
+
+# 특정 task-id 의 로그 일괄 삭제 (예: dev-9428)
+find <PROJECT_ROOT>/.project-docs/okstra/tasks/*/dev-9428 \
+  -type f -name '*.log' -print    # dry-run
+find <PROJECT_ROOT>/.project-docs/okstra/tasks/*/dev-9428 \
+  -type f -name '*.log' -delete
+
+# 전체 일괄 삭제 (주의)
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -print    # dry-run
+find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -delete
+```
+
+Substitute the literal `<PROJECT_ROOT>` with the resolved absolute path so the commands are directly copy-pasteable.
+
+### logs.4 — Notes for the user
+
+- Logs are truncated on each re-dispatch of the same `seq`, so deleting an in-flight run's log will cause the wrapper to recreate an empty file on the next dispatch — no data loss beyond the current trace.
+- **If a dispatch is currently running, check the `status` sub-command first** and avoid deleting logs for tasks in `in-progress` state — you will lose the live trace for the active run.
+- Prompt history files (`.md`) are separate and are NOT touched by these commands — only `.log` sidecars.
+- This sub-command **does not modify any external files itself**, including `.gitignore`. If the project commits `.project-docs/okstra/`, the user may want to add `.project-docs/okstra/tasks/**/runs/**/prompts/*.log` to `.gitignore` manually to keep large logs out of git.
+
+---
+
+## Output Rules (shared)
+
+- Responses should be concise and written in Korean unless the user requests otherwise.
+- Use project-relative paths whenever possible.
+- If there is no recent report, display `--`.
+- If a specific task does not exist, explicitly state that it cannot be found based on `task-catalog.json`.
+- If `awaitingApproval` is true, clearly indicate that the task is awaiting user approval.
+- Display status fields as-is from disk (`completed`, `contract-violated`, `todo`, `error`, empty, ...). Do not normalize or remap.
+- Dates in `YYYY-MM-DD HH:MM` format.

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

@@ -18,9 +18,9 @@ Launch an okstra task — gather inputs interactively via the **wizard state mac
 
 ## When NOT to Use
 
-- User explicitly asks to spawn a new terminal / new claude — use `okstra-history` Step 4 (resume command) or instruct them to run `okstra` in another terminal.
-- User wants status only — use `okstra-status`.
-- User wants past runs — use `okstra-history`.
+- User explicitly asks to spawn a new terminal / new claude — use `okstra-inspect history.4` (resume command) or instruct them to run `okstra` in another terminal.
+- User wants status only — use `okstra-inspect status`.
+- User wants past runs — use `okstra-inspect history`.
 
 ## How the wizard talks to you