okstra 0.102.2 → 0.102.4

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 (167) hide show
  1. package/README.kr.md +5 -5
  2. package/README.md +5 -5
  3. package/docs/kr/architecture/storage-model.md +8 -3
  4. package/docs/kr/architecture.md +12 -13
  5. package/docs/kr/cli.md +4 -4
  6. package/docs/kr/container.md +1 -1
  7. package/docs/kr/performance-improvement-plan-v2.md +2 -2
  8. package/docs/project-structure-overview.md +2 -2
  9. package/package.json +7 -2
  10. package/runtime/BUILD.json +2 -2
  11. package/runtime/bin/lib/okstra/interactive.sh +12 -0
  12. package/runtime/bin/okstra-antigravity-exec.sh +1 -2
  13. package/runtime/bin/okstra-codex-exec.sh +1 -2
  14. package/runtime/bin/okstra-render-final-report.py +2 -9
  15. package/runtime/bin/okstra-spawn-followups.py +4 -6
  16. package/runtime/bin/okstra-trace-cleanup.sh +24 -4
  17. package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
  18. package/runtime/prompts/lead/report-writer.md +1 -1
  19. package/runtime/prompts/profiles/_common-contract.md +9 -11
  20. package/runtime/python/okstra_ctl/codex_dispatch.py +6 -13
  21. package/runtime/python/okstra_ctl/consumers.py +35 -0
  22. package/runtime/python/okstra_ctl/container.py +4 -6
  23. package/runtime/python/okstra_ctl/dispatch_core.py +8 -13
  24. package/runtime/python/okstra_ctl/final_report_paths.py +24 -0
  25. package/runtime/python/okstra_ctl/handoff.py +2 -1
  26. package/runtime/python/okstra_ctl/implementation_outcome.py +271 -0
  27. package/runtime/python/okstra_ctl/implementation_stage.py +7 -11
  28. package/runtime/python/okstra_ctl/path_hints.py +665 -0
  29. package/runtime/python/okstra_ctl/render.py +4 -3
  30. package/runtime/python/okstra_ctl/report_view_artifacts.py +14 -0
  31. package/runtime/python/okstra_ctl/report_views.py +7 -4
  32. package/runtime/python/okstra_ctl/run.py +3 -10
  33. package/runtime/python/okstra_ctl/run_context.py +4 -2
  34. package/runtime/python/okstra_ctl/stage_targets.py +18 -0
  35. package/runtime/python/okstra_ctl/wizard.py +37 -26
  36. package/runtime/python/okstra_ctl/wizard_stage_intent.py +54 -0
  37. package/runtime/python/okstra_project/state.py +40 -2
  38. package/runtime/python/okstra_token_usage/report.py +2 -5
  39. package/runtime/validators/validate-report-views.py +2 -1
  40. package/runtime/validators/validate-run.py +1 -11
  41. package/src/commands/lifecycle/install.mjs +5 -5
  42. package/src/commands/lifecycle/uninstall.mjs +4 -4
  43. package/docs/superpowers/plans/2026-05-12-ticket-id-in-reports.md +0 -638
  44. package/docs/superpowers/plans/2026-05-14-convergence-queue-pruning.md +0 -1568
  45. package/docs/superpowers/plans/2026-05-17-dual-format-final-report.md +0 -167
  46. package/docs/superpowers/plans/2026-05-20-final-report-language.md +0 -1501
  47. package/docs/superpowers/plans/2026-05-20-implementation-planning-multi-stage.md +0 -1267
  48. package/docs/superpowers/plans/2026-05-20-okstra-run-prompt-sot-b1.md +0 -1007
  49. package/docs/superpowers/plans/2026-05-20-wizard-messages-json-sot.md +0 -720
  50. package/docs/superpowers/plans/2026-05-20-wizard-prompt-json-sot-a1.md +0 -681
  51. package/docs/superpowers/plans/2026-05-21-improvement-discovery-task-type.md +0 -1691
  52. package/docs/superpowers/plans/2026-05-24-implementation-lead-context-slimming.md +0 -1700
  53. package/docs/superpowers/plans/2026-05-25-okstra-project-root-rename.md +0 -158
  54. package/docs/superpowers/plans/2026-05-26-wizard-3-option-picker.md +0 -860
  55. package/docs/superpowers/plans/2026-06-02-final-verification-protocol-hardening.md +0 -326
  56. package/docs/superpowers/plans/2026-06-02-okstra-run-branch-confirm-step.md +0 -337
  57. package/docs/superpowers/plans/2026-06-02-okstra-run-phase-pane-cleanup.md +0 -410
  58. package/docs/superpowers/plans/2026-06-02-requirements-discovery-fanout.md +0 -728
  59. package/docs/superpowers/plans/2026-06-04-adversarial-implementation-planning.md +0 -294
  60. package/docs/superpowers/plans/2026-06-04-adversarial-verification.md +0 -570
  61. package/docs/superpowers/plans/2026-06-04-coverage-critic.md +0 -516
  62. package/docs/superpowers/plans/2026-06-04-stage-cohesion-planner.md +0 -351
  63. package/docs/superpowers/plans/2026-06-04-stage-run-batching.md +0 -457
  64. package/docs/superpowers/plans/2026-06-05-acceptance-critic.md +0 -251
  65. package/docs/superpowers/plans/2026-06-05-compact-markdown-report-tables.md +0 -323
  66. package/docs/superpowers/plans/2026-06-05-wizard-batch-prompts.md +0 -559
  67. package/docs/superpowers/plans/2026-06-06-final-verification-whole-task-gate.md +0 -993
  68. package/docs/superpowers/plans/2026-06-06-stage-parallel-and-pending-fixes.md +0 -93
  69. package/docs/superpowers/plans/2026-06-06-stage-worktree-isolation-p1.md +0 -447
  70. package/docs/superpowers/plans/2026-06-06-stage-worktree-isolation-p2.md +0 -289
  71. package/docs/superpowers/plans/2026-06-06-stage-worktree-isolation-p3.md +0 -774
  72. package/docs/superpowers/plans/2026-06-06-stage-worktree-isolation-p4.md +0 -303
  73. package/docs/superpowers/plans/2026-06-06-stage-worktree-isolation-p5-multidep-base.md +0 -387
  74. package/docs/superpowers/plans/2026-06-07-stage-conformance-qa-phase2.md +0 -275
  75. package/docs/superpowers/plans/2026-06-07-stage-conformance-qa-phase3.md +0 -282
  76. package/docs/superpowers/plans/2026-06-07-stage-conformance-qa-phase4a.md +0 -147
  77. package/docs/superpowers/plans/2026-06-07-stage-conformance-qa-phase4b.md +0 -262
  78. package/docs/superpowers/plans/2026-06-07-stage-conformance-qa-phase4c.md +0 -184
  79. package/docs/superpowers/plans/2026-06-07-stage-conformance-qa-phase4d.md +0 -88
  80. package/docs/superpowers/plans/2026-06-07-stage-conformance-qa-phase4e.md +0 -250
  81. package/docs/superpowers/plans/2026-06-07-stage-conformance-qa.md +0 -409
  82. package/docs/superpowers/plans/2026-06-09-implementation-run-artifact-stage-isolation.md +0 -320
  83. package/docs/superpowers/plans/2026-06-10-concurrent-run-team-guard.md +0 -456
  84. package/docs/superpowers/plans/2026-06-10-git-reconcile-stale-sha-recovery.md +0 -1408
  85. package/docs/superpowers/plans/2026-06-10-lead-worker-completion-polling-PROBE.md +0 -42
  86. package/docs/superpowers/plans/2026-06-10-lead-worker-completion-polling.md +0 -337
  87. package/docs/superpowers/plans/2026-06-10-p6-token-usage-incremental.md +0 -1029
  88. package/docs/superpowers/plans/2026-06-10-stage-group-handoff.md +0 -1572
  89. package/docs/superpowers/plans/2026-06-11-fix-cycle.md +0 -1290
  90. package/docs/superpowers/plans/2026-06-11-wizard-whole-task-final-verification.md +0 -526
  91. package/docs/superpowers/plans/2026-06-12-html-plan-approval.md +0 -1000
  92. package/docs/superpowers/plans/2026-06-13-repo-risk-hardening.md +0 -493
  93. package/docs/superpowers/plans/2026-06-14-host-runtime-auto-execution.md +0 -1775
  94. package/docs/superpowers/plans/2026-06-15-coding-preflight-pack-dispatch-path.md +0 -504
  95. package/docs/superpowers/plans/2026-06-15-internal-skill-migration-final-fixups.md +0 -342
  96. package/docs/superpowers/plans/2026-06-15-internal-skill-migration-fixups.md +0 -258
  97. package/docs/superpowers/plans/2026-06-15-internal-skill-migration-remaining-fixups.md +0 -387
  98. package/docs/superpowers/plans/2026-06-15-internal-skill-resource-migration.md +0 -749
  99. package/docs/superpowers/plans/2026-06-15-worker-prompt-anchor-final-fixups.md +0 -828
  100. package/docs/superpowers/plans/2026-06-15-worker-prompt-header-error-contract.md +0 -490
  101. package/docs/superpowers/plans/2026-06-17-okstra-error-report.md +0 -724
  102. package/docs/superpowers/plans/2026-06-18-subagent-pane-reclaim.md +0 -483
  103. package/docs/superpowers/plans/2026-06-19-agent-operating-standard.md +0 -476
  104. package/docs/superpowers/plans/2026-06-19-okstra-inspect-recap-facet.md +0 -647
  105. package/docs/superpowers/plans/2026-06-20-error-feedback-loop.md +0 -1019
  106. package/docs/superpowers/plans/2026-06-20-run-index-row-normalization.md +0 -583
  107. package/docs/superpowers/plans/2026-06-20-stage-auto-integrate-teardown.md +0 -819
  108. package/docs/superpowers/plans/2026-06-21-okstra-container-local-user-test.md +0 -714
  109. package/docs/superpowers/plans/2026-06-21-release-handoff-local-checkout.md +0 -348
  110. package/docs/superpowers/plans/2026-06-23-implementation-stage-multiselect-chain.md +0 -630
  111. package/docs/superpowers/plans/2026-06-23-implementation-step-commit-granularity.md +0 -274
  112. package/docs/superpowers/plans/2026-06-23-phase-batch-cleanup-enforcement.md +0 -409
  113. package/docs/superpowers/plans/2026-06-24-cross-project-precondition.md +0 -542
  114. package/docs/superpowers/plans/2026-06-24-decision-drafts-render-gap.md +0 -568
  115. package/docs/superpowers/plans/2026-06-24-manual-user-test-section.md +0 -203
  116. package/docs/superpowers/plans/2026-06-24-okstra-container-build-rename.md +0 -525
  117. package/docs/superpowers/specs/2026-05-12-ticket-id-in-reports-design.md +0 -131
  118. package/docs/superpowers/specs/2026-05-15-implementation-plan-verification-design.md +0 -254
  119. package/docs/superpowers/specs/2026-05-20-final-report-language-design.md +0 -383
  120. package/docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md +0 -322
  121. package/docs/superpowers/specs/2026-05-20-okstra-run-prompt-sot-design.md +0 -299
  122. package/docs/superpowers/specs/2026-05-21-improvement-discovery-task-type-design.md +0 -335
  123. package/docs/superpowers/specs/2026-06-02-okstra-run-branch-confirm-step-design.md +0 -113
  124. package/docs/superpowers/specs/2026-06-02-okstra-run-phase-pane-cleanup-design.md +0 -173
  125. package/docs/superpowers/specs/2026-06-02-requirements-discovery-fanout-design.md +0 -154
  126. package/docs/superpowers/specs/2026-06-04-adversarial-implementation-planning-design.md +0 -90
  127. package/docs/superpowers/specs/2026-06-04-adversarial-verification-design.md +0 -176
  128. package/docs/superpowers/specs/2026-06-04-coverage-critic-design.md +0 -99
  129. package/docs/superpowers/specs/2026-06-04-stage-splitting-cost-aware-design.md +0 -98
  130. package/docs/superpowers/specs/2026-06-05-acceptance-critic-design.md +0 -90
  131. package/docs/superpowers/specs/2026-06-05-compact-markdown-report-tables-design.md +0 -87
  132. package/docs/superpowers/specs/2026-06-05-wizard-batch-prompts-design.md +0 -121
  133. package/docs/superpowers/specs/2026-06-06-final-verification-whole-task-gate-design.md +0 -126
  134. package/docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md +0 -180
  135. package/docs/superpowers/specs/2026-06-06-vertical-slice-tdd-planning-design.md +0 -179
  136. package/docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md +0 -169
  137. package/docs/superpowers/specs/2026-06-09-executor-model-custom-id-cascade-design.md +0 -66
  138. package/docs/superpowers/specs/2026-06-09-implementation-run-artifact-stage-isolation-design.md +0 -87
  139. package/docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-design.md +0 -168
  140. package/docs/superpowers/specs/2026-06-10-concurrent-run-team-guard-design.md +0 -107
  141. package/docs/superpowers/specs/2026-06-10-git-reconcile-stale-sha-recovery-design.md +0 -105
  142. package/docs/superpowers/specs/2026-06-10-lead-worker-completion-polling-design.md +0 -113
  143. package/docs/superpowers/specs/2026-06-10-stage-group-handoff-design.md +0 -156
  144. package/docs/superpowers/specs/2026-06-11-brief-entry-only-handoff-stage-entry-design.md +0 -158
  145. package/docs/superpowers/specs/2026-06-11-fix-cycle-design.md +0 -94
  146. package/docs/superpowers/specs/2026-06-11-wizard-whole-task-final-verification-design.md +0 -89
  147. package/docs/superpowers/specs/2026-06-12-codex-lead-adapter-design.md +0 -358
  148. package/docs/superpowers/specs/2026-06-12-html-plan-approval-design.md +0 -85
  149. package/docs/superpowers/specs/2026-06-12-stage-discipline-rule-design.md +0 -108
  150. package/docs/superpowers/specs/2026-06-13-forbidden-actions-ssot-design.md +0 -134
  151. package/docs/superpowers/specs/2026-06-13-neutral-tmux-lead-adapter-design.md +0 -284
  152. package/docs/superpowers/specs/2026-06-14-host-runtime-auto-execution-design.md +0 -404
  153. package/docs/superpowers/specs/2026-06-17-okstra-error-report-design.md +0 -123
  154. package/docs/superpowers/specs/2026-06-18-subagent-pane-reclaim-design.md +0 -150
  155. package/docs/superpowers/specs/2026-06-19-agent-operating-standard-design.md +0 -120
  156. package/docs/superpowers/specs/2026-06-19-okstra-inspect-recap-facet-design.md +0 -96
  157. package/docs/superpowers/specs/2026-06-20-error-feedback-loop-design.md +0 -171
  158. package/docs/superpowers/specs/2026-06-20-run-index-row-normalization-design.md +0 -112
  159. package/docs/superpowers/specs/2026-06-20-stage-auto-integrate-teardown-design.md +0 -145
  160. package/docs/superpowers/specs/2026-06-21-okstra-container-local-user-test-design.md +0 -125
  161. package/docs/superpowers/specs/2026-06-21-release-handoff-local-checkout-design.md +0 -113
  162. package/docs/superpowers/specs/2026-06-23-implementation-stage-multiselect-chain-design.md +0 -138
  163. package/docs/superpowers/specs/2026-06-23-implementation-step-commit-granularity-design.md +0 -120
  164. package/docs/superpowers/specs/2026-06-24-cross-project-precondition-design.md +0 -129
  165. package/docs/superpowers/specs/2026-06-24-decision-drafts-render-gap-design.md +0 -185
  166. package/docs/superpowers/specs/2026-06-24-manual-user-test-section-design.md +0 -121
  167. package/docs/superpowers/specs/2026-06-24-okstra-container-build-rename-design.md +0 -110
@@ -1,42 +0,0 @@
1
- # Task 1 실측 결과 — self-scheduled 워커 완료 폴링
2
-
3
- - 실측일: 2026-06-10
4
- - 환경: interactive Claude Code 세션 (메인 lead 역할)
5
- - 관련: [plan](2026-06-10-lead-worker-completion-polling.md) Task 1, [spec](../specs/2026-06-10-lead-worker-completion-polling-design.md) §5
6
-
7
- ## 실험 1 — harness-tracked background 완료 → 정지 lead 자동 재개
8
-
9
- - 절차: `Bash(run_in_background:true)` 로 "30초 후 결과 파일 작성 + DONE 출력" task(`bvdjebqzw`)를 띄우고, **ScheduleWakeup/cron 등 추가 장치 없이** lead 턴을 종료.
10
- - 관측: 30초 뒤 background task 완료 시, **사용자 입력 없이** harness 가 `<task-notification>` 으로 lead 를 자동 재개시킴.
11
- - 판정: **성공.** harness-tracked background 완료는 정지 lead 를 자동으로 깨운다. mailbox/idle 알림(누락 위험)에 의존하지 않는 신뢰성 있는 재개 채널이다.
12
-
13
- ## 실험 2 — 복수 워커 단일 스케줄 until-loop 폴링
14
-
15
- - 절차: 단일 `Bash(run_in_background:true)` task(`bh9mfrp3n`) 안에서 워커 2개를 시차(8초/22초)로 띄우고, 하나의 `until [ -f wA ] && [ -f wB ]; do sleep 3; done` 루프로 둘 다 대기.
16
- - 관측: 출력 `BOTH WORKERS DETECTED at 02:55:50 — wA=A wB=B`. 단일 스케줄이 복수 워커 결과 파일을 모두 감지하고 완료 → 자동 재개.
17
- - 판정: **성공.** 워커가 N개여도 단일 background 폴링이 전원의 결과 파일을 추적할 수 있다.
18
-
19
- ## 메커니즘 확정 — `Bash run_in_background` + `until` 루프
20
-
21
- cron / Monitor 가 아니라 **`Bash(run_in_background:true)` + `until`-조건 루프**가 채택 메커니즘이다.
22
-
23
- 근거:
24
- - Monitor 도구 설명이 단일 완료 알림("tell me when X is ready")에 대해 명시적으로 이 패턴을 권장한다: *"use Bash with run_in_background and a command that exits when the condition is true, e.g. `until grep -q "Ready in" dev.log; do sleep 0.5; done`"*. Monitor 는 **반복** 이벤트용, cron 은 **주기 재실행**용이라 단일 워커-완료 알림엔 과하다.
25
- - background task 는 완료되면 사라지므로 spec §4.3 의 "스케줄 해제 / 좀비 cron 방지" 부담이 **원천 소멸**한다. 종료 lifecycle 이 cron 대비 훨씬 단순해진다.
26
- - `until ...; do sleep N; done` 의 `sleep` 은 background 컨텍스트에서 허용된다 (foreground sleep 만 harness 가 차단). 실험 2 에서 `sleep 3` 으로 확인.
27
-
28
- ## 게이트 판정
29
-
30
- **통과.** 방향 C 채택. 메커니즘 = `Bash run_in_background` + `until` 루프.
31
-
32
- ## 후속 반영 사항 (spec/plan 갱신 필요)
33
-
34
- - spec §4.4 "Monitor vs cron" → "`Bash run_in_background` + `until` 루프" 로 확정. Monitor/cron 은 폴백/대안으로 격하.
35
- - spec §4.3 종료 lifecycle → cron 해제 항목 제거(background task 자가 소멸). "deadline 초과" 는 until-loop 에 wall-clock 상한(`SECONDS` 가드)으로 구현. soft timeout 표는 유지.
36
- - plan `<WAKEUP>` = `Bash run_in_background` + `until` 루프 폴링 스크립트.
37
- - plan Task 7(self-wakeup 도구 권한 seed) → **불필요.** `Bash(run_in_background)` 는 이미 권한 내. settings.template.json 변경 없음.
38
-
39
- ## 미확인 (정적 가정, 추가 실측 권장)
40
-
41
- - 본 실측은 메인 interactive 세션. okstra.sh spawn 경로도 interactive([scripts/okstra.sh:173](../../../scripts/okstra.sh), `-p` 없음)이므로 동일 동작 기대하나, okstra.sh 가 띄운 lead 세션에서 background 자동 재개를 1회 교차 확인하면 완전.
42
- - teammate(Agent) 워커가 비동기로 결과 파일을 쓰는 것 + background 폴링이 그 파일을 stat 으로 감지하는 것은 자명(기존 okstra 워커 동작 + 파일 존재 검사)하여 별도 실측은 생략. 워커 종류(in-process/teammate/CLI wrapper)와 폴링 메커니즘은 독립이다.
@@ -1,337 +0,0 @@
1
- # Lead-Worker 완료 인지 (self-scheduled 폴링) Implementation Plan
2
-
3
- > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
-
5
- **Goal:** okstra lead 가 비동기 dispatch 한 워커의 완료를 mailbox/idle 알림 없이 self-scheduled 폴링으로 스스로 인지해, 사용자의 수동 nudge 없이 다음 phase 로 진행하게 만든다.
6
-
7
- **Architecture:** lead 는 워커를 기존대로 비동기 dispatch 한 뒤 단일 self-wakeup 스케줄을 걸고 턴을 종료한다. 깨어날 때마다 dispatch 한 워커 전원의 `worker-results` 파일 출현+헤더 검증으로 완료를 직접 확인하고, 전원 완료(또는 워커별 deadline 초과) 시 스케줄을 해제하고 진행한다. 변경은 코드가 아니라 프롬프트/SKILL 명세 레이어 중심이다.
8
-
9
- **Tech Stack:** Claude Code Agent Teams, Monitor 툴 / scheduled-tasks(cron, `/loop`), bash 검증 스크립트, okstra SKILL markdown.
10
-
11
- **설계 출처:** [docs/superpowers/specs/2026-06-10-lead-worker-completion-polling-design.md](../specs/2026-06-10-lead-worker-completion-polling-design.md)
12
-
13
- ---
14
-
15
- ## ⚠️ BLOCKING 게이트
16
-
17
- **Task 1 (실측)이 통과하지 않으면 Task 2~9 를 진행하지 않는다.** Task 1 에서 "self-wakeup 이 정지 lead 를 재개시키지 못한다"가 확인되면, 이 plan 전체를 폐기하고 spec §3 의 **방향 A(`team_name` 없는 foreground 동기 dispatch)** 로 별도 plan 을 작성한다. 방향 A 는 공식 문서가 명시적으로 보장하는 유일한 폴백이다.
18
-
19
- > **갱신 (2026-06-10): Task 1 통과** ([PROBE](2026-06-10-lead-worker-completion-polling-PROBE.md)). 채택 메커니즘 = **`Bash run_in_background` + `until` 루프**. 아래 모든 Task 의 `<WAKEUP>` 표기는 이 패턴으로 치환한다:
20
- > ```bash
21
- > # lead 가 워커 dispatch 직후 run_in_background:true 로 띄우는 폴링 스크립트
22
- > deadline=$((SECONDS + <per_worker_deadline_seconds>))
23
- > until [ -f "<result_path_A>" ] && [ -f "<result_path_B>" ] ...; do
24
- > [ $SECONDS -ge $deadline ] && { echo "POLL_TIMEOUT"; exit 1; }
25
- > sleep 5
26
- > done
27
- > echo "ALL_WORKERS_DONE"
28
- > ```
29
- > 완료(또는 timeout exit) 시 harness 가 lead 를 자동 재개한다. **Task 7(self-wakeup 도구 권한 seed)은 불필요** — `Bash(run_in_background)` 는 이미 권한 내이고, background task 는 완료 시 자가 소멸하므로 도구 권한 추가·스케줄 해제 lifecycle 이 없다. Task 2 의 종료 lifecycle 에서 "cron 해제"는 "background task 자가 소멸"로 대체하고, deadline 은 위 `SECONDS` 가드로 구현한다.
30
-
31
- ---
32
-
33
- ## File Structure
34
-
35
- | 파일 | 책임 | 변경 |
36
- |---|---|---|
37
- | `docs/superpowers/plans/2026-06-10-lead-worker-completion-polling-PROBE.md` | Task 1 실측 결과 기록 | Create |
38
- | `agents/SKILL.md` | Phase 4/5/6 dispatch 후 완료 폴링 루프 명세, 동기 전제 문구 정정 | Modify |
39
- | `agents/workers/claude-worker.md` | "Agent() call blocks" 동기 전제 정정 | Modify |
40
- | `skills/okstra-report-writer/SKILL.md` | Phase 6 dispatch 후 완료 폴링 명세 | Modify |
41
- | `skills/okstra-team-contract/SKILL.md` | worker-completion 폴링 규약 + soft timeout terminal status | Modify |
42
- | `skills/okstra-convergence/SKILL.md` | 라운드별 reverify 집합 폴링 적용 | Modify |
43
- | `templates/reports/settings.template.json` | self-wakeup 도구 권한 seed | Modify |
44
- | `agents/TODO.md` | 수정 B/C 해소 표시 | Modify |
45
- | `tests-e2e/scenario-<id>-worker-completion-polling.sh` | 폴링 종료 lifecycle e2e | Create |
46
-
47
- 명세 변경의 SSOT 는 `agents/SKILL.md` + `skills/okstra-team-contract/SKILL.md` 이며, 나머지 SKILL 은 그 규약을 참조한다 (DRY — 폴링 알고리즘을 여러 파일에 복붙하지 않는다).
48
-
49
- ---
50
-
51
- ### Task 1: 실측 검증 게이트 (BLOCKING — 메커니즘 확정)
52
-
53
- **목적:** spec §5 의 세 가지를 interactive 세션에서 실측해 self-wakeup 메커니즘(Monitor vs cron)을 확정한다. 이 Task 는 명세를 바꾸지 않는다 — 오직 런타임 동작을 관측해 기록한다.
54
-
55
- **Files:**
56
- - Create: `docs/superpowers/plans/2026-06-10-lead-worker-completion-polling-PROBE.md`
57
-
58
- - [ ] **Step 1: 비동기 워커 + cron self-wakeup 재개 실측**
59
-
60
- interactive Claude Code 세션에서:
61
- 1. `team_name` 을 포함한 `Agent(...)` 로 더미 워커를 띄운다. 워커 프롬프트: "sleep 90 후 `/tmp/okstra-probe/worker-A.done` 에 `done` 을 써라" (background Bash 사용).
62
- 2. dispatch 직후, cron(`/loop` 또는 `CronCreate`)으로 1분 간격 self-wakeup 을 건다. wakeup 프롬프트: "`/tmp/okstra-probe/worker-A.done` 이 있으면 'PROBE: detected' 출력 후 cron 해제, 없으면 'PROBE: waiting' 출력".
63
- 3. lead 턴을 종료한다 (추가 입력 없이).
64
-
65
- 관측 기준:
66
- - 사용자 입력 **없이** lead 가 1분 후 자동으로 깨어나 'PROBE: waiting' 을 출력하는가?
67
- - 파일 출현 후 깨어남에서 'PROBE: detected' 를 출력하고 cron 을 해제하는가?
68
-
69
- - [ ] **Step 2: Monitor 툴 재개 실측**
70
-
71
- 같은 더미 워커 시나리오를 Monitor 툴로 반복:
72
- 1. `Agent(team_name: …)` 로 더미 워커 dispatch.
73
- 2. Monitor 로 `bash -c 'until [ -f /tmp/okstra-probe/worker-A.done ]; do sleep 2; done; echo READY'` 를 건다 (Monitor 가 sleep 제약 우회/스트리밍을 어떻게 다루는지 관측).
74
- 3. lead 턴 종료.
75
-
76
- 관측 기준: Monitor 가 `READY` 라인을 스트리밍해 lead 를 자동 재개시키는가? cron 대비 토큰/반응 차이는?
77
-
78
- - [ ] **Step 3: 복수 워커 집합 폴링 실측**
79
-
80
- 워커 2개(`worker-A.done`, `worker-B.done`)를 서로 다른 sleep(60s, 120s)으로 띄우고, Step 1 또는 Step 2 의 승자 메커니즘으로 **단일 스케줄이 두 파일을 모두 추적**하는지 확인. 한 개만 끝났을 때 'PROBE: partial (A done, B waiting)', 둘 다 끝나면 해제.
81
-
82
- - [ ] **Step 4: 결과 기록**
83
-
84
- `...-PROBE.md` 에 기록:
85
- - cron 자동 재개: 성공/실패 (관측 근거)
86
- - Monitor 자동 재개: 성공/실패 (관측 근거)
87
- - 복수 워커 단일-스케줄 폴링: 성공/실패
88
- - **채택 메커니즘** (Monitor 우선, 실패 시 cron, 둘 다 실패 시 방향 A 전환)
89
- - headless 경로 주의: 본 실측은 interactive 한정. okstra.sh spawn 도 interactive([scripts/okstra.sh:173](../../../scripts/okstra.sh))이므로 동일 가정하되, 가능하면 okstra.sh spawn 으로 1회 교차 확인.
90
-
91
- - [ ] **Step 5: 게이트 판정 + 커밋**
92
-
93
- ```bash
94
- git add docs/superpowers/plans/2026-06-10-lead-worker-completion-polling-PROBE.md
95
- git commit -m "test(run): self-scheduled 워커 완료 폴링 실측 결과 기록"
96
- ```
97
-
98
- 판정: 채택 메커니즘이 정해지면 Task 2 로 진행. 둘 다 실패면 STOP — 방향 A plan 작성으로 전환하고 사용자에게 보고.
99
-
100
- ---
101
-
102
- ### Task 2: 완료 폴링 규약 정의 (team-contract SSOT)
103
-
104
- **전제:** Task 1 에서 채택된 메커니즘을 `<WAKEUP>` 로 표기. 아래 명세의 self-wakeup 도구 호출만 Task 1 승자로 치환한다. 폴링 알고리즘·종료 lifecycle·복수 워커 집합 로직은 메커니즘 무관하게 동일하다.
105
-
106
- **Files:**
107
- - Modify: `skills/okstra-team-contract/SKILL.md` (신규 섹션 "Worker-completion detection (self-scheduled polling)")
108
-
109
- - [ ] **Step 1: 규약 본문 작성**
110
-
111
- 다음 내용을 새 섹션으로 추가한다 (정확한 문안은 작성 시 SKILL 톤에 맞춤):
112
-
113
- ```markdown
114
- ## Worker-completion detection (self-scheduled polling)
115
-
116
- Lead dispatches workers asynchronously (Agent with team_name returns
117
- `Spawned successfully` immediately — NOT a completion). Lead MUST NOT
118
- treat the spawn ack as completion, and MUST NOT end its turn with a
119
- prose "waiting for ..." statement. Instead:
120
-
121
- 1. Record the dispatched workers' Result Paths as the **pending set**
122
- (from run-manifest / launch prompt `**Result Path:**`).
123
- 2. Arm a SINGLE self-wakeup via <WAKEUP> (one schedule for ALL workers,
124
- not one per worker).
125
- 3. End the turn.
126
- 4. On each wakeup, for every path still in the pending set: verify the
127
- file exists AND passes the standardized worker-result header check.
128
- Move passing workers to the **done set**.
129
- 5. Termination:
130
- - pending set empty → disarm <WAKEUP>, proceed to next phase.
131
- - a worker exceeds its per-worker deadline (see soft-timeout below)
132
- → record `timeout`, remove from pending set, redispatch-once or
133
- proceed.
134
- - any error/abort path → ALWAYS disarm <WAKEUP> (no zombie schedule).
135
- 6. Per-worker soft timeout: 2× the task-type expected duration table
136
- below. (Supersedes TODO.md 수정 B.)
137
-
138
- | Task type | Expected per-worker | Deadline (2×) |
139
- |---|---|---|
140
- | requirements-discovery | 10 min | 20 min |
141
- | error-analysis | 15 min | 30 min |
142
- | implementation-planning | 20 min | 40 min |
143
- | implementation | 20 min | 40 min |
144
- | final-verification | 10 min | 20 min |
145
- ```
146
-
147
- - [ ] **Step 2: 일관성 grep**
148
-
149
- ```bash
150
- grep -rn "Spawned successfully\|self-scheduled\|pending set\|Worker-completion detection" skills/okstra-team-contract/SKILL.md
151
- ```
152
- Expected: 새 섹션이 단일 위치에 존재. 다른 SKILL 에 폴링 알고리즘 중복 없음.
153
-
154
- - [ ] **Step 3: 커밋**
155
-
156
- ```bash
157
- git add skills/okstra-team-contract/SKILL.md
158
- git commit -m "feat(skills/okstra-team-contract): 워커 완료 self-scheduled 폴링 규약 정의"
159
- ```
160
-
161
- ---
162
-
163
- ### Task 3: 동기 전제 문구 정정 (claude-worker + SKILL)
164
-
165
- **Files:**
166
- - Modify: `agents/workers/claude-worker.md:87-89` (Stop Condition)
167
- - Modify: `agents/SKILL.md:381` (Common Mistakes 항목)
168
-
169
- - [ ] **Step 1: claude-worker.md 정정**
170
-
171
- `agents/workers/claude-worker.md:89` 의 "Lead's `Agent()` call blocks until you return your final assistant message." 는 `team_name` dispatch 에서 거짓이다. 다음으로 교체:
172
-
173
- ```markdown
174
- You are an in-process Claude subagent. When dispatched with `team_name`
175
- (Teams mode), Lead's `Agent()` call returns `Spawned successfully`
176
- immediately and does NOT block on your completion — Lead detects your
177
- completion via self-scheduled polling of your worker-results file
178
- (see okstra-team-contract "Worker-completion detection"). Therefore you
179
- MUST write your worker-results file at the canonical Result Path before
180
- returning; that file's appearance is the ONLY signal Lead uses.
181
- ```
182
-
183
- - [ ] **Step 2: SKILL.md:381 정정**
184
-
185
- "when the Agent call finally returns" 전제를 self-scheduled 폴링으로 갱신하고, heartbeat sidecar 규칙은 보조 liveness 신호로 유지하되 "완료 인지 = 결과 파일 출현"으로 명확히 한다.
186
-
187
- - [ ] **Step 3: 일관성 grep**
188
-
189
- ```bash
190
- grep -rn "blocks until you return\|Agent call finally returns\|call blocks" agents/
191
- ```
192
- Expected: 동기-blocking 전제 문구가 더 이상 남아있지 않음 (0 hits, 또는 의도된 foreground 맥락만).
193
-
194
- - [ ] **Step 4: 커밋**
195
-
196
- ```bash
197
- git add agents/workers/claude-worker.md agents/SKILL.md
198
- git commit -m "fix(agents): Agent dispatch 동기-blocking 전제를 비동기-폴링으로 정정"
199
- ```
200
-
201
- ---
202
-
203
- ### Task 4: Phase 4/5 dispatch 후 폴링 루프 명세 (agents/SKILL.md)
204
-
205
- **Files:**
206
- - Modify: `agents/SKILL.md` (Phase 4/5 실행 섹션, 대략 219-249)
207
-
208
- - [ ] **Step 1: 폴링 진입 명세 추가**
209
-
210
- Phase 4/5 dispatch 직후, lead 가 okstra-team-contract "Worker-completion detection" 규약에 따라 self-wakeup 폴링을 무장하고 턴을 종료하도록 명시. PROGRESS 체크포인트 추가:
211
-
212
- ```markdown
213
- - `PROGRESS: phase-5-poll pending=<n> done=<m>` — emitted on each wakeup
214
- while the pending set is non-empty.
215
- ```
216
-
217
- DRY: 폴링 알고리즘은 team-contract SSOT 를 참조만 한다 (복붙 금지).
218
-
219
- - [ ] **Step 2: 일관성 grep + 커밋**
220
-
221
- ```bash
222
- grep -rn "phase-5-poll\|Worker-completion detection" agents/SKILL.md
223
- git add agents/SKILL.md
224
- git commit -m "feat(agents): Phase 4/5 워커 dispatch 후 완료 폴링 진입 명세"
225
- ```
226
-
227
- ---
228
-
229
- ### Task 5: Phase 6 report-writer 폴링 명세 (okstra-report-writer)
230
-
231
- **Files:**
232
- - Modify: `skills/okstra-report-writer/SKILL.md` (Phase 6 dispatch template 직후)
233
-
234
- - [ ] **Step 1: dispatch 후 폴링 명세**
235
-
236
- [skills/okstra-report-writer/SKILL.md:27-41](../../../skills/okstra-report-writer/SKILL.md) 의 dispatch 템플릿 뒤에, "dispatch 후 report-writer 의 data.json + worker-results 파일 출현을 team-contract 규약대로 폴링하여 완료를 인지한다. spawn ack 를 완료로 착각하지 말 것" 을 추가.
237
-
238
- - [ ] **Step 2: 일관성 grep + 커밋**
239
-
240
- ```bash
241
- grep -rn "Worker-completion detection\|Spawned successfully" skills/okstra-report-writer/SKILL.md
242
- git add skills/okstra-report-writer/SKILL.md
243
- git commit -m "feat(skills/okstra-report-writer): Phase 6 report-writer 완료 폴링 명세"
244
- ```
245
-
246
- ---
247
-
248
- ### Task 6: convergence 라운드 폴링 적용 (okstra-convergence)
249
-
250
- **Files:**
251
- - Modify: `skills/okstra-convergence/SKILL.md` (reverify dispatch 섹션)
252
-
253
- - [ ] **Step 1: 라운드별 집합 폴링 참조 추가**
254
-
255
- 각 convergence 라운드의 reverify dispatch 집합(가변 1~N)에 동일한 team-contract 폴링 규약을 적용한다는 문장 추가. 라운드마다 pending set 이 재구성됨을 명시.
256
-
257
- - [ ] **Step 2: 일관성 grep + 커밋**
258
-
259
- ```bash
260
- grep -rn "Worker-completion detection" skills/okstra-convergence/SKILL.md
261
- git add skills/okstra-convergence/SKILL.md
262
- git commit -m "feat(skills/okstra-convergence): 라운드별 reverify 완료 폴링 적용"
263
- ```
264
-
265
- ---
266
-
267
- ### Task 7: self-wakeup 도구 권한 seed (settings.template.json)
268
-
269
- **Files:**
270
- - Modify: `templates/reports/settings.template.json`
271
-
272
- - [ ] **Step 1: Task 1 승자 도구 권한 추가**
273
-
274
- Task 1 에서 cron 채택 시 `CronCreate`/`CronList`/`CronDelete` 를, Monitor 채택 시 `Monitor` 를 `permissions.allow` 에 추가한다. 사용자 머신 전파를 위해 personal `.claude/` 가 아니라 이 템플릿에 seed (CLAUDE.md artifact-home 규칙).
275
-
276
- - [ ] **Step 2: JSON 유효성 + 커밋**
277
-
278
- ```bash
279
- jq . templates/reports/settings.template.json >/dev/null && echo "valid"
280
- git add templates/reports/settings.template.json
281
- git commit -m "feat(templates): self-wakeup 폴링 도구 권한 seed"
282
- ```
283
-
284
- ---
285
-
286
- ### Task 8: TODO.md 수정 B/C 해소
287
-
288
- **Files:**
289
- - Modify: `agents/TODO.md`
290
-
291
- - [ ] **Step 1: 수정 B/C 항목에 해소 메모**
292
-
293
- "수정 B — Leader-side 워커 soft timeout" 와 "수정 C 후보 — worker-results 파일 폴링 루프" 항목에, 본 plan(self-scheduled 폴링)으로 통합·해소됨을 기록하고 spec/plan 경로를 링크. 변경 이력에 2026-06-10 항목 추가.
294
-
295
- - [ ] **Step 2: 커밋**
296
-
297
- ```bash
298
- git add agents/TODO.md
299
- git commit -m "docs(agents): 워커 완료 폴링으로 TODO 수정 B/C 해소 기록"
300
- ```
301
-
302
- ---
303
-
304
- ### Task 9: e2e 시나리오 + build 검증
305
-
306
- **Files:**
307
- - Create: `tests-e2e/scenario-<id>-worker-completion-polling.sh`
308
- - Test: `bash validators/validate-workflow.sh`, `npm run build`
309
-
310
- - [ ] **Step 1: 종료 lifecycle e2e 작성**
311
-
312
- `tests-e2e/scenario-<id>-<name>.sh` 규약(mktemp OKSTRA_HOME, trap EXIT cleanup)에 따라, 폴링 종료 lifecycle 의 검증 가능한 부분을 스크립트화: pending/done set 추적, deadline 시 timeout 기록, 스케줄 해제 확인. (LLM 비결정 동작은 e2e 가 아니라 Task 1 PROBE 가 담당 — e2e 는 결정적 산출물/상태 전이만 검증.)
313
-
314
- - [ ] **Step 2: 워크플로우 validator + build**
315
-
316
- ```bash
317
- bash validators/validate-workflow.sh
318
- npm run build
319
- node bin/okstra doctor
320
- ```
321
- Expected: validator 통과, build 가 변경된 SKILL/agent/template 을 runtime/ 으로 동기화, doctor 정상.
322
-
323
- - [ ] **Step 3: 커밋**
324
-
325
- ```bash
326
- git add tests-e2e/ runtime/
327
- git commit -m "test(e2e): 워커 완료 폴링 종료 lifecycle 시나리오 + build 동기화"
328
- ```
329
-
330
- ---
331
-
332
- ## Self-Review (작성자 체크)
333
-
334
- - **Spec 커버리지:** §1 문제→Task 1 실측 재현. §3 방향 C→Task 2~7. §4.1 메커니즘→Task 2/4. §4.2 복수 워커→Task 1 Step3 + Task 2. §4.3 종료 lifecycle→Task 2 Step1. §4.4 Monitor/cron→Task 1. §5 실측 게이트→Task 1(BLOCKING). §6 변경 범위→Task 2~9 파일 일치. §7 미해결→Task 1 이 캐시 TTL/Monitor 형태 확정.
335
- - **Placeholder:** `<WAKEUP>` / `<id>` 는 Task 1 결과·시나리오 번호로 채워지는 의도된 변수이며, 그 치환 규칙을 각 Task 에 명시함 (막연한 TODO 아님).
336
- - **타입/이름 일관성:** "pending set" / "done set" / "Worker-completion detection" / `<WAKEUP>` 용어가 Task 2~6 에서 동일하게 사용됨.
337
- - **알려진 한계:** SKILL 명세 변경은 LLM 동작을 *유도*할 뿐 코드로 *강제*하지 못한다 (CLAUDE.md Rule 3). 결정적 강제가 가능한 부분(종료 lifecycle 의 산출물/상태)만 Task 9 e2e 가 검증하고, 나머지는 Task 1 실측 + 실사용 관측에 의존함을 명시.