okstra 0.124.0 → 0.125.0

package/runtime/skills/okstra-inspect/facets/status.md

@@ -0,0 +1,145 @@
+# okstra-inspect facet — status
+
+Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.
+
+## 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>
+
+- 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: "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 (the block below shows the message shape only — render the actual confirmation text 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.

package/runtime/skills/okstra-inspect/facets/time.md

@@ -0,0 +1,56 @@
+# okstra-inspect facet — time
+
+Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.
+
+## 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
+
+Apply the standard task-key resolution rule from `SKILL.md` (core): full task-key → use directly; bare token → the resolver CLI and the 0/1/N branch. 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
+```

package/runtime/skills/okstra-pr-gen/SKILL.md

@@ -33,7 +33,7 @@ Present a 3-option picker (`AskUserQuestion`):
 
 1. `Generate PR` — generate a PR body from a branch diff.
 2. `Register template` — save a new PR body template.
-3. `Enter manually` — always the last option (okstra picker convention).
+3. `Enter directly` — always the last option (okstra picker convention).
 
 ## Mode A — Generate PR
 
@@ -44,7 +44,7 @@ okstra pr template list --json
 ```
 
 - If `templates` is non-empty, present a picker: 1–2 recommended templates from
-  the list, plus `Default template` (the bundled default), plus `Enter manually`
+  the list, plus `Default template` (the bundled default), plus `Enter directly`
   last.
 - If empty, tell the user the bundled default template will be used.
 
@@ -56,7 +56,7 @@ Carry the chosen template name as `<template>` (`default` for the bundled one).
 okstra pr branches --json
 ```
 
-Present a 3-option base picker from `recommended` (top entries) plus `Enter manually`
+Present a 3-option base picker from `recommended` (top entries) plus `Enter directly`
 last. Carry the choice as `<base>`.
 
 ### A3. Build the generation bundle and fill the template

package/runtime/templates/project-docs/task-index.template.md

@@ -69,4 +69,4 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Notes
 
-- 이 문서는 사람이 빠르게 훑어보기 위한 요약입니다. 정본·상세 metadata 는 `task-manifest.json` 을 참조하세요.
+- This document is a summary for humans to skim quickly. For the canonical, detailed metadata, refer to `task-manifest.json`.