okstra 0.124.0 → 0.125.0

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

@@ -6,19 +6,19 @@ description: >-
 
 # OKSTRA Inspect
 
-Single read-side entry point for okstra runtime inspection plus the one status mutation that belongs here (`workStatus`) and read-derived artifact rendering (`errors` report). Sub-commands:
+Single read-side entry point for okstra runtime inspection plus the one status mutation that belongs here (`workStatus`) and read-derived artifact rendering (`errors` report). Each sub-command's full procedure lives in a lazily loaded facet file — after dispatch, Read exactly the one facet you need.
 
-| 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/antigravity wrapper `.log` sidecars; emit cleanup commands. |
-| `cost` | Estimate file/read context cost for a task bundle. |
-| `errors` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
-| `error-zip` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
-| `recap` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`, and writes agent-authored notes to `notes/` for feeding into later runs. |
+| Sub-command | Facet file | What it does |
+|---|---|---|
+| `status` | `facets/status.md` | Task / phase status, blockers, approval state. Also writes `workStatus` on user request. |
+| `history` | `facets/history.md` | List past okstra runs; assemble re-run or resume command. |
+| `report` | `facets/report.md` | Resolve final-report path for a task-key. Optionally read it. |
+| `time` | `facets/time.md` | Per-task-type and per-worker duration breakdown for a task. |
+| `logs` | `facets/logs.md` | Inventory codex/antigravity wrapper `.log` sidecars; emit cleanup commands. |
+| `cost` | `facets/cost.md` | Estimate file/read context cost for a task bundle. |
+| `errors` | `facets/errors.md` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
+| `error-zip` | `facets/error-zip.md` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
+| `recap` | `facets/recap.md` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`, and writes agent-authored notes to `notes/` for feeding into later runs. |
 
 ## Step 0: Preflight (shared)
 
@@ -48,748 +48,34 @@ Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this
 
 ## Step 1: Dispatch by intent
 
-Classify the user's request into one sub-command using the trigger table above. If ambiguous (e.g. "show me okstra"), ask which facet — do not silently default. After routing, the chosen sub-command's section below governs the rest of the response.
-
-When you ask which facet, the option list is **authoritative**: enumerate every sub-command in the `Sub-command | What it does` table above as a numbered text list, in table order, each with its one-line description, and let the user pick by number or name. Never present a hand-picked subset — the AskUserQuestion 4-option cap is not a reason to drop facets; render the full menu as text in the question body so no facet (e.g. a newly added one) is ever hidden. The table is the single source of truth for this menu; adding a row there is all it takes for the facet to appear here.
-
-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> in progress", "<task-id> complete".
-
-### status.1 — Overall project status
-
-Read `.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 / 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` | whether awaiting 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-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-inspect 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 `.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>
+Classify the user's request into one sub-command using the trigger table above. If ambiguous (e.g. "show me okstra"), ask which facet — do not silently default. After routing, **Read the chosen row's facet file** (path relative to this skill's base directory) and follow it for the rest of the response. Load exactly one facet per sub-command — never preload the others.
 
-- 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-->`
+When you ask which facet, the option list is **authoritative**: enumerate every sub-command in the dispatch table above as a numbered text list, in table order, each with its one-line description, and let the user pick by number or name. Never present a hand-picked subset — the AskUserQuestion 4-option cap is not a reason to drop facets; render the full menu as text in the question body so no facet (e.g. a newly added one) is ever hidden. The table is the single source of truth for this menu; adding a row there (plus its facet file) is all it takes for the facet to appear here.
 
-### 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-->`
-```
+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, then load and run each facet in turn.
 
-### status.3 — Resume / next-step guidance
+## Shared rules (referenced by facets)
 
-The status response always includes one of:
+### Standard task-key resolution (0/1/N)
 
-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: "change DEV-6827 to done", "mark PROD-1623 as blocked", "set DEV-9047 in progress", "Mark DEV-6827 as done".
-
-Explicit phrasing (recognized user utterances — normalize each to a `okstra set-work-status` call below):
-- `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:** run the update through the CLI (one Bash call, literal `okstra` token) — never edit `task-manifest.json` by hand:
-
-```bash
-okstra set-work-status <token> <status> --project-root <projectRoot> --json
-```
-
-- `<token>` is a full task-key or a bare task-id. Add `--task-group <group>` to scope a duplicated id, `--note "<note>"` to set `workStatusNote` (flag omitted → any existing note is left untouched).
-- Branch on the stdout JSON: `ok: true` → confirm below. `stage: "ambiguous"` → list `matches[]` (with `_matchedVia`) via a 3-option picker and retry with the chosen full task-key. `stage: "not-found"` → `<TASK-ID> cannot be found.` An invalid `<status>` makes the CLI exit 2 with the allowed-values list — surface it verbatim; nothing was modified.
-
-Confirm in Korean:
-```
-✓ <TASK-ID> workStatus: <previousWorkStatus> → <workStatus>
-✓ task-manifest.json updated
-```
-`<previousWorkStatus>` = `(none)` when the JSON's `previousWorkStatus` is empty.
-
-**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:** the CLI updates `task-manifest.json` only. `discovery/task-catalog.json` may be stale until the next run regenerates it; downstream consumers (e.g. `okstra-schedule-gen`) re-read each manifest directly.
-
----
-
-## history
-
-Trigger phrases: "okstra history", "past runs", "run history", "re-run", "list tasks", "run again", "resume", "continue".
-
-**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 `.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>/.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`. Note: `latestRunManifestPath` is projected from the timeline's latest run, so it is empty when the task has no recorded run yet (timeline absent) — in that case fall back to a `history.2` per-run `runManifestPath`, or ask the user.
-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`, `--antigravity-model`
-   - for `taskType: implementation`: `teamContract.executor.provider` → `--executor <claude|codex|antigravity>` 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/bin/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 it exists: `bash <resume-command-path>`.
-4. If the path is empty or the file is missing: `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/okstra_ctl/ids.py:88` (`slugify_task_segment`, the SSOT; `interactive.sh` consumes it via import). Catalog lookup is case-insensitive; file path assembly uses slugified segments.
-
-Lookup methods (in priority order):
-
-A. **`task-catalog.json` (fast):** read `.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 `.okstra/tasks/<group-segment>/<task-id-segment>/task-manifest.json`, use `latestReportPath` (task-type-agnostic).
-
-C. **`timeline.json` (specific run):** for a specific date or run, read `.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 `.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:30`. Highest seq is latest. Stage-isolated runs (`implementation`, single-stage `final-verification`) keep their reports one level deeper at `runs/<task-type-segment>/stage-<N>/reports/` — scan those subdirectories too; seq is independent per stage. 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 → `This task is not yet complete (currentStatus: <currentStatus>, workStatus: <workStatus>).`
-   - Any signal indicates completion but the file is missing → `Report file does not exist: <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
-
-Match the depth of read to the request — final reports routinely run 300+ lines / 50K+ tokens, so ingesting the whole file just to answer "just the gist" is wasteful:
-
-- **Summary / verdict intent** ("summary", "just the key points", "conclusion", "did it pass?", "verdict"): do **not** read the whole report first. Read the `final-<task-type-segment>-<NNN>.status` sidecar under `runs/<task-type-segment>/status/` (stage-isolated: `runs/<task-type-segment>/stage-<N>/status/`) for the machine verdict, then read only the report's leading summary block (the first "Overall Verdict" / "Executive" / verdict heading and its body) to quote the gist. Offer to read the full report if the user wants detail.
-- **Full-read intent** ("the whole thing", "read it all", "full body"): ingest the resolved report file.
-
-After reading, surface follow-up options:
-
-1. **Proceed to implementation:** based on the report's "Recommended Next Steps" section.
-2. **Additional verification:** to launch a new okstra run with the same task-key, assemble the command through the `history` sub-command — it offers the full option set (base-ref, workers, render-only) and renders a host-correct invocation.
-3. **Check related tasks:** 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: "work time", "elapsed time", "time summary", "duration", "elapsed", "how long did it take", "time analysis".
-
-Aggregate elapsed work time for a task, grouped by **task type** and broken down by **worker** (lead + each worker). The `time-report` CLI reads both data sources (`history/timeline.json` runs + each run's `team-state-*.json` usage blocks) and does **all** aggregation — cross-run sums, CPU-sum vs wall-clock, timestamp parsing, unavailable detection. You only resolve the task-key, call it, and render. **Never recompute durations by hand.**
-
-### time.1 — Resolve the task-key
-
-Same standard as `cost.1`: full task-key → use directly; bare token (task-id or task-group) → `okstra resolve-task-key <token> --project-root <projectRoot> --json` and branch on `matches[]` (0 = not found, 1 = use, N = 3-option picker). If no okstra history exists, say `No okstra history found. Run /okstra-run first.`
-
-### time.2 — Fetch aggregated data
-
-```bash
-okstra time-report <task-key> --project-root <projectRoot> --json
-```
-
-Returns (all durations are **raw milliseconds**):
-- `byTaskType[]` — `{taskType, runs, leadMs, workersMs, cpuSumMs}`, plus `grandTotal`
-- `perWorker` — `{<taskType>: [{workerId, agents[], runs, totalMs, avgMs}]}`; only workers with a nonzero run appear, and `agents[]` lists agent labels that differ from `workerId`
-- `perRunWallClock[]` — `{runTimestamp, taskType, wallClockMs}` (max `endedAt` − min `startedAt` per run)
-- `phaseTimelines[]` — `{runTimestamp, taskType, phases:[{phase, firstAt, wallMsToNext}]}`
-- `unavailable[]` — `{runTimestamp, taskType, reason}` for runs with no Phase-7 durations (never summed into totals)
-
-### time.3 — Render
-
-Convert every `*Ms` to `HH:MM:SS` (zero-pad; never show raw ms). Task types in `byTaskType` are already in chronological (first-appearance) order.
-
-- **By task type** — `| Task type | Runs | CPU sum | Lead | Workers |` from `byTaskType`, plus a `grandTotal` row. `CPU sum` (= Lead + Workers) overlaps because workers run inside the lead's window — it is *not* wall-clock. Surface wall-clock only when the user explicitly asks, from `perRunWallClock`.
-- **Per worker** (per task type) — `| Worker | Runs | Total | Avg/run |` from `perWorker`. Render the worker as bare `workerId` when `agents` is empty, else `workerId (agent1, agent2)`.
-- **Phase breakdown** — "by stage"/"per stage"/"which stage took longest" in okstra most often means the **lifecycle stage (task-type)** view, which the *By task type* table above already answers — lead with that table, do not treat the request as unanswerable. Render the intra-run phase timeline only when the user clearly means within-a-run phases ("which phase", "Phase 1~7", "phase timeline"): one table per run from `phaseTimelines`: `| Phase | Start | Wall to next |` using `firstAt`/`wallMsToNext` (`null` → `--`). When `phaseTimelines` is empty, do **not** headline "not measurable" — the By-task-type table is the stage answer; mention the missing intra-run markers only as a trailing footnote.
-- If `unavailable[]` is non-empty, append a trailing note listing each run with its reason. Never fold them into totals.
-- Show the resolved `<task-key>` in the heading.
-
-```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 |
-| **Grand total**        | 6    | **03:03:06** | 01:05:49 | 01:57:17 |
-
-### Per worker — requirements-discovery
-
-| Worker               | Runs | Total    | Avg/run  |
-|----------------------|------|----------|----------|
-| lead                 | 2    | 00:12:08 | 00:06:04 |
-| claude (sonnet-eval) | 2    | 00:09:12 | 00:04:36 |
-
-> Unavailable: 1 run (implementation / 2026-04-30_03-03-48) — Phase 7 not reached
-```
-
----
-
-## cost
-
-Trigger phrases: "okstra context-cost", "context cost", "context-cost", "context cost (Korean)", "read cost", "artifact cost", "task bundle cost", "agent read cost".
-
-Read-only estimate of how much file/context surface a prepared task bundle asks the lead, analysis workers, and report-writer to absorb. This sub-command does **not** mutate task artifacts.
-
-### cost.1 — Resolve target
-
-Accepted target forms:
-
-1. Full task-key: `<project-id>:<task-group>:<task-id>`.
-2. Bare token — a task-id (e.g. `DEV-9184`) **or** a task-group (e.g. `PROD`).
-3. Task root path, e.g. `<projectRoot>/.okstra/tasks/<group>/<task-id>`.
-
-If the user gives a task root path, run `okstra context-cost <absolute-or-user-provided-path>` directly.
-
-If the user gives a full task-key, run:
-
-```bash
-okstra context-cost <task-key> --project-root <projectRoot>
-```
-
-If the user gives a bare token, resolve it with the shared resolver (SSOT — `scripts/okstra_ctl/resolve_task_key.py` / `okstra_project.resolve_task_reference`). The resolver matches the token as a task-id **and** as a task-group, unioning both (a group expands to its member tasks); each entry carries `_matchedVia` (`"taskId"` | `"taskGroup"`):
+Facets that accept a bare token (a task-id like `DEV-9184` **or** a task-group like `PROD`) resolve it with the shared resolver (SSOT — `scripts/okstra_ctl/resolve_task_key.py` / `okstra_project.resolve_task_reference`). The resolver matches the token as a task-id **and** as a task-group, unioning both (a group expands to its member tasks); each entry carries `_matchedVia` (`"taskId"` | `"taskGroup"`):
 
 ```bash
 okstra resolve-task-key <token> --project-root <projectRoot> --json
 ```
 
-Branch on the stdout JSON `matches[]` — this **standard 0/1/N rule** is referenced by `errors`/`recap` below:
+Branch on the stdout JSON `matches[]`:
 - **0** → report the task cannot be found. Do not guess.
 - **1** → use that entry's `taskKey`.
 - **N** → list the candidate `taskKey`s (with `updatedAt`, and `_matchedVia` so the user sees which came from a task-id vs a task-group) and ask via a 3-option picker (1–2 recommendations + `Enter directly`), then use the chosen `taskKey`.
 
-If the user asks generally ("show me the context cost") and does not name a task:
+### No-task fallback
+
+When a facet needs a task but the user did not name one:
 
 1. Read `.okstra/discovery/task-catalog.json`.
 2. If exactly one task exists, use it.
-3. If multiple tasks exist, show the latest 10 by `updatedAt` and ask which task to measure. Do not guess.
-
-### cost.2 — Run estimator
-
-Use the CLI output as the source of truth:
-
-```bash
-okstra context-cost <resolved-target> --project-root <projectRoot>
-```
-
-Do not re-count files manually unless the CLI fails and the user explicitly asks for manual fallback.
-
-### cost.3 — Render
-
-Render the CLI JSON into the cost.4 template. Each row's Files / Size / ~Tokens come from the matching output block — `totals` (Task bundle, Current run, Legacy timestamp), `instructionSet`, `leadPhase1`, `analysisWorker`, `reportWriter`, `skillAssets`; their exact field names are in the CLI output (do not re-list them here). Format bytes as raw + rounded KB/MB.
-
-Field-specific notes (these affect interpretation, not just display):
-- Analysis worker uses per-worker fields (`bytesPerWorker`, `estimatedTokensPerWorker`). Use `analysisWorker.estimatedReductionPercent` directly for the worker-input reduction — do **not** recompute it from `bytesPerWorker` when `mode == "analysis-packet-primary"` (that value is already the packet-primary cost).
-- `estimatedTokens*` are a static ranking heuristic (~4 ASCII chars/token, non-ASCII ≈ 1 token/char), never billing numbers — actual cost is the token-usage collector's domain.
-- `skillAssets` = the per-run hot-path instruction assets loaded OUTSIDE the task bundle (skill bodies + agent specs), sorted by size — the prompt-diet target.
-
-### cost.4 — Output template
-
-```markdown
-## okstra Context Cost — <task-key>
-
-| Surface | Files | Size | ~Tokens |
-|---|---:|---:|---:|
-| Task bundle | <N> | <bytes> (<human>) | - |
-| Current run | <N> | <bytes> (<human>) | - |
-| Instruction set | <N> | <bytes> (<human>) | <estimatedTokens> |
-| Lead Phase 1 (`<mode>`) | <N> | <bytes> (<human>) | <estimatedTokens> |
-| Analysis worker / worker (`<mode>`) | <N> | <bytes> (<human>) | <estimatedTokensPerWorker> |
-| Report writer synthesis | <N> | <bytes> (<human>) | <estimatedTokens> |
-| Skill assets (hot path) | <N> | <bytes> (<human>) | <estimatedTokens> |
-
-- Current run: `<currentRunPath-or-->`
-- Legacy timestamp artifacts: `<N>`
-- Legacy full worker contract: `<legacyFullContractBytesPerWorker>` bytes (`<human>`) per analysis worker
-- Packet estimate: `<estimatedPacketModeBytesPerWorker>` bytes (`<human>`) per analysis worker
-- Estimated worker-input reduction: `<percent>%`
-
-### Reading
-
-<One or two Korean sentences explaining the main bottleneck and the next likely optimization target.>
-```
-
-Interpretation rules:
-
-- `leadPhase1.mode == "active-run-context"` means the compact lead intake file is present and should be treated as the primary lead read surface.
-- `leadPhase1.mode == "legacy-five-file"` means this task was prepared before active-run-context, or the manifest does not reference it.
-- `analysisWorker.mode == "analysis-packet-primary"` means new workers should read `analysis-packet.md` first and open full source inputs only for evidence checks or missing detail.
-- If `analysisWorker.mode == "full-input-contract"` and `estimatedReductionPercent` is low, the next target is worker prompt/input contract slimming.
-- If `reportWriter.bytes` dominates, the next target is a compact `synthesis-input` artifact.
-- If `skillAssets.estimatedTokens` dominates the per-run fixed cost, the next target is slimming the largest `skillAssets.files[]` entries (prompt diet — perf plan v2 P2), e.g. thin-core + lazy-sidecar split.
-- If `legacyTimestampFileCount` is high, recommend current-view/cold-artifact separation or retention cleanup, not destructive deletion by default.
-
----
-
-## logs
-
-Trigger phrases: "okstra logs", "log status", "log files", "log files", "log size", "log status", "log cleanup", "log cleanup".
-
-Read-only inventory of codex/antigravity 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/antigravity wrappers (`okstra-codex-exec.sh`, `okstra-antigravity-exec.sh`) write a sidecar log next to each prompt history file:
-
-```
-.okstra/tasks/<task-group>/<task-id>/runs/<phase>/prompts/
-  <worker>-worker-prompt-<phase>-<seq>.md    <-- prompt (git-tracked)
-  <worker>-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
-
-```bash
-okstra log-report --project-root <projectRoot> --json
-```
-
-Scans `<projectRoot>/.okstra/tasks/**/runs/*/prompts/*.log` and parses task/phase/worker/seq from each path. Returns (sizes are **raw bytes**, mtimes **epoch seconds**):
-- `topLargest[]` — `{path, sizeBytes, mtimeEpoch, taskKey, taskGroup, taskId, phase, worker, seq}`, size desc (widen with `--top <N>`)
-- `perTask[]` — `{taskKey, fileCount, totalBytes, oldestEpoch, newestEpoch}`, total-size desc
-- `totals` — `{fileCount, totalBytes, taskCount}`
-
-If `totals.fileCount` is 0, report `No wrapper log files found under <projectRoot>` and stop.
-
-### logs.2 — Summary tables
-
-Render from the CLI output (format bytes → KB/MB; epoch → `Nd`/`Nh` relative to now):
-
-**Table A — Top largest logs** (from `topLargest`): `| # | Task | Phase | Worker | Seq | Size | Age | Path |`.
-
-**Table B — Per-task totals** (from `perTask`): `| Task Key | Files | Total Size | Oldest | Newest |`.
-
-**Footer:** `Total: <fileCount> files, <totalBytes→MB> across <taskCount> 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)
-
-# Delete only logs older than 7 days
-find <PROJECT_ROOT>/.okstra/tasks \
-  -type f -path '*/runs/*/prompts/*.log' -mtime +7 -print    # dry-run
-find <PROJECT_ROOT>/.okstra/tasks \
-  -type f -path '*/runs/*/prompts/*.log' -mtime +7 -delete
-
-# Delete only logs older than 30 days
-find <PROJECT_ROOT>/.okstra/tasks \
-  -type f -path '*/runs/*/prompts/*.log' -mtime +30 -print   # dry-run
-find <PROJECT_ROOT>/.okstra/tasks \
-  -type f -path '*/runs/*/prompts/*.log' -mtime +30 -delete
-
-# Delete all logs for a specific task-group (e.g. dev-9388)
-find <PROJECT_ROOT>/.okstra/tasks/dev-9388 \
-  -type f -name '*.log' -print    # dry-run
-find <PROJECT_ROOT>/.okstra/tasks/dev-9388 \
-  -type f -name '*.log' -delete
-
-# Delete all logs for a specific task-id (e.g. dev-9428)
-find <PROJECT_ROOT>/.okstra/tasks/*/dev-9428 \
-  -type f -name '*.log' -print    # dry-run
-find <PROJECT_ROOT>/.okstra/tasks/*/dev-9428 \
-  -type f -name '*.log' -delete
-
-# Delete everything (caution)
-find <PROJECT_ROOT>/.okstra/tasks \
-  -type f -path '*/runs/*/prompts/*.log' -print    # dry-run
-find <PROJECT_ROOT>/.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 `.okstra/`, the user may want to add `.okstra/tasks/**/runs/**/prompts/*.log` to `.gitignore` manually to keep large logs out of git.
-
----
-
-## errors
-
-Trigger phrases: "okstra errors", "error report", "error report (Korean)", "error summary", "gather the errors", "clean up failure logs".
-
-Aggregate a task's okstra-run error logs (`runs/*/logs/errors-*.jsonl`, lead-observed + worker-reported) into a timestamped markdown report and summarize it. This sub-command renders a **read-derived artifact** (a `.md` file) but never mutates task state (`task-manifest.json`, catalog, timeline).
-
-### errors.1 — Resolve target
-
-Accepted target forms (same as `cost`):
-
-1. Full task-key: `<project-id>:<task-group>:<task-id>`.
-2. Bare token (task-id or task-group) — resolve via `okstra resolve-task-key <token> --project-root <projectRoot> --json` and branch on `matches[]` using the standard 0/1/N rule from `cost.1` (0 = not found, 1 = use, N = picker).
-3. Task root path.
-
-If the user asks for an error report without naming a task, apply the same no-task fallback as `cost.1` — list only the placeholder forms and do not ask back: read `.okstra/discovery/task-catalog.json`, use the single task as-is if there is one, and if there are several, list the latest 10 by `updatedAt` as real task-keys and ask (no guessing).
-
-### errors.2 — Run the renderer
-
-Use the CLI output as the source of truth:
-
-```bash
-okstra error-report <resolved-target> --project-root <projectRoot>
-```
-
-For a task-root path, run `okstra error-report <path>` directly. Do not parse the jsonl files by hand unless the CLI fails and the user explicitly asks for a manual fallback.
-
-### errors.3 — Summarize output
-
-Parse the stdout JSON and report:
-
-| Field | Source |
-|---|---|
-| Report file | `reportPath` (project-root-relative `.md`) |
-| Total errors | `totals.errorCount` |
-| Logs (runs) | `totals.runCount` |
-| By errorType | `totals.byErrorType` (tool-failure / cli-failure / contract-violation) |
-| By source | `totals.bySource` (lead-observed / worker-reported) |
-| By phase | `byPhase[]` |
-| By agent | `byAgent[]` |
-| Parse-skipped lines | `parseSkipped` |
-
-- If `reportPath` is empty AND `totals.errorCount == 0`: report `This task has no recorded error logs.` and do not claim a file was written.
-- Otherwise show the `.md` path and offer to read it.
-- If `parseSkipped > 0`, surface it (do not silently hide malformed lines).
-
-### errors — Output template
-
-```markdown
-## okstra Error Report — <task-key>
-
-- Report: `<reportPath-or-->`
-- Total errors: <N> across <runCount> log(s)
-- By type: <tool-failure: a, cli-failure: b, ...>
-- By source: <lead-observed: x, worker-reported: y>
-
-| Phase | Count |
-|---|---:|
-| implementation | 3 |
-
-| Agent | Count |
-|---|---:|
-| codex-worker | 2 |
-
-<If parseSkipped > 0: "⚠ Parse-skipped lines: <N>">
-```
-
----
-
-## error-zip
-
-Trigger phrases: "okstra error-zip", "error zip", "error feedback", "error bundle", "cross-project errors".
-
-Collect and anonymize the okstra run errors (`runs/*/logs/errors-*.jsonl`) of every target project on the machine into the global run-index, then bundle them as a `.zip` (aggregate report + anonymized JSONL). Read-only over every target's `.okstra/`.
-
-### error-zip.1 — Decide the output path (picker)
-
-Read the previous output path from `lastOutputPath` in `~/.okstra/error-zip.json`. If that value exists, present it in a 3-option picker:
-
-1. (previous path exists) reuse `<lastOutputPath>` — recommended, first option.
-   (no previous path) propose the default path `~/okstra-error-feedback-<YYYY-MM-DD>.zip` — recommended.
-2. Enter directly (always the last option).
-
-Read `~/.okstra/error-zip.json` directly with Read (if absent, treat it as no previous path).
-
-### error-zip.2 — Run the renderer
-
-```bash
-okstra error-zip --out <resolved-path>
-```
-
-### error-zip.3 — Report the summary
-
-Parse the stdout JSON and report:
-
-| Field | Source |
-|---|---|
-| Output zip | `outPath` |
-| Total errors | `errorCount` |
-| Logs (runs) | `runCount` |
-| Unreachable runs | `unreachableRuns` |
-| Cluster count | `clusterCount` |
-| Project count | `projectCount` |
-
-- If `unreachableRuns > 0`, surface it (no silent omission).
-- End with the next step: "To fix okstra itself with this zip, build a brief with the error-feedback variant of `/okstra-brief-gen`, then run `okstra-run --task-type error-analysis` in the okstra repo."
-
----
-
-## recap
-
-Trigger phrases: "okstra recap", "recap", "work summary", "summarize this task", "before/after summary", "explain this work", "task question".
-
-On top of the `.okstra` artifacts accumulated for a single task-id, (a) produce a before/after summary and (b) answer free-form questions about that work. By default it reads only the `.okstra/` subtree (artifact mode). It expands to code mode only when the user explicitly asks to look at the code changes too. This sub-command performs only the `recap/recap-log.jsonl` append and the `notes/` note authoring (recap.5); it never mutates `task-manifest.json` / catalog / timeline.
-
-### recap.1 — Resolve target
-
-The same three forms as `cost` / `errors`: ① full task-key, ② bare token (task-id or task-group → `okstra resolve-task-key <token> --project-root <projectRoot> --json`; the standard 0/1/N branch from `cost.1`), ③ task-root path.
-
-If the user asks for a recap without naming a task (e.g. "summarize this work"), apply the `cost.1` no-task fallback as-is — do not list only a placeholder form like `<task-group>` and ask back; read `.okstra/discovery/task-catalog.json`, use the single task as-is if there is one, and if there are several, list the latest 10 by `updatedAt` as real task-keys and ask (no guessing).
-
-### recap.2 — Assemble the before/after summary
-
-Use the CLI output as the source of truth:
-
-```bash
-okstra recap assemble <resolved-target> --project-root <projectRoot>
-```
-
-Parse the stdout JSON (`{taskKey, runCount, transitions[], latestPhaseStates}`) and narrate the per-run before/after transitions. For each `transitions[]` entry, show `fromPhase → toPhase` (previous run currentPhase → this run currentPhase), `status`, `lastCompletedPhase`, `nextRecommendedPhase`, and `reportPath` in chronological order. If `runCount == 0`, answer only "This task has no recorded runs." and do not claim to have read any file.
-
-For a run that has a `reportPath`, read that final-report to enrich the summary only when the user wants a deeper one (do not read them all automatically).
-
-### recap.3 — Free-form Q&A loop
-
-After the summary output, take the user's free-form questions.
-
-- **artifact mode (default)**: answer only from `.okstra/` artifacts (timeline, task-manifest, that run's final-report). Every factual claim is accompanied by a `path:line` citation to the `.okstra` file.
-- **code mode (opt-in)**: only when the user **explicitly asks** — "look at the code changes / the diff too" — additionally read `git diff` · `git log` from that task's worktree/branch and answer at the code level. Entering recap never by itself switches to code mode.
-
-### recap.4 — Persist each turn
-
-Log one summary and each Q&A answer (append-only):
-
-```bash
-okstra recap record <resolved-target> --project-root <projectRoot> \
-  --kind <summary|qa> --mode <artifact|code> \
-  --question "<question or omit>" --answer "<one or two line summary>" \
-  --citation "<path:line>" --citation "<path:line>"
-```
-
-Put a one-or-two-line summary in `--answer`, not the full answer transcript. If there are multiple citations, repeat `--citation`. Do not silently swallow a recording failure (abnormal exit) — tell the user.
-
-### recap — Output template
-
-```markdown
-## okstra Recap — <task-key>
-
-Before/after summary (runs: <N>):
-
-| # | when | task-type | from → to | status | next |
-|---|---|---|---|---|---|
-| 1 | <ts> | requirements-discovery | (start) → requirements-discovery | done | error-analysis |
-
-<Free-form questions follow. To include code changes, ask "also show me the diff".>
-```
-
-### recap.5 — Agent-authored notes (`notes/`)
-
-Leave something in `notes/` only when, during recap, you produced an artifact **for the okstra task** — verification evidence, a design/decision draft, an analysis note — that may serve as grounding for future runs, and whose content is **neither a rendered report nor a user decision**.
-
-**Route by ownership.** First determine which of the following the thing you are about to write belongs to:
-
-| Content | Lane (path) | Author |
-|---|---|---|
-| final report body | `runs/<type>/reports/*.md` (rendered from `*.data.json`) | okstra renderer — never hand-edit |
-| user's answer to a clarification | `runs/<type>/user-responses/*.md` (`created-by: user`) | user only |
-| finalized ADR | `.okstra/decisions/NNNN-*.md` | promoted / managed |
-| **Agent evidence / design draft / analysis** | **`.okstra/tasks/<group>/<id>/notes/`** | you (the AI) |
-
-If it is **your own grounding/draft** — not a rendered artifact, not a user decision — it goes to `notes/`. Do not hand-stamp the note; write it via the CLI — code guarantees the path/frontmatter/date and prints the argument to pass into the next run:
-
-```bash
-okstra recap note <resolved-target> --project-root <projectRoot> \
-  --kind <verification-evidence|decision-draft|analysis-note> \
-  --slug <short-topic-slug> \
-  --purpose "<one line — what it is and which run/decision it feeds>" \
-  --scope-note "<one line — what it is NOT, e.g. not a user decision on C-00x>" \
-  --body-file <note-body markdown path>
-```
-
-Write the body to the scratchpad as markdown first, then pass it with `--body-file` (if short, an inline `--body "<md>"` also works). The CLI creates `.okstra/tasks/<group>/<id>/notes/<slug>-<YYYY-MM-DD>.md` and returns `notePath` and `clarificationResponseArg` as stdout JSON.
-
-**self-check rules (there is no validator, so you keep them yourself):**
-
-1. **Do not hand-edit a rendered report** (`*.md` / `*.data.json` / `*.html` under `runs/*/reports/`). Because it is regenerated from `data.json`, an edit is overwritten and diverges from the SSOT. Write findings to `notes/` instead.
-2. **Do not author a `user-responses/` file or apply `created-by: user`.** That is the user's decision, and writing it for them forges a decision the user never made. If your evidence supports a particular answer, write that in `notes/` and leave the decision to the user. The one exception is the echo-back confirmation flow of the `okstra-user-response` skill — there the user makes the decision in-session and the CLI is merely a transcription channel, so recording a `created-by: user` sidecar with `write` is legitimate. This exception holds only after the user has explicitly confirmed "correct", and only for verbatim input.
-3. **Do not write to okstra-managed directories** (`runs/`, `instruction-set/`, `history/`, `recap/`, `.okstra/decisions/`). `notes/` is the only agent-owned lane. `recap/recap-log.jsonl` is the exception — write it, but not by hand; only via the `okstra recap record` CLI.
-4. **`notes/` is inert to okstra** — no run reads it automatically. After writing, relay the `clarificationResponseArg` the CLI printed (e.g. `--clarification-response <notePath>`) to the user verbatim, telling them it only takes effect when the next run is executed with that argument.
-
-**Guardrail:** `.okstra/` is gitignored — treat `notes/` as local scratch and never `git add` it. Creating a new note is easy to undo (delete the file), so always prefer it over editing a generated or user-owned file.
-
----
+3. If multiple tasks exist, show the latest 10 by `updatedAt` as real task-keys and ask which one. Do not guess, and do not answer with placeholder forms only.
 
 ## Output Rules (shared)