okstra 0.122.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 (108) hide show
  1. package/README.md +5 -2
  2. package/docs/architecture/storage-model.md +15 -1
  3. package/docs/architecture.md +45 -7
  4. package/docs/cli.md +47 -5
  5. package/docs/for-ai/README.md +42 -36
  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 +320 -0
  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 +92 -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 +52 -28
  26. package/docs/task-process/implementation.md +51 -32
  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/bin/lib/okstra/usage.sh +3 -3
  36. package/runtime/prompts/coding-preflight/frameworks/node-server.md +1 -1
  37. package/runtime/prompts/launch.template.md +6 -3
  38. package/runtime/prompts/lead/convergence.md +11 -21
  39. package/runtime/prompts/lead/okstra-lead-contract.md +16 -18
  40. package/runtime/prompts/lead/plan-body-verification.md +47 -18
  41. package/runtime/prompts/lead/report-writer.md +50 -45
  42. package/runtime/prompts/lead/team-contract.md +11 -122
  43. package/runtime/prompts/profiles/_common-contract.md +15 -22
  44. package/runtime/prompts/profiles/_implementation-deliverable.md +4 -2
  45. package/runtime/prompts/profiles/_implementation-executor.md +6 -1
  46. package/runtime/prompts/profiles/_implementation-verifier.md +3 -3
  47. package/runtime/prompts/profiles/error-analysis.md +2 -2
  48. package/runtime/prompts/profiles/final-verification.md +3 -1
  49. package/runtime/prompts/profiles/implementation-planning.md +24 -14
  50. package/runtime/prompts/profiles/implementation.md +1 -1
  51. package/runtime/prompts/profiles/improvement-discovery.md +1 -1
  52. package/runtime/prompts/profiles/release-handoff.md +3 -3
  53. package/runtime/prompts/profiles/requirements-discovery.md +18 -18
  54. package/runtime/prompts/wizard/prompts.ko.json +44 -0
  55. package/runtime/python/okstra_ctl/codex_dispatch.py +23 -1
  56. package/runtime/python/okstra_ctl/design_prep.py +1462 -0
  57. package/runtime/python/okstra_ctl/design_surfaces.py +243 -0
  58. package/runtime/python/okstra_ctl/final_report_schema.py +33 -1
  59. package/runtime/python/okstra_ctl/implementation_stage.py +35 -0
  60. package/runtime/python/okstra_ctl/incremental_carry.py +294 -21
  61. package/runtime/python/okstra_ctl/incremental_scope.py +51 -5
  62. package/runtime/python/okstra_ctl/material.py +1 -1
  63. package/runtime/python/okstra_ctl/model_discovery.py +98 -0
  64. package/runtime/python/okstra_ctl/models.py +8 -3
  65. package/runtime/python/okstra_ctl/render.py +5 -0
  66. package/runtime/python/okstra_ctl/run.py +53 -5
  67. package/runtime/python/okstra_ctl/user_response.py +67 -2
  68. package/runtime/python/okstra_ctl/wizard.py +283 -3
  69. package/runtime/python/okstra_token_usage/report.py +11 -0
  70. package/runtime/schemas/final-report-v1.0.schema.json +336 -0
  71. package/runtime/skills/_fragments/bash-invocation-rule.md +1 -0
  72. package/runtime/skills/_fragments/preflight-outdated-cli.md +1 -0
  73. package/runtime/skills/_fragments/python-bootstrap-note.md +1 -0
  74. package/runtime/skills/okstra-brief-gen/SKILL.md +117 -122
  75. package/runtime/skills/okstra-container-build/SKILL.md +24 -14
  76. package/runtime/skills/okstra-graphify/SKILL.md +12 -4
  77. package/runtime/skills/okstra-inspect/SKILL.md +105 -99
  78. package/runtime/skills/okstra-manager/SKILL.md +1 -1
  79. package/runtime/skills/okstra-memory/SKILL.md +3 -3
  80. package/runtime/skills/okstra-rollup/SKILL.md +12 -6
  81. package/runtime/skills/okstra-run/SKILL.md +49 -88
  82. package/runtime/skills/{okstra-schedule → okstra-schedule-gen}/SKILL.md +38 -32
  83. package/runtime/skills/okstra-setup/SKILL.md +1 -1
  84. package/runtime/skills/okstra-setup/references/project-config.md +17 -16
  85. package/runtime/skills/okstra-usage/SKILL.md +5 -2
  86. package/runtime/skills/okstra-user-response/SKILL.md +23 -9
  87. package/runtime/templates/prd/brief.template.md +92 -92
  88. package/runtime/templates/reports/error-analysis-input.template.md +1 -1
  89. package/runtime/templates/reports/fan-out-unit.template.md +6 -6
  90. package/runtime/templates/reports/final-report.template.md +67 -0
  91. package/runtime/templates/reports/final-verification-input.template.md +6 -6
  92. package/runtime/templates/reports/i18n/en.json +31 -0
  93. package/runtime/templates/reports/i18n/ko.json +31 -0
  94. package/runtime/templates/reports/implementation-input.template.md +1 -1
  95. package/runtime/templates/reports/implementation-planning-input.template.md +1 -1
  96. package/runtime/templates/reports/improvement-discovery-input.template.md +1 -1
  97. package/runtime/templates/reports/quick-input.template.md +1 -1
  98. package/runtime/templates/reports/release-handoff-input.template.md +1 -1
  99. package/runtime/templates/reports/schedule.template.md +22 -22
  100. package/runtime/templates/reports/task-brief.template.md +3 -3
  101. package/runtime/templates/reports/user-response.template.md +20 -20
  102. package/runtime/templates/worker-prompt-preamble.md +111 -13
  103. package/runtime/validators/validate-run.py +426 -5
  104. package/runtime/validators/validate-schedule.py +5 -5
  105. package/src/cli-registry.mjs +7 -0
  106. package/src/commands/inspect/design-prep.mjs +23 -0
  107. package/src/lib/skill-catalog.mjs +2 -1
  108. package/docs/for-ai/skills/okstra-schedule.md +0 -320
@@ -1,82 +1,82 @@
1
1
  # okstra-memory AI Manual
2
2
 
3
- ## 원천
3
+ ## Source
4
4
 
5
- - 스킬 원문: [`skills/okstra-memory/SKILL.md`](../../../skills/okstra-memory/SKILL.md)
5
+ - Skill source: [`skills/okstra-memory/SKILL.md`](../../../skills/okstra-memory/SKILL.md)
6
6
  - CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
7
7
  - memory CLI: [`src/commands/memory/memory.mjs`](../../../src/commands/memory/memory.mjs)
8
8
 
9
- ## 목적
9
+ ## Purpose
10
10
 
11
- `okstra-memory`는 사용자 홈의 Memory Book을 관리한다.
11
+ `okstra-memory` manages the Memory Book in the user's home.
12
12
 
13
13
  ```text
14
14
  ~/.okstra/memory-book/
15
15
  ```
16
16
 
17
- 프로젝트 local `.okstra/` artifact가 아니다. `<PROJECT_ROOT>/.okstra/project.json`이 없어도 사용할 수 있다.
17
+ It is not a project-local `.okstra/` artifact. It can be used even without `<PROJECT_ROOT>/.okstra/project.json`.
18
18
 
19
- ## 사용 조건
19
+ ## When to use
20
20
 
21
- 사용한다:
21
+ Use it when:
22
22
 
23
- - 사용자가 "기억해둬", "대화 저장", "okstra에 정리해서 보관", "remember this", "save this decision"처럼 명시적으로 저장을 요청한다.
24
- - 저장된 memory를 검색, 목록화, 읽기, archive하려고 한다.
23
+ - The user explicitly asks to save, e.g. "remember this", "save the conversation", "organize and store this in okstra", "remember this", "save this decision".
24
+ - The user wants to search, list, read, or archive stored memory.
25
25
 
26
- 사용하지 않는다:
26
+ Do not use it when:
27
27
 
28
- - 사용자가 단순 brainstorming 중이고 저장 요청이 없다. 이때는 확인 질문을 먼저 한다.
29
- - project task artifact로 남겨야 하는 내용. 이 경우 해당 okstra task의 brief/report/decision 경로를 사용한다.
28
+ - The user is only brainstorming with no save request. In that case, ask a confirmation question first.
29
+ - The content should be kept as a project task artifact. In that case, use the brief/report/decision path of the relevant okstra task.
30
30
 
31
31
  ## safety rule
32
32
 
33
- 명시적 저장 요청 없이 저장하지 않는다. credentials, API keys, tokens, private personal data, secrets는 저장하지 않는다. 대화에 민감한 내용이 있으면 summary에서 제외하고 omission을 기록한다.
33
+ Do not save without an explicit save request. Do not store credentials, API keys, tokens, private personal data, or secrets. If the conversation includes sensitive material, exclude it from the summary and note the omission.
34
34
 
35
- CLI도 high-confidence secret shape를 감지해 `memory add`를 거부할 수 있다. 거부되면 내용을 redact하고 재시도한다.
35
+ The CLI can also detect high-confidence secret shapes and refuse `memory add`. If refused, redact the content and retry.
36
36
 
37
37
  ## CLI availability
38
38
 
39
- 먼저 help를 확인한다.
39
+ Check the help first.
40
40
 
41
41
  ```bash
42
42
  okstra memory --help
43
43
  ```
44
44
 
45
- `okstra`가 PATH에 없으면 `npx okstra@latest install`을 직접 실행하지 말고, 한 번 설치 후 재시도하라고 안내한다.
45
+ If `okstra` is not on PATH, do not run `npx okstra@latest install` directly; tell the user to install it once and then retry.
46
46
 
47
- ## project-group 선택
47
+ ## project-group selection
48
48
 
49
- 모든 memory entry는 project-group에 속한다. 저장/검색 전에 group을 먼저 고른다.
49
+ Every memory entry belongs to a project-group. Pick the group before storing or searching.
50
50
 
51
- 기존 group 조회:
51
+ Enumerate existing groups:
52
52
 
53
53
  ```bash
54
54
  okstra memory groups --json
55
55
  ```
56
56
 
57
- 추천:
57
+ Recommendations:
58
58
 
59
- - 가장 많이 쓰인 existing group
60
- - 두 번째 existing group
61
- - 직접 입력
59
+ - the most-used existing group
60
+ - the second existing group
61
+ - Enter directly
62
62
 
63
- 개인 메모리는 `private`를 우선 추천한다. group이 없거나 선택이 없으면 CLI default인 `global`을 쓴다.
63
+ For a personal note, recommend `private` first. If there is no group or no selection, use the CLI default `global`.
64
64
 
65
- 선택 group은 `add`, `search`, `list`에 `--project-group <group>`으로 전달한다. 사용자가 cross-group search를 명시한 경우에만 flag를 생략한다.
65
+ Pass the chosen group to `add`, `search`, and `list` as `--project-group <group>`. Omit the flag only when the user explicitly wants a cross-group search.
66
66
 
67
- ## 저장 절차
67
+ ## Store procedure
68
68
 
69
- 대화 전체 transcript를 저장하지 않는다. 오래 남길 durable memory만 추출해 concise Markdown summary로 만든다.
69
+ Do not store the full conversation transcript. Extract only durable memory worth keeping long-term and turn it into a concise Markdown summary.
70
70
 
71
- 포함할 것:
71
+ Include:
72
72
 
73
- - 저장 이유
73
+ - the reason for storing
74
74
  - source: `conversation`
75
- - 관련 project id가 명확하면 `--project`
76
- - 검색용 tags
75
+ - `--project` when the related project id is clear
76
+ - tags for search
77
77
  - memory type
78
78
 
79
- type 값은 `okstra memory --help` 출력이 권위다. 원문 기준 category:
79
+ The `okstra memory --help` output is authoritative for the type values. Categories per the source:
80
80
 
81
81
  - `decision`
82
82
  - `preference`
@@ -86,19 +86,19 @@ type 값은 `okstra memory --help` 출력이 권위다. 원문 기준 category:
86
86
  - `follow-up`
87
87
  - `context`
88
88
 
89
- 저장 명령 형태:
89
+ Store command shape:
90
90
 
91
91
  ```bash
92
92
  okstra memory add --content "<summary markdown>" --title "<short title>" --type <type> --project-group <group> --tag <tag> --project <id> --source conversation --yes
93
93
  ```
94
94
 
95
- 필요하면 `--tag`, `--project`를 반복한다. 관련 project가 명확하지 않으면 `--project`를 생략한다.
95
+ Repeat `--tag` and `--project` as needed. Omit `--project` when no related project is clear.
96
96
 
97
- `--yes`는 사용자가 저장을 명시했을 때만 사용한다.
97
+ Use `--yes` only when the user explicitly asked to save.
98
98
 
99
- ## 검색/읽기/archive
99
+ ## search / read / archive
100
100
 
101
- 기본은 선택한 project-group scope다.
101
+ The default scope is the chosen project-group.
102
102
 
103
103
  ```bash
104
104
  okstra memory search "<query>" --project-group "<group>"
@@ -108,20 +108,19 @@ okstra memory show "<memory-id>"
108
108
  okstra memory archive "<memory-id>"
109
109
  ```
110
110
 
111
- ID parsing이 필요하면 `--json`을 선호한다. 사용자에게는 짧은 요약과 entry id/path 정도만 보여준다.
111
+ Prefer `--json` when you need to parse IDs. Show the user only a short summary plus the entry id/path.
112
112
 
113
- ## 출력 규칙
113
+ ## Output rules
114
114
 
115
- - 저장 시 title, type, project-group, tags, generated id를 요약한다.
116
- - 검색 시 match count와 가장 관련 높은 entry를 먼저 보여준다.
117
- - archive는 사용자 의도가 명확할 때만 실행한다.
118
- - project `.okstra/`에 쓰지 않는다.
115
+ - On store, summarize title, type, project-group, tags, and the generated id.
116
+ - On search, show the match count and the most relevant entry first.
117
+ - Run archive only when the user's intent is clear.
118
+ - Do not write into a project `.okstra/`.
119
119
 
120
- ## 금지 패턴
121
-
122
- - 명시 요청 없이 자동 저장.
123
- - secret/token/key를 저장.
124
- - full transcript를 그대로 저장.
125
- - project-local task memory처럼 `.okstra/`에 쓰기.
126
- - cross-group search를 사용자가 요청하지 않았는데 기본으로 수행하기.
120
+ ## Forbidden patterns
127
121
 
122
+ - Auto-saving without an explicit request.
123
+ - Storing a secret/token/key.
124
+ - Storing the full transcript verbatim.
125
+ - Writing into `.okstra/` as if it were project-local task memory.
126
+ - Performing a cross-group search by default when the user did not ask for it.
@@ -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.
@@ -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`. 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`.