okstra 0.124.0 → 0.125.1

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`.

package/runtime/templates/worker-prompt-preamble.md

@@ -43,9 +43,17 @@ Different recipients need different files. Do NOT include `final-report-template
 
 ## Error reporting (all workers)
 
-If any tool call you make (Bash, Read, Edit, MCP, etc.) returns a non-zero exit code, raises an exception, or otherwise fails its intended effect, append a single entry to your worker errors sidecar at the absolute path the lead provided as `**Errors sidecar path:** <abs-path>`.
+Record a tool call only when its failure **blocked the step you intended** — a test you needed to run did not start, a file you needed to read was missing, a config resolved against the wrong tree, an edit was rejected. When that happens, append a single entry to your worker errors sidecar at the absolute path the lead provided as `**Errors sidecar path:** <abs-path>`.
 
-If the sidecar file does not exist, create it with `{"schemaVersion": 1, "errors": []}` then append.
+A non-zero exit code is NOT by itself a failure to record. Many tools use non-zero to report a normal, expected result. Do **NOT** record an entry when:
+
+- a search/probe tool (`rg`, `grep`, `find`, `ls`, `test`, `git check-ignore`) exits non-zero solely because it found **no matches**, and you proceed unaffected;
+- you probe an **optional / expected-absent** path (`graphify-out/`, `.project-docs/`, `.scratch/`, an optional lint config, a review pack) and it is absent — detecting absence was the point of the probe;
+- output was truncated but you re-ran and read the content end-to-end.
+
+The test: if the non-zero exit changed nothing about what you could do next, it is a normal result, not a `tool-failure`. When in doubt about whether a failure blocked you, record it — under-recording a real blocker is worse than one noisy entry. These benign non-zero exits are the single largest source of error-log noise; keeping them out is what makes the log a signal.
+
+If the sidecar file does not exist and you have a real entry to record, create it with `{"schemaVersion": 1, "errors": []}` then append.
 
 ### Entry schema
 
@@ -109,7 +117,13 @@ For the **improvement-discovery phase** specifically, the dispatched prompt MUST
 
 - `**Phase 1.5 Grilling Log:** <absolute-path>` — the lead's Phase 1.5 reflect-back log (`<RUN_DIR>/state/phase-1.5-grilling.md`, written before dispatch). Its `Resolved scope` / `Resolved lenses` blocks are the authoritative scope and lens definition for this run. Read the file at this absolute path; do NOT re-derive it from `<RUN_DIR>`, and do NOT re-interpret the brief's raw `scan-scope` / `priority-lenses`. The presence of this anchor is itself the signal that this is an improvement-discovery run — no separate task-type detection is required.
 
-When a worker reads any project-relative path from the prompt, it MUST resolve it against `Project Root` (e.g. `<Project Root>/<Result Path>`) — never use bare relative paths that depend on cwd.
+### Path anchoring (BLOCKING — the single largest source of worker tool-failures)
+
+Every `.okstra/...` path is anchored at `**Project Root:**`, **never** at your cwd. When your run has a worktree (`**Worktree:**` is present), your cwd is that worktree — and the stage/task worktree does **not** contain the project's `.okstra/` directory. So a bare `Read`/`cat .okstra/tasks/...` from cwd resolves inside the worktree and fails "no such file". This is the same trap whether the path came from the prompt, a manifest field, a prior report's citation, or your own reasoning.
+
+- Resolve any project-relative path (`.okstra/...`, `<Result Path>`, `<Prompt History Path>`, a prior-report `path:line` citation) against `**Project Root:**`: `<Project Root>/.okstra/...`. Never use the bare relative form.
+- Mutating build/test commands still run from the worktree cwd (`cd <Worktree> && ...`) — but reads of okstra artifacts (`.okstra/**`) always go through `<Project Root>`, even while cwd is the worktree.
+- If a `.okstra/...` read fails "no such file / does not exist in the worktree", do not retry the same relative path — re-anchor it to `<Project Root>` and read the absolute path.
 
 ---