okstra 0.123.0 → 0.124.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/README.md +1 -0
  2. package/docs/architecture/storage-model.md +1 -1
  3. package/docs/architecture.md +11 -1
  4. package/docs/cli.md +2 -0
  5. package/docs/for-ai/README.md +41 -35
  6. package/docs/for-ai/skills/okstra-brief-gen.md +105 -105
  7. package/docs/for-ai/skills/okstra-container-build.md +61 -61
  8. package/docs/for-ai/skills/okstra-graphify.md +64 -0
  9. package/docs/for-ai/skills/okstra-inspect.md +86 -86
  10. package/docs/for-ai/skills/okstra-manager.md +32 -32
  11. package/docs/for-ai/skills/okstra-memory.md +49 -50
  12. package/docs/for-ai/skills/okstra-pr-gen.md +48 -0
  13. package/docs/for-ai/skills/okstra-rollup.md +58 -58
  14. package/docs/for-ai/skills/okstra-run.md +95 -95
  15. package/docs/for-ai/skills/okstra-schedule-gen.md +106 -106
  16. package/docs/for-ai/skills/okstra-setup.md +63 -64
  17. package/docs/for-ai/skills/okstra-user-response.md +48 -0
  18. package/docs/performance-improvement-plan-v2.md +4 -4
  19. package/docs/pr-template-usage.md +34 -34
  20. package/docs/project-structure-overview.md +91 -70
  21. package/docs/task-process/README.md +33 -33
  22. package/docs/task-process/common-flow.md +26 -26
  23. package/docs/task-process/error-analysis.md +20 -21
  24. package/docs/task-process/final-verification.md +41 -41
  25. package/docs/task-process/implementation-planning.md +33 -33
  26. package/docs/task-process/implementation.md +38 -38
  27. package/docs/task-process/release-handoff.md +46 -46
  28. package/docs/task-process/requirements-discovery.md +22 -23
  29. package/package.json +1 -1
  30. package/runtime/BUILD.json +2 -2
  31. package/runtime/agents/workers/antigravity-worker.md +4 -4
  32. package/runtime/agents/workers/claude-worker.md +2 -2
  33. package/runtime/agents/workers/codex-worker.md +4 -4
  34. package/runtime/agents/workers/report-writer-worker.md +4 -4
  35. package/runtime/prompts/coding-preflight/frameworks/node-server.md +1 -1
  36. package/runtime/prompts/launch.template.md +1 -1
  37. package/runtime/prompts/lead/convergence.md +10 -20
  38. package/runtime/prompts/lead/okstra-lead-contract.md +14 -16
  39. package/runtime/prompts/lead/plan-body-verification.md +18 -18
  40. package/runtime/prompts/lead/report-writer.md +43 -44
  41. package/runtime/prompts/lead/team-contract.md +11 -122
  42. package/runtime/prompts/profiles/_common-contract.md +15 -22
  43. package/runtime/prompts/profiles/_implementation-deliverable.md +1 -1
  44. package/runtime/prompts/profiles/_implementation-executor.md +1 -1
  45. package/runtime/prompts/profiles/_implementation-verifier.md +2 -2
  46. package/runtime/prompts/profiles/error-analysis.md +2 -2
  47. package/runtime/prompts/profiles/final-verification.md +1 -1
  48. package/runtime/prompts/profiles/implementation-planning.md +13 -13
  49. package/runtime/prompts/profiles/implementation.md +1 -1
  50. package/runtime/prompts/profiles/improvement-discovery.md +1 -1
  51. package/runtime/prompts/profiles/release-handoff.md +3 -3
  52. package/runtime/prompts/profiles/requirements-discovery.md +18 -18
  53. package/runtime/skills/_fragments/bash-invocation-rule.md +1 -0
  54. package/runtime/skills/_fragments/preflight-outdated-cli.md +1 -0
  55. package/runtime/skills/_fragments/python-bootstrap-note.md +1 -0
  56. package/runtime/skills/okstra-brief-gen/SKILL.md +117 -122
  57. package/runtime/skills/okstra-container-build/SKILL.md +24 -14
  58. package/runtime/skills/okstra-graphify/SKILL.md +12 -4
  59. package/runtime/skills/okstra-inspect/SKILL.md +104 -98
  60. package/runtime/skills/okstra-manager/SKILL.md +1 -1
  61. package/runtime/skills/okstra-memory/SKILL.md +3 -3
  62. package/runtime/skills/okstra-rollup/SKILL.md +12 -6
  63. package/runtime/skills/okstra-run/SKILL.md +49 -88
  64. package/runtime/skills/okstra-schedule-gen/SKILL.md +36 -30
  65. package/runtime/skills/okstra-setup/SKILL.md +1 -1
  66. package/runtime/skills/okstra-setup/references/project-config.md +17 -16
  67. package/runtime/skills/okstra-usage/SKILL.md +5 -2
  68. package/runtime/skills/okstra-user-response/SKILL.md +15 -3
  69. package/runtime/templates/prd/brief.template.md +92 -92
  70. package/runtime/templates/reports/error-analysis-input.template.md +1 -1
  71. package/runtime/templates/reports/fan-out-unit.template.md +6 -6
  72. package/runtime/templates/reports/final-verification-input.template.md +6 -6
  73. package/runtime/templates/reports/implementation-input.template.md +1 -1
  74. package/runtime/templates/reports/implementation-planning-input.template.md +1 -1
  75. package/runtime/templates/reports/improvement-discovery-input.template.md +1 -1
  76. package/runtime/templates/reports/quick-input.template.md +1 -1
  77. package/runtime/templates/reports/release-handoff-input.template.md +1 -1
  78. package/runtime/templates/reports/schedule.template.md +22 -22
  79. package/runtime/templates/reports/task-brief.template.md +3 -3
  80. package/runtime/templates/reports/user-response.template.md +20 -20
  81. package/runtime/templates/worker-prompt-preamble.md +111 -13
  82. package/runtime/validators/validate-schedule.py +1 -1
package/docs/for-ai/skills/okstra-pr-gen.md ADDED
@@ -0,0 +1,48 @@
1
+ # okstra-pr-gen AI Manual
2
+
3
+ ## Sources
4
+
5
+ - Skill source: [`skills/okstra-pr-gen/SKILL.md`](../../../skills/okstra-pr-gen/SKILL.md)
6
+ - Template core (CLI): [`scripts/okstra_ctl/pr_template.py`](../../../scripts/okstra_ctl/pr_template.py)
7
+ - Node wrapper: [`src/commands/pr/pr.mjs`](../../../src/commands/pr/pr.mjs)
8
+ - Bundled default template: [`src/commands/pr/default.md`](../../../src/commands/pr/default.md)
9
+
10
+ ## Purpose
11
+
12
+ `okstra-pr-gen` registers PR body templates and generates PR descriptions from a branch diff. Templates live in the user home at `~/.okstra/template/pr/`. This skill is **global** — it does not require `<PROJECT_ROOT>/.okstra/project.json`. PR generation additionally requires the current directory to be a git repository.
13
+
14
+ ## Check CLI availability
15
+
16
+ A separate Bash call with a literal leading token:
17
+
18
+ ```bash
19
+ okstra pr --help
20
+ ```
21
+
22
+ If `okstra` is not on PATH: `okstra not installed — run npx okstra@latest install once, then retry`. Every Bash command starts with the literal `okstra` token and passes literal arguments (do not wrap it in `$(...)`/leading `VAR=`/`if`/`eval`/`||`/`&&`).
23
+
24
+ ## Pick the mode (always first)
25
+
26
+ A 3-option picker via `AskUserQuestion`:
27
+
28
+ 1. `Generate PR` — generate a PR body from a branch diff
29
+ 2. `Register template` — save a new PR body template
30
+ 3. `Enter manually` — always last (okstra picker convention)
31
+
32
+ ## Mode A — Generate PR
33
+
34
+ 1. Pick a template: `okstra pr template list --json`. If empty, use the bundled default. Carry the chosen name as `<template>` (`default` for the bundled one).
35
+ 2. Pick the base branch: `okstra pr branches --json`. 3-option from the top `recommended` entries plus `Enter manually`. Carry the choice as `<base>`.
36
+ 3. Generation bundle: `okstra pr gen --base <base> --template <template> --json` → `{base, currentBranch, templateName, template, commits, diffStat}`. Then **read the real diff honestly** (SSOT): `git diff <base>...HEAD` (large diffs section by section). Fill the placeholders from the diff and commits, describing **only actual changes**. Mark a checklist box `[x]` only when the diff supports it (tests touched → tests box, docs touched → docs box). If `commits`/`diffStat` are empty, say there is nothing to describe and stop. **Never append AI trailers/footers.**
37
+ 4. Output and offer to create the PR: print the filled PR body as a single fenced markdown block. Ask whether to open a PR. **Only on an explicit yes**: write the body to a temp file and run `gh pr create --base <base> --title "<title>" --body-file <path>`. If `gh` is missing or unauthenticated (`gh auth status` fails), leave the text in chat and give manual-creation guidance. **No push/PR creation without the user's confirmation.**
38
+
39
+ ## Mode B — Register template
40
+
41
+ 1. Template name (`AskUserQuestion`, free text) — must match `^[A-Za-z0-9._-]+$`, otherwise re-ask.
42
+ 2. body — pasted text or an absolute path.
43
+ 3. Save: `okstra pr template add --name <name> --file <abs-path>` (or, for pasted text, `--content "<body>"`). Add `--yes` only when the user confirmed overwriting a same-named template. Report the saved path (`saved: ...`).
44
+
45
+ ## Output Rules
46
+
47
+ - Not read-side — write actions (PR creation, template saving) happen only after the user's explicit confirmation.
48
+ - Do not invent changes not in the diff. Stop if commit/diffStat is empty.
package/docs/for-ai/skills/okstra-rollup.md CHANGED
@@ -1,82 +1,82 @@
1
1
  # okstra-rollup AI Manual
2
2
 
3
- ## 원천
3
+ ## Source
4
4
 
5
- - 스킬 원문: [`skills/okstra-rollup/SKILL.md`](../../../skills/okstra-rollup/SKILL.md)
6
- - 집계 코어(CLI): [`scripts/okstra_ctl/rollup.py`](../../../scripts/okstra_ctl/rollup.py)
7
- - Node 래퍼: [`src/commands/inspect/rollup.mjs`](../../../src/commands/inspect/rollup.mjs)
8
- - 재사용하는 단일-task 집계기: [`scripts/okstra_ctl/time_report.py`](../../../scripts/okstra_ctl/time_report.py), [`scripts/okstra_ctl/error_log_core.py`](../../../scripts/okstra_ctl/error_log_core.py)
9
- - catalog 열거 헬퍼: [`scripts/okstra_project/state.py`](../../../scripts/okstra_project/state.py) (`list_project_tasks`)
10
- - 단위 테스트: [`tests/inspect/test_okstra_rollup.py`](../../../tests/inspect/test_okstra_rollup.py)
5
+ - Skill source: [`skills/okstra-rollup/SKILL.md`](../../../skills/okstra-rollup/SKILL.md)
6
+ - aggregation core (CLI): [`scripts/okstra_ctl/rollup.py`](../../../scripts/okstra_ctl/rollup.py)
7
+ - Node wrapper: [`src/commands/inspect/rollup.mjs`](../../../src/commands/inspect/rollup.mjs)
8
+ - reused single-task aggregators: [`scripts/okstra_ctl/time_report.py`](../../../scripts/okstra_ctl/time_report.py), [`scripts/okstra_ctl/error_log_core.py`](../../../scripts/okstra_ctl/error_log_core.py)
9
+ - catalog enumeration helper: [`scripts/okstra_project/state.py`](../../../scripts/okstra_project/state.py) (`list_project_tasks`)
10
+ - unit tests: [`tests/inspect/test_okstra_rollup.py`](../../../tests/inspect/test_okstra_rollup.py)
11
11
 
12
- ## 목적
12
+ ## Purpose
13
13
 
14
- `okstra-rollup`은 **여러 task의 run 결과를 한꺼번에 모아 요약**한다. 단일 task를 보는 `okstra-inspect`와 대비되는 task 횡단(cross-task) read-side 레이어다.
14
+ `okstra-rollup` **collects and summarizes the run results of multiple tasks at once**. It is a cross-task read-side layer, in contrast to `okstra-inspect` which looks at a single task.
15
15
 
16
- - 입력 범위: 한 task-group, 또는 `--task-group`을 생략하면 프로젝트 전체 catalog.
17
- - deterministic 집계(개수·시간 합·에러 합·상태/카테고리/phase 분포)는 `okstra rollup` CLI가 전담한다. 스킬은 그 표를 렌더하고, 각 task의 report 본문을 읽어 **task 횡단 종합 요약(digest)**을 작성한다.
18
- - 설계 원칙: 집계 손계산은 LLM이 틀리기 쉬우므로 CLI(SSOT)로 내리고, 자연어 종합만 LLM이 맡는다. `okstra-inspect time`이 "절대 손으로 시간을 재합산하지 말 것"이라 못 박는 것과 같은 분업이다.
16
+ - Input scope: one task-group, or the whole-project catalog when `--task-group` is omitted.
17
+ - Deterministic aggregation (counts, time sums, error sums, status/category/phase distributions) is handled entirely by the `okstra rollup` CLI. The skill renders that table and reads each task's report body to write a **cross-task synthesis (digest)**.
18
+ - Design principle: hand-computed aggregation is error-prone for an LLM, so it is pushed to the CLI (SSOT), and only the natural-language synthesis is left to the LLM. This is the same division of labor as `okstra-inspect time`, which insists on "never re-sum the time by hand".
19
19
 
20
- 이 스킬은 read-only다. task 산출물을 mutate 하지 않는다.
20
+ This skill is read-only. It does not mutate task artifacts.
21
21
 
22
- ## 사용 조건
22
+ ## When to use
23
23
 
24
- 사용한다:
24
+ Use it when:
25
25
 
26
- - 사용자가 "롤업", "task-group 요약", "그룹 단위 리포트", "여러 task 결과 모아", "전체 task 현황 요약", "run 결과 한꺼번에 정리"를 요청한다.
27
- - 한 task가 아니라 **여러 task**를 가로질러 보고 싶을 때.
26
+ - The user asks for "rollup", "task-group summary", "group-level report", "collect multiple task results", "whole-project task status summary", "run results all at once".
27
+ - You want to look across **multiple tasks** rather than a single one.
28
28
 
29
- 사용하지 않는다:
29
+ Do not use it when:
30
30
 
31
- - 단일 task의 report/시간/에러/recap → `okstra-inspect` (report / time / errors / recap facet).
32
- - 미래 작업 계획표(non-done task의 클라이언트용 일정) → `okstra-schedule-gen`. rollup은 과거 run 결과를 모으는 **회고형**이고, schedule은 앞으로의 계획을 짜는 **전망형**이다.
33
- - 실제 phase 실행 → `okstra-run`.
31
+ - A single task's report/time/errors/recap → `okstra-inspect` (report / time / errors / recap facet).
32
+ - A forward-looking work plan (a client-facing schedule of non-done tasks) → `okstra-schedule-gen`. rollup is **retrospective**, collecting past run results; schedule is **forward-looking**, planning future work.
33
+ - Actual phase execution → `okstra-run`.
34
34
 
35
35
  ## Preflight
36
36
 
37
- 리터럴 `okstra` 토큰으로 시작하는 단일 Bash 호출(`if`/`eval`/`$(...)`/`VAR=`/`||`/`&&`/`npx` fallback으로 감싸지 않는다):
37
+ A single Bash call starting with the literal `okstra` token (not wrapped in `if`/`eval`/`$(...)`/`VAR=`/`||`/`&&`/`npx` fallback):
38
38
 
39
39
  ```bash
40
40
  okstra preflight --runtime claude-code --json
41
41
  ```
42
42
 
43
- `ok:false` → `/okstra-setup` 안내 후 멈춘다. `ok:true`면 `projectRoot`를 리터럴 문자열로 들고 다음 단계로 간다.
43
+ `ok:false` → point to `/okstra-setup` and stop. If `ok:true`, carry `projectRoot` as a literal string and proceed.
44
44
 
45
- ## scope 해석
45
+ ## scope resolution
46
46
 
47
- - 사용자가 task-group을 지목("alpha 그룹 요약") → `--task-group <group>`.
48
- - "전체 task"/"프로젝트 전체"/범위 미지정 → `--task-group` 생략(전체 catalog).
49
- - 진짜 모호하면 한 번만 묻는다: 한 task-group인지 프로젝트 전체인지. 특정 그룹을 임의로 추측하지 않는다.
47
+ - The user named a task-group ("summarize the alpha group") → `--task-group <group>`.
48
+ - "all tasks" / "the whole project" / no scope named → omit `--task-group` (whole catalog).
49
+ - If genuinely ambiguous, ask once: one task-group or the whole project? Do not silently guess a specific group.
50
50
 
51
- ## CLI 호출
51
+ ## CLI call
52
52
 
53
53
  ```bash
54
54
  okstra rollup --task-group <group> --project-root <projectRoot> --json
55
55
  ```
56
56
 
57
- 전체 프로젝트면 `--task-group`을 뺀다. 출력은 항상 JSON이며 **모든 시간은 raw 밀리초**다.
57
+ For the whole project, drop `--task-group`. The output is always JSON, and **all times are raw milliseconds**.
58
58
 
59
- ## 출력 해석
59
+ ## Interpreting the output
60
60
 
61
- 최상위:
61
+ Top level:
62
62
 
63
- - `taskGroup` — 범위(`null`이면 프로젝트 전체), `taskCount` — task 수.
64
- - `tasks[]` — task 1개당: `taskKey, taskGroup, taskId, taskType, workCategory, workStatus, currentPhase, currentPhaseState, nextRecommendedPhase, latestRunStatus, updatedAt, reportPath, runCount, cpuSumMs, wallClockMs, errorCount`.
65
- - `totals` — `runs, cpuSumMs, wallClockMs, errors`, 그리고 `byWorkStatus` / `byWorkCategory` / `byCurrentPhase` / `byTaskType` (각각 `{값: 개수}` 맵).
63
+ - `taskGroup` — the scope (`null` = whole project), `taskCount` — number of tasks.
64
+ - `tasks[]` — per task: `taskKey, taskGroup, taskId, taskType, workCategory, workStatus, currentPhase, currentPhaseState, nextRecommendedPhase, latestRunStatus, updatedAt, reportPath, runCount, cpuSumMs, wallClockMs, errorCount`.
65
+ - `totals` — `runs, cpuSumMs, wallClockMs, errors`, plus `byWorkStatus` / `byWorkCategory` / `byCurrentPhase` / `byTaskType` (each a `{value: count}` map).
66
66
 
67
- 수치 의미(반드시 지킬 것):
67
+ Numeric meanings (must observe):
68
68
 
69
- - `runCount`는 timeline의 **전체 run 수**다. `cpuSumMs`/`wallClockMs`는 Phase 7 usage에 도달한 run만 반영하므로 `runCount > 0`이어도 `0`일 수 있다.
70
- - `cpuSumMs`는 lead + worker가 겹쳐 도는 **CPU 합**이지 wall-clock이 아니다. 라벨을 "CPU"로 쓰고, wall-clock은 사용자가 명시적으로 물을 때만 `wallClockMs`로 보여준다.
71
- - `reportPath`는 프로젝트 상대경로이며 비어 있을 수 있다(아직 report가 없는 task).
72
- - `taskCount`가 `0`이면 해당 범위에 okstra task가 없다고 말하고 멈춘다.
69
+ - `runCount` is the **total number of runs** in the timeline. `cpuSumMs`/`wallClockMs` reflect only runs that reached Phase 7 usage, so they can be `0` even when `runCount > 0`.
70
+ - `cpuSumMs` is the **CPU sum** of the overlapping lead + workers, not wall-clock. Label it "CPU", and show wall-clock as `wallClockMs` only when the user explicitly asks.
71
+ - `reportPath` is project-relative and may be empty (a task with no report yet).
72
+ - If `taskCount` is `0`, say there are no okstra tasks in that scope and stop.
73
73
 
74
- ## 렌더
74
+ ## Render
75
75
 
76
- 모든 `*Ms`는 `HH:MM:SS`로 변환한다(zero-pad, raw ms 절대 노출 금지 — `okstra-inspect time`과 같은 규칙). task는 `updatedAt` 내림차순 정렬.
76
+ Convert every `*Ms` to `HH:MM:SS` (zero-pad; never expose raw ms — the same rule as `okstra-inspect time`). Sort tasks by `updatedAt` descending.
77
77
 
78
78
  ```markdown
79
- ## okstra Rollup — <task-group 또는 "whole project"> (<taskCount> tasks)
79
+ ## okstra Rollup — <task-group or "whole project"> (<taskCount> tasks)
80
80
 
81
81
  | Task | Category | workStatus | Phase | Runs | CPU | Errors | Report |
82
82
  |------|----------|------------|-------|------|-----|--------|--------|
@@ -87,26 +87,26 @@ okstra rollup --task-group <group> --project-root <projectRoot> --json
87
87
  **workStatus:** done 1 · in-progress 1 **category:** bugfix 1 · feature 1
88
88
  ```
89
89
 
90
- - `Report` 열: `reportPath`가 있으면 `✓`, 없으면 `—`.
91
- - 상태/카테고리/phase 줄은 `totals`의 tally 맵을 **그대로** 옮긴다. `tasks[]` 배열을 직접 세지 않는다(집계는 CLI가 SSOT).
90
+ - `Report` column: `✓` when `reportPath` is present, `—` when not.
91
+ - Build the status/category/phase lines from the `totals` tally maps **verbatim**. Do not count the `tasks[]` array yourself (the CLI is the SSOT for aggregation).
92
92
 
93
- ## digest 작성 (요약 — 스킬의 핵심 가치)
93
+ ## Writing the digest (the summary — the skill's core value)
94
94
 
95
- 사용자가 "요약"/"정리"/"summarize"/"digest"를 요청한 경우(일반적인 경우):
95
+ When the user asks to "summarize"/"organize"/"summarize"/"digest" (the common case):
96
96
 
97
- 1. `reportPath`가 비어 있지 않고 `<projectRoot>/<reportPath>` 파일이 실제로 존재하는 task마다 report를 읽고, **무엇을 달성했고 권장 다음 단계가 무엇인지** 1~2줄로 요약한다.
98
- 2. per-task 줄 위에, 그룹 차원 종합 2~4문장을 쓴다: 그룹 전반에서 무엇이 산출됐는지, 미결 작업이 어디 있는지(`byWorkStatus`/`byCurrentPhase` 활용), 에러 핫스팟(높은 `errorCount` task)이 있는지.
99
- 3. 각 per-task 주장은 report 경로(`<reportPath>`)로 인용해 독자가 바로 열어볼 수 있게 한다.
97
+ 1. For each task with a non-empty `reportPath` whose `<projectRoot>/<reportPath>` file actually exists, read the report and summarize in 1–2 lines **what it accomplished and its recommended next step**.
98
+ 2. Above the per-task lines, write a 2–4 sentence group-level synthesis: what was delivered across the group, where the open work sits (using `byWorkStatus`/`byCurrentPhase`), and whether there are error hot-spots (tasks with high `errorCount`).
99
+ 3. Cite each per-task claim with the report path (`<reportPath>`) so the reader can open it directly.
100
100
 
101
- report가 없는 task는 요약을 지어내지 말고 현재 phase/workStatus를 대신 말한다. report 아닌 산출물을 읽어 빈칸을 메우지 않는다(artifact-home 규칙). report가 비었거나 없으면 그렇다고 말한다.
101
+ For a task with no report, do not invent a summary; state the current phase/workStatus instead. Do not read non-report artifacts to fill the gap (artifact-home rule). If a report is empty or missing, say so.
102
102
 
103
- 단일 task의 깊은 drill-down(전체 report, worker별 시간, 에러 분해, run 간 recap)이 필요하면 `/okstra-inspect`로 안내한다.
103
+ If a deep single-task drill-down (full report, per-worker time, error breakdown, run-to-run recap) is needed, point the user to `/okstra-inspect`.
104
104
 
105
- ## 금지 패턴
105
+ ## Forbidden patterns
106
106
 
107
- - 집계 수치(합계, 분포)를 `tasks[]`에서 손으로 다시 세기. `totals`가 SSOT다.
108
- - raw ms 노출. 항상 `HH:MM:SS`.
109
- - `cpuSumMs`를 wall-clock인 양 표기.
110
- - report가 없는 task에 대해 요약을 지어내기. 현재 phase/workStatus로 대체한다.
111
- - okstra 산출물 밖(non-`.okstra`) 파일을 읽어 요약을 채우기.
112
- - 단일 task 상세를 rollup에서 처리하기. `okstra-inspect`로 보낸다.
107
+ - Re-counting aggregate numbers (totals, distributions) by hand from `tasks[]`. `totals` is the SSOT.
108
+ - Exposing raw ms. Always `HH:MM:SS`.
109
+ - Labeling `cpuSumMs` as if it were wall-clock.
110
+ - Inventing a summary for a task with no report. Substitute the current phase/workStatus.
111
+ - Reading files outside okstra artifacts (non-`.okstra`) to fill the summary.
112
+ - Handling single-task detail in rollup. Send it to `okstra-inspect`.
package/docs/for-ai/skills/okstra-run.md CHANGED
@@ -1,52 +1,52 @@
1
1
  # okstra-run AI Manual
2
2
 
3
- ## 원천
3
+ ## Source
4
4
 
5
- - 스킬 원문: [`skills/okstra-run/SKILL.md`](../../../skills/okstra-run/SKILL.md)
5
+ - Skill source: [`skills/okstra-run/SKILL.md`](../../../skills/okstra-run/SKILL.md)
6
6
  - wizard CLI wrapper: [`src/commands/execute/wizard.mjs`](../../../src/commands/execute/wizard.mjs)
7
7
  - wizard state machine: [`scripts/okstra_ctl/wizard.py`](../../../scripts/okstra_ctl/wizard.py)
8
8
  - render-bundle CLI: [`src/commands/execute/render-bundle.mjs`](../../../src/commands/execute/render-bundle.mjs)
9
9
  - prepare entrypoint: [`scripts/okstra_ctl/run.py`](../../../scripts/okstra_ctl/run.py)
10
10
 
11
- ## 목적
11
+ ## Purpose
12
12
 
13
- `okstra-run`은 현재 Claude Code 세션 안에서 okstra task run을 시작한다. 입력 수집은 `okstra wizard` state machine이 전담하고, 스킬은 wizard prompt를 사용자에게 relay한 뒤 `okstra render-bundle`로 task bundle을 준비한다. bundle이 준비되면 현재 세션이 Claude lead로 전환된다.
13
+ `okstra-run` starts an okstra task run inside the current Claude Code session. Input collection is owned entirely by the `okstra wizard` state machine; the skill relays the wizard prompts to the user and then prepares the task bundle via `okstra render-bundle`. Once the bundle is ready, the current session takes over as Claude lead.
14
14
 
15
- 단일 권위:
15
+ Single authority:
16
16
 
17
- - 질문 순서, 분기, validation: `scripts/okstra_ctl/wizard.py`
17
+ - Question order, branching, validation: `scripts/okstra_ctl/wizard.py`
18
18
  - task bundle materialization: `prepare_task_bundle()`
19
- - 스킬 문서: thin prompt-relay loop
19
+ - Skill document: thin prompt-relay loop
20
20
 
21
- ## 사용 조건
21
+ ## When to Use
22
22
 
23
- 사용한다:
23
+ Use it when:
24
24
 
25
- - 사용자가 현재 세션에서 okstra task를 시작하려고 한다.
26
- - 기존 task의 다음 phase를 이어서 실행하려고 한다.
27
- - "okstra run", "okstra start", "이 세션에서 okstra 시작", "다음 단계 실행" 등.
25
+ - The user wants to start an okstra task in the current session.
26
+ - The user wants to continue the next phase of an existing task.
27
+ - "okstra run", "okstra start", "start okstra in this session", "run the next phase", etc.
28
28
 
29
- 사용하지 않는다:
29
+ Do not use it when:
30
30
 
31
- - 상태만 보려는 경우: `okstra-inspect status`
32
- - 과거 run이나 resume command를 보려는 경우: `okstra-inspect history`
33
- - 사용자가 새 terminal/new claude process를 명시한 경우: inspect history/resume 안내
31
+ - The user only wants status: `okstra-inspect status`
32
+ - The user wants past runs or a resume command: `okstra-inspect history`
33
+ - The user explicitly named a new terminal / new claude process: point them to inspect history/resume
34
34
 
35
35
  ## Preflight
36
36
 
37
- 단일 Bash 호출:
37
+ A single Bash call:
38
38
 
39
39
  ```bash
40
40
  okstra preflight --runtime claude-code --json
41
41
  ```
42
42
 
43
- runtime이나 project setup이 없으면(`ok:false`) `/okstra-setup`을 안내하고 멈춘다. `export PYTHONPATH`를 만들지 않는다.
43
+ If there is no runtime or project setup (`ok:false`), point the user to `/okstra-setup` and stop. Do not create an `export PYTHONPATH`.
44
44
 
45
- ## Bash 호출 규칙
45
+ ## Bash invocation rule
46
46
 
47
- 모든 okstra 호출은 literal token `okstra`로 시작한다. `--state-file`, `--answer`, path, model, worker 값은 이전 JSON/tool output에서 읽어 literal string으로 붙인다.
47
+ Every okstra call begins with the literal token `okstra`. Read the `--state-file`, `--answer`, path, model, and worker values from the prior JSON/tool output and paste them as literal strings.
48
48
 
49
- 피해야 한다:
49
+ Avoid:
50
50
 
51
51
  - `$STATE_FILE`, `$ANSWER`
52
52
  - `$(...)`
@@ -54,21 +54,21 @@ runtime이나 project setup이 없으면(`ok:false`) `/okstra-setup`을 안내
54
54
  - `eval`, `export`
55
55
  - `okstra ... && okstra ...`
56
56
 
57
- empty answer도 flag를 생략하지 않는다.
57
+ Do not drop the flag even for an empty answer.
58
58
 
59
59
  ```bash
60
60
  okstra wizard step --state-file /tmp/okstra-wizard/state.json --answer ""
61
61
  ```
62
62
 
63
- ## wizard 초기화
63
+ ## wizard initialization
64
64
 
65
- state file 생성:
65
+ Create the state file:
66
66
 
67
67
  ```bash
68
68
  okstra wizard new-state-file
69
69
  ```
70
70
 
71
- 출력 absolute path를 그대로 들고 간다.
71
+ Carry the printed absolute path verbatim.
72
72
 
73
73
  wizard init:
74
74
 
@@ -76,61 +76,61 @@ wizard init:
76
76
  okstra wizard init --state-file /tmp/okstra-wizard/state.json --project-root /abs/project --project-id project-id
77
77
  ```
78
78
 
79
- 결과는 `{ok, next}` JSON이다. 첫 step은 `task_pick`이다.
79
+ The result is `{ok, next}` JSON. The first step is `task_pick`.
80
80
 
81
- ## wizard JSON 해석
81
+ ## Interpreting the wizard JSON
82
82
 
83
- `next.kind`에 따라 UI를 고른다.
83
+ Pick the UI according to `next.kind`.
84
84
 
85
- | kind | 처리 |
85
+ | kind | Handling |
86
86
  |---|---|
87
- | `pick`, `multi: false` | 모든 `options[]`를 그대로 selectable choice로 렌더. 선택 option의 `value` 제출 |
88
- | `pick`, `multi: true` | 모든 선택 value를 comma-separated string으로 제출. 선택 없음도 `--answer ""` 제출 |
89
- | `pick_group` | wizard의 `questions[]`를 한 번의 multi-question UI로 렌더. step별 value를 JSON object로 만들어 한 번에 제출 |
90
- | `text` | picker를 쓰지 않고 plain text label을 보여준 뒤 다음 사용자 메시지를 verbatim 제출 |
91
- | `done` | 입력 수집 종료. render-args로 이동 |
92
- | `aborted` | state file을 지우고 중단. render-args/render-bundle 호출 금지 |
87
+ | `pick`, `multi: false` | Render every `options[]` verbatim as a selectable choice. Submit the chosen option's `value` |
88
+ | `pick`, `multi: true` | Submit all chosen values as a comma-separated string. An empty selection still submits `--answer ""` |
89
+ | `pick_group` | Render the wizard's `questions[]` as a single multi-question UI. Build a JSON object of per-step values and submit it in one shot |
90
+ | `text` | Show a plain text label without a picker, then submit the user's next message verbatim |
91
+ | `done` | Input collection finished. Move to render-args |
92
+ | `aborted` | Delete the state file and stop. Do not call render-args/render-bundle |
93
93
 
94
- `progress.label`은 wizard가 만든 문자열이다. UI prompt 뒤에 그대로 붙이고, 직접 계산하지 않는다.
94
+ `progress.label` is a string the wizard composed. Append it verbatim after the UI prompt; do not compute it yourself.
95
95
 
96
96
  ## wizard loop
97
97
 
98
- 1. prompt 렌더.
99
- 2. 사용자 답변을 literal `--answer`로 제출.
100
- 3. `ok: true`: `result.echo`를 한 줄로 사용자에게 보여주고 다음 step.
101
- 4. `ok: false`: `result.error`를 그대로 보여주고 `result.current`로 같은 step 재시도.
102
- 5. `current: null`: prompt를 재구성할 수 없는 terminal 오류다. 에러를 보여주고 멈춘다.
98
+ 1. Render the prompt.
99
+ 2. Submit the user's answer as a literal `--answer`.
100
+ 3. `ok: true`: show `result.echo` to the user on one line and advance to the next step.
101
+ 4. `ok: false`: show `result.error` verbatim and retry the same step via `result.current`.
102
+ 5. `current: null`: a terminal error where the prompt cannot be reconstructed. Show the error and stop.
103
103
 
104
- 중요: wizard가 제공한 option을 줄이거나 숨기거나 "추천 + 직접 입력"으로 재구성하지 않는다. wizard의 `options[]`가 완전한 선택지다.
104
+ Important: never trim, hide, or restructure the wizard-provided options into a "recommended + Enter directly" form. The wizard's `options[]` is the complete choice set.
105
105
 
106
- ## brief 후보 정렬
106
+ ## brief candidate ordering
107
107
 
108
- entry phase(`requirements-discovery`, `error-analysis`, `improvement-discovery`)의 brief 선택은 wizard가 처리한다.
108
+ The brief selection for entry phases (`requirements-discovery`, `error-analysis`, `improvement-discovery`) is handled by the wizard.
109
109
 
110
- - task-group 후보는 task catalog의 최근 사용 이력과 `.okstra/briefs/<group>/` 아래 최근 brief 생성/수정 시각을 합산해 최신순으로 보여준다.
111
- - brief 파일 후보는 선택된 group의 `.okstra/briefs/<task-group>/**/*.md` 안에서 고른다.
112
- - brief 파일 정렬 키는 `max(파일 생성/수정 시각, 해당 brief를 사용한 task catalog updatedAt)`이다.
113
- - direct input은 항상 마지막이다.
110
+ - task-group candidates are shown newest-first by combining recent task-catalog use with the recent brief creation/modification times under `.okstra/briefs/<group>/`.
111
+ - brief file candidates are chosen from within the selected group's `.okstra/briefs/<task-group>/**/*.md`.
112
+ - The brief-file sort key is `max(file created/modified time, task-catalog updatedAt of the task that used this brief)`.
113
+ - direct input is always last.
114
114
 
115
115
  ## confirm step
116
116
 
117
- `next.step == "confirm"`이면 먼저 confirmation summary를 가져온다.
117
+ When `next.step == "confirm"`, first fetch the confirmation summary.
118
118
 
119
119
  ```bash
120
120
  okstra wizard confirmation --state-file /tmp/okstra-wizard/state.json
121
121
  ```
122
122
 
123
- `text`를 사용자에게 보여준 뒤 Proceed/Edit/중단 picker를 렌더한다. `Edit`은 wizard가 이전 step으로 rewind한다.
123
+ Show `text` to the user, then render the Proceed/Edit/Abort picker. `Edit` rewinds the wizard to an earlier step.
124
124
 
125
- ## outcome과 render-bundle
125
+ ## outcome and render-bundle
126
126
 
127
- `next.kind == "done"`이면:
127
+ When `next.kind == "done"`:
128
128
 
129
129
  ```bash
130
130
  okstra wizard outcome --state-file /tmp/okstra-wizard/state.json
131
131
  ```
132
132
 
133
- `outcome.persistActions[]`를 먼저 실행한 뒤 `outcome.renderArgs` object의 key를 `okstra render-bundle` flag로 전달한다. 빈 string 값도 명시적으로 전달한다. 예외: `chain-stages` key는 render-bundle flag가 아니다 — Step 7 무인 연쇄 루프를 구동하는 값이라 flag로 넘기지 않는다(`run.py`는 `--stage`/`--stages`만 받는다). render-bundle block의 `--stage`는 implementation·final-verification 전용, `--stages`는 release-handoff 전용(빈 값 = whole-task)이다.
133
+ Run `outcome.persistActions[]` first, then pass each key of the `outcome.renderArgs` object as an `okstra render-bundle` flag. Pass empty string values explicitly too. Exception: the `chain-stages` key is not a render-bundle flag — it drives the Step 7 unattended-chaining loop, so do not pass it as a flag (`run.py` accepts only `--stage`/`--stages`). In the render-bundle block, `--stage` is implementation·final-verification only, and `--stages` is release-handoff only (empty value = whole-task).
134
134
 
135
135
  ```bash
136
136
  okstra render-bundle \
@@ -160,52 +160,52 @@ okstra render-bundle \
160
160
  --fix-cycle "<args.fix-cycle>"
161
161
  ```
162
162
 
163
- stdout에서 다음 labeled line을 파싱한다.
163
+ Parse the following labeled lines from stdout.
164
164
 
165
165
  - `okstra task root:`
166
166
  - `okstra instruction-set:`
167
- - 선택적으로 `okstra concurrent-run stages:`
167
+ - optionally `okstra concurrent-run stages:`
168
168
 
169
- render-bundle은 `prepare_task_bundle()`을 render-only로 호출해 manifests, run context, instruction set, discovery files를 준비하고 `~/.okstra/recent.jsonl`에 `prepared`로 등록한다.
169
+ render-bundle calls `prepare_task_bundle()` in render-only mode to prepare the manifests, run context, instruction set, and discovery files, and registers the run as `prepared` in `~/.okstra/recent.jsonl`.
170
170
 
171
171
  ## conformance waiver
172
172
 
173
- implementation에서 Tier 3 conformance가 환경상 불가능할 때만 사용자에게 waiver를 제안한다. waiver는 사용자 승인과 verbatim reason이 있어야 한다. AI lead나 worker가 자체 면제를 만들지 않는다.
173
+ Offer a waiver to the user only when Tier 3 conformance is genuinely impossible in the environment during implementation. A waiver requires user approval and a verbatim reason. Neither the AI lead nor a worker creates a self-exemption.
174
174
 
175
- 선택 시 `render-bundle`에만 추가한다.
175
+ When chosen, add it to `render-bundle` only.
176
176
 
177
177
  ```bash
178
178
  --qa-waiver "<stageKey>:<reason>"
179
179
  ```
180
180
 
181
- 값이 없으면 flag 자체를 생략한다.
181
+ Omit the flag entirely when there is no value.
182
182
 
183
- ## concurrent-run 분기
183
+ ## concurrent-run branch
184
184
 
185
- `render-bundle` stdout에 `okstra concurrent-run stages:`가 있으면 이미 no-team background gate가 prompt에 반영된 상태다.
185
+ If `render-bundle` stdout carries `okstra concurrent-run stages:`, the no-team background gate is already reflected in the prompt.
186
186
 
187
- 사용자에게 세 선택지를 준다.
187
+ Give the user three options.
188
188
 
189
- 1. no-team background로 진행.
190
- 2. 대기 — dispatch 보류, stage worktree·run context 보존. 점유 run 종료 후 같은 stage를 resume으로 재개하도록 resume 명령(`okstra-inspect` history → resume)을 사용자에게 출력한다.
191
- 3. 직접 입력.
189
+ 1. Proceed as no-team background.
190
+ 2. Wait — hold the dispatch, preserve the stage worktree·run context. After the occupying run finishes, print the resume command (`okstra-inspect` history → resume) so the user can resume the same stage.
191
+ 3. Enter directly.
192
192
 
193
- 이 picker는 스킬이 만드는 것이므로 wizard option 축약 금지 규칙과 별개다.
193
+ This picker is authored by the skill, so it is separate from the wizard-option-abbreviation ban.
194
194
 
195
195
  ## stale git SHA recovery
196
196
 
197
- `Recorded stage SHAs no longer match the git history`류 `PrepareError`가 나오면 registry/consumers를 수동 수정하지 않는다.
197
+ When a `PrepareError` such as `Recorded stage SHAs no longer match the git history` appears, do not fix the registry/consumers by hand.
198
198
 
199
- 1. 에러 메시지에 나온 `okstra git-reconcile ... --check --json`을 그대로 실행한다.
200
- 2. confirm 항목마다 사용자에게 current branch tip, 다른 ref, 중단을 묻는다.
201
- 3. 선택 ref로 `okstra git-reconcile ... --apply --stage <N> --use-ref <ref>`를 실행한다.
202
- 4. 실패했던 render-bundle을 같은 인자로 재시도한다.
199
+ 1. Run the `okstra git-reconcile ... --check --json` printed in the error message verbatim.
200
+ 2. For each confirm item, ask the user for the current branch tip, a different ref, or abort.
201
+ 3. Run `okstra git-reconcile ... --apply --stage <N> --use-ref <ref>` with the chosen ref.
202
+ 4. Retry the failed render-bundle with the same arguments.
203
203
 
204
- anchor가 unresolvable이면 `--reset-anchor <ref>`는 사용자 확인 후 실행한다.
204
+ If the anchor is unresolvable, run `--reset-anchor <ref>` after user confirmation.
205
205
 
206
206
  ## PR template persistence
207
207
 
208
- release-handoff에서 `outcome.persistActions[]`가 `config.set` / `pr-template-path` action을 반환하면 render-bundle 전에 config를 저장한다.
208
+ In release-handoff, when `outcome.persistActions[]` returns a `config.set` / `pr-template-path` action, save the config before render-bundle.
209
209
 
210
210
  ```bash
211
211
  # action.scope == "project"
@@ -214,40 +214,40 @@ okstra config set pr-template-path "<path>" --scope project
214
214
  okstra config set pr-template-path "<path>" --scope global
215
215
  ```
216
216
 
217
- scope와 path는 wizard state file이 아니라 `okstra wizard outcome`의 persist action에서 읽는다. raw state file을 직접 읽지 않는다.
217
+ Read the scope and path from the persist action of `okstra wizard outcome`, not from the wizard state file. Do not read the raw state file directly.
218
218
 
219
- ## Claude lead 전환
219
+ ## Claude lead takeover
220
220
 
221
- render-bundle 후 `<INSTRUCTION_SET_PATH>/claude-execution-prompt.md`를 verbatim으로 읽고, 그 prompt 순서대로 Phase 1부터 진행한다.
221
+ After render-bundle, read `<INSTRUCTION_SET_PATH>/claude-execution-prompt.md` verbatim and proceed from Phase 1 in that prompt's order.
222
222
 
223
- 사용자에게 한 줄로 알린다.
223
+ Inform the user on one line.
224
224
 
225
225
  ```text
226
226
  Took over as Claude lead for `<taskKey>` (`<task-type>`). Run dir: `<RUN_DIR_RELATIVE_PATH>`. Beginning Phase 1 (context loading).
227
227
  ```
228
228
 
229
- 단일 원소 chain이면 Step 6 종료가 곧 run 종료다. 아래 Step 7은 `chain-stages` CSV가 2개 이상일 때만 적용된다.
229
+ For a single-element chain, the end of Step 6 is the end of the run. Step 7 below applies only when the `chain-stages` CSV has 2 or more elements.
230
230
 
231
- ## implementation 무인 연쇄 (chain-stages)
231
+ ## implementation unattended chaining (chain-stages)
232
232
 
233
- `task-type == implementation`이고 render-args `chain-stages` CSV가 원소 2개 이상이면, 현재 세션이 오케스트레이터로서 stage를 의존성 순서대로 무인 연쇄 실행한다. 큐 = `chain-stages`를 `,`로 분해한 위상정렬 stage 리스트. 큐의 각 stage `N`에 대해 순서대로:
233
+ When `task-type == implementation` and the render-args `chain-stages` CSV has 2 or more elements, the current session acts as the orchestrator and runs the stages as an unattended chain in dependency order. Queue = the topologically-sorted stage list from splitting `chain-stages` on `,`. For each stage `N` in the queue, in order:
234
234
 
235
- 1. render-bundle을 같은 인자로, 단 `--stage N`으로 재호출한다(base commit은 prepare가 predecessor의 done `head_commit`으로 자동 계산 — 손으로 넘기지 않는다). conformance waiver·concurrent-run·git-reconcile 게이트는 매 stage의 render-bundle마다 동일 적용.
236
- 2. Step 6대로 Claude lead가 되어 그 stage의 Phase 1~7을 인라인 실행한다. Phase 6의 lead persistence가 `runs/<plan-task-key>/consumers.jsonl`에 그 stage의 `status:"done"` 행을 append한다.
237
- 3. `done` 행 기록을 확인한 뒤 다음 stage로 넘어간다. stage 경계마다 컨텍스트(잔여 pane·완료 teammate)를 정리한다.
238
- 4. stage 시작/완료마다 한 줄 보고: `stage N/<총개수> 시작` / `stage N done → 다음 K`.
235
+ 1. Re-call render-bundle with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit` — do not pass it by hand). The conformance waiver·concurrent-run·git-reconcile gates apply identically to each stage's render-bundle.
236
+ 2. As in Step 6, become Claude lead and run that stage's Phase 1–7 inline. Phase 6's lead persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl`.
237
+ 3. After confirming the `done` row was written, move to the next stage. Clean up context (leftover panes·finished teammates) at each stage boundary.
238
+ 4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
239
239
 
240
- 큐를 모두 소화하면 연쇄를 종료하고 완료를 보고한다.
240
+ Once the whole queue is consumed, end the chain and report completion.
241
241
 
242
- - **다음 stage가 아직 ready 아님 — 정상 종료:** 큐의 stage가 다른 implementation run에 started/reserved로 점유돼 render-bundle이 `--stage N already in progress or reserved by another run`(StageTargetError)으로 거부되면, 이는 예외가 아니다 — 연쇄를 **정상 종료**하고 남은 큐를 보고한다(예: `남은 큐: stage 4, 5 — 점유 해제 후 okstra-run으로 재개`).
243
- - **연쇄 중 예외 게이트:** render-bundle이 concurrent-run 충돌이나 git stale-SHA 재조정을 띄우면 **그 stage에서 연쇄를 멈추고** 게이트를 Step 5 절차대로 사용자에게 제시한다. 사용자가 해소하면 그 자리에서 남은 큐를 이어 재개한다. 데이터 손상·동시 점유 충돌은 사람이 확인 — 무인 연쇄의 안전 경계다.
242
+ - **Next stage not yet ready — normal termination:** When a stage in the queue is occupied by another implementation run as started/reserved and render-bundle is rejected with `--stage N already in progress or reserved by another run` (StageTargetError), this is not an exception — **terminate the chain normally** and report the remaining queue (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`).
243
+ - **Exception gate during chaining:** If render-bundle raises a concurrent-run conflict or git stale-SHA reconciliation, **stop the chain at that stage** and present the gate to the user per the Step 5 procedure. Once the user resolves it, resume the remaining queue in place. Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining.
244
244
 
245
- ## 금지 패턴
245
+ ## Forbidden patterns
246
246
 
247
- - wizard가 내준 질문 순서를 바꾸기.
248
- - wizard option을 숨기거나 추천만 남기기.
249
- - `text` prompt를 picker로 바꾸기.
250
- - empty answer에서 `--answer` flag를 생략하기.
251
- - `okstra.sh`를 호출해 wizard/render-bundle 경로를 우회하기.
252
- - render-bundle 전에 사용자가 abort한 state로 render-args를 호출하기.
253
- - Claude lead prompt를 읽기 전에 phase 작업을 임의로 시작하기.
247
+ - Changing the question order the wizard emitted.
248
+ - Hiding wizard options or keeping only the recommendations.
249
+ - Turning a `text` prompt into a picker.
250
+ - Dropping the `--answer` flag on an empty answer.
251
+ - Bypassing the wizard/render-bundle path by calling `okstra.sh`.
252
+ - Calling render-args on a state the user aborted before render-bundle.
253
+ - Starting phase work arbitrarily before reading the Claude lead prompt.