okstra 0.232.0 → 0.234.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 (205) hide show
  1. package/README.md +19 -283
  2. package/dist/cli-registry.mjs +14 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/trace/capacity.d.mts +12 -0
  10. package/dist/commands/trace/capacity.mjs +21 -0
  11. package/dist/commands/trace/capacity.mjs.map +1 -0
  12. package/dist/commands/trace/model.d.mts +89 -0
  13. package/dist/commands/trace/model.mjs +251 -0
  14. package/dist/commands/trace/model.mjs.map +1 -0
  15. package/dist/commands/trace/progression.d.mts +11 -0
  16. package/dist/commands/trace/progression.mjs +194 -0
  17. package/dist/commands/trace/progression.mjs.map +1 -0
  18. package/dist/commands/trace/review.d.mts +7 -0
  19. package/dist/commands/trace/review.mjs +51 -0
  20. package/dist/commands/trace/review.mjs.map +1 -0
  21. package/dist/commands/trace/task-link.d.mts +18 -0
  22. package/dist/commands/trace/task-link.mjs +72 -0
  23. package/dist/commands/trace/task-link.mjs.map +1 -0
  24. package/dist/commands/trace/trace.d.mts +1 -0
  25. package/dist/commands/trace/trace.mjs +293 -0
  26. package/dist/commands/trace/trace.mjs.map +1 -0
  27. package/dist/lib/bounded-file.d.mts +1 -0
  28. package/dist/lib/bounded-file.mjs +36 -0
  29. package/dist/lib/bounded-file.mjs.map +1 -0
  30. package/dist/lib/config-store.d.mts +34 -0
  31. package/dist/lib/config-store.mjs +70 -0
  32. package/dist/lib/config-store.mjs.map +1 -0
  33. package/dist/lib/file-lock.mjs +4 -5
  34. package/dist/lib/file-lock.mjs.map +1 -1
  35. package/dist/lib/input-limit.d.mts +4 -0
  36. package/dist/lib/input-limit.mjs +8 -0
  37. package/dist/lib/input-limit.mjs.map +1 -0
  38. package/dist/lib/memory-auto-register.mjs +2 -17
  39. package/dist/lib/memory-auto-register.mjs.map +1 -1
  40. package/dist/lib/report-language-tag.d.mts +1 -0
  41. package/dist/lib/report-language-tag.mjs +4 -0
  42. package/dist/lib/report-language-tag.mjs.map +1 -0
  43. package/dist/lib/report-language.d.mts +1 -0
  44. package/dist/lib/report-language.mjs +50 -0
  45. package/dist/lib/report-language.mjs.map +1 -0
  46. package/dist/lib/skill-catalog.mjs +3 -0
  47. package/dist/lib/skill-catalog.mjs.map +1 -1
  48. package/docs/architecture/storage-model.md +55 -5
  49. package/docs/architecture.md +10 -4
  50. package/docs/cli.md +320 -3
  51. package/docs/contributor-change-matrix.md +1 -2
  52. package/docs/project-structure-overview.md +34 -43
  53. package/package.json +1 -1
  54. package/runtime/BUILD.json +2 -2
  55. package/runtime/agents/operations/trace-interface-review.json +6 -0
  56. package/runtime/agents/operations/trace-scope-review.json +6 -0
  57. package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
  58. package/runtime/prompts/coding-preflight/clean-code.md +18 -20
  59. package/runtime/prompts/coding-preflight/overview.md +1 -1
  60. package/runtime/prompts/duties/code-reviewer.json +1 -1
  61. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  62. package/runtime/prompts/host-orchestration/README.md +18 -9
  63. package/runtime/prompts/launch.template.md +3 -2
  64. package/runtime/prompts/lead/context-loader.md +2 -0
  65. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  66. package/runtime/prompts/lead/report-writer.md +6 -6
  67. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
  68. package/runtime/prompts/profiles/_common-contract.md +1 -1
  69. package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
  70. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
  71. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  72. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
  73. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  74. package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
  75. package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
  76. package/runtime/python/okstra_ctl/business_flow/cli.py +60 -6
  77. package/runtime/python/okstra_ctl/business_flow/contracts.py +12 -1
  78. package/runtime/python/okstra_ctl/business_flow/engine.py +17 -5
  79. package/runtime/python/okstra_ctl/business_flow/history.py +60 -0
  80. package/runtime/python/okstra_ctl/business_flow/source.py +35 -2
  81. package/runtime/python/okstra_ctl/business_flow/store.py +51 -14
  82. package/runtime/python/okstra_ctl/business_flow/sweep.py +124 -0
  83. package/runtime/python/okstra_ctl/code_review_census.py +93 -2
  84. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  85. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  86. package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
  87. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  88. package/runtime/python/okstra_ctl/code_review_target.py +140 -15
  89. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  90. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  91. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  92. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  93. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  94. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  95. package/runtime/python/okstra_ctl/doyouknow/cli.py +9 -9
  96. package/runtime/python/okstra_ctl/doyouknow/config.py +2 -2
  97. package/runtime/python/okstra_ctl/doyouknow/group_view.py +152 -0
  98. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +4 -3
  99. package/runtime/python/okstra_ctl/doyouknow/source_store.py +2 -2
  100. package/runtime/python/okstra_ctl/doyouknow/sources/business.py +116 -0
  101. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
  102. package/runtime/python/okstra_ctl/doyouknow/sync.py +34 -9
  103. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  104. package/runtime/python/okstra_ctl/fixed_text.py +10 -0
  105. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  106. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  107. package/runtime/python/okstra_ctl/json_boundary.py +33 -6
  108. package/runtime/python/okstra_ctl/manager_cli.py +122 -1
  109. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  110. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  111. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  112. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  113. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  114. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  115. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  116. package/runtime/python/okstra_ctl/manager_sync.py +42 -3
  117. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  118. package/runtime/python/okstra_ctl/material.py +2 -0
  119. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  120. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  121. package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
  122. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  123. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  124. package/runtime/python/okstra_ctl/paths.py +6 -1
  125. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  126. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  127. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
  128. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  129. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  130. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  131. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
  132. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  133. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  134. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
  135. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  136. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  137. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  138. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  139. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  140. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  141. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  142. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  143. package/runtime/python/okstra_ctl/project_group.py +175 -0
  144. package/runtime/python/okstra_ctl/project_group_cli.py +62 -0
  145. package/runtime/python/okstra_ctl/render.py +28 -2
  146. package/runtime/python/okstra_ctl/report_assembly.py +38 -11
  147. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  148. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  149. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  150. package/runtime/python/okstra_ctl/report_language.py +4 -1
  151. package/runtime/python/okstra_ctl/report_narrative.py +179 -7
  152. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  153. package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
  154. package/runtime/python/okstra_ctl/run.py +43 -35
  155. package/runtime/python/okstra_ctl/run_context.py +10 -1
  156. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  157. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  158. package/runtime/python/okstra_ctl/task_query.py +239 -0
  159. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  160. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  161. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  162. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  163. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  164. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  165. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  166. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  167. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  168. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  169. package/runtime/python/okstra_project/state.py +20 -0
  170. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  171. package/runtime/python/okstra_token_usage/cli.py +23 -10
  172. package/runtime/python/okstra_token_usage/collect.py +25 -22
  173. package/runtime/python/okstra_token_usage/policy.py +193 -0
  174. package/runtime/schemas/business-flow-v1.schema.json +3 -0
  175. package/runtime/schemas/doyouknow-config-v1.schema.json +1 -1
  176. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  177. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  178. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  179. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  180. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  181. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  182. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  183. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  184. package/runtime/skills/okstra-code-review/SKILL.md +58 -50
  185. package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
  186. package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
  187. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  188. package/runtime/skills/okstra-explain-flow/SKILL.md +33 -4
  189. package/runtime/skills/okstra-manager/SKILL.md +24 -0
  190. package/runtime/skills/okstra-memory/SKILL.md +1 -1
  191. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  192. package/runtime/skills/okstra-run/SKILL.md +55 -183
  193. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  194. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  195. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  196. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  197. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  198. package/runtime/templates/doyouknow/group-view.css +103 -0
  199. package/runtime/templates/doyouknow/group-view.js +317 -0
  200. package/runtime/templates/doyouknow/group-view.template.html +72 -0
  201. package/runtime/templates/manager/view.template.html +4 -0
  202. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  203. package/runtime/templates/trace/trace.template.md +42 -0
  204. package/runtime/validators/checks/fixtures-02.py +25 -33
  205. package/runtime/validators/validate-run.py +93 -36
package/docs/cli.md CHANGED
@@ -1,3 +1,214 @@
1
+ # okstra-run 입력 형식과 사용량 정책
2
+
3
+ 새 실행은 run manifest에 `reportAuthoringFormat: "json-v1"`과 `usageAccountingPolicy: "advisory"`를 기록한다. 작성자 입력은 `reportNarrativePath`의 `.json` 파일에 허용된 작성자 소유 값만 쓰며, 설명 문자열에는 Markdown을 사용할 수 있다. 최종 보고서의 `schemaVersion`과 `reportContractVersion`은 `3.0`을 유지한다. 필드가 없는 기존 실행은 `markdown-v1`·`strict`로 읽으며, 알 수 없는 값은 거부한다.
4
+
5
+ `json-v1` 작성자 입력은 UTF-8 2,000,000바이트, 루트를 0으로 세고 스칼라 값을 포함한 깊이 32까지 받는다. 소유권 검사에서 방문한 필드 경로의 누적 길이는 64,000,000문자까지 허용한다. 초과·재귀 오류는 작성자 입력 결함으로 처리하며, 교정 결과도 같은 크기 제한을 통과한 뒤 게시한다. 보존된 교정 기준은 worker 결과 디렉터리의 일반 파일이어야 하고 심볼릭 링크는 거부한다. 이 한도는 작성자 JSON의 판독·교정 계약이며 최종 `data.json`의 크기 제한은 아니다.
6
+
7
+ 다음 작성 중 입력 소비 명령은 선택 인자 `--run-manifest`를 받는다. 새 JSON 입력을 읽을 때는 해당 실행의 manifest를 함께 전달한다. 인자를 생략한 기존 호출은 Markdown 입력 경로를 유지하며, 확장자만 보고 JSON으로 전환하지 않는다. JSON 입력 경로는 manifest의 `reportNarrativePath`와 일치해야 한다.
8
+
9
+ ```bash
10
+ okstra plan-items extract --run-manifest <run-manifest> --narrative <writer-input> --output <items.json>
11
+ okstra plan-items validate --run-manifest <run-manifest> --narrative <writer-input> --items <items.json>
12
+ okstra option-votes gaps --task-manifest <task-manifest> --run-manifest <run-manifest> --narrative <writer-input> --json
13
+ okstra design-snapshot --run-manifest <run-manifest> --narrative <writer-input> --output <design-preparation.json>
14
+ okstra incremental-carry --run-manifest <run-manifest> --prev-data <previous.data.json> --cur-narrative <writer-input> --state <state.json> --prev-seq <seq> --carry-stages <csv> --reverify-stages <csv> --out-state <state.json>
15
+ ```
16
+
17
+ `okstra token-usage <team-state> --write`는 해당 실행의 manifest에서 사용량 정책을 읽는다. `advisory`는 원인이 확인된 세션·청구량 부재를 진단으로 기록한다. 수집기의 기존 카운터는 유지하고, 보고서를 조립할 때 미수집 값과 불완전 합계를 `null`로 투영한다. 그 부재만으로 실제 작업 검증을 실패시키지는 않는다. 수집 생략·잘못된 값·귀속 모호성·예상하지 못한 수집 오류는 계속 실패한다. 게시 후 재수집하거나 `--substitute-data <data.json>`을 지정해도 `advisory` 실행의 게시된 보고서는 덮어쓰지 않는다. `--write`를 사용한 재수집 결과는 team-state에 보존되며, `strict` 실행은 기존 동작을 유지한다.
18
+
19
+ 호스트 지침은 wizard 확인 후 `orchestration.hostRulesPath`가 비어 있지 않을 때 첫 `render-bundle` 전에 읽는다. `implementation`·`implementation-planning`만 이 경로를 반환하며, 선언된 파일 누락은 오류다. 준비 후에는 동결 사본을 사용한다. [okstra-run 사용 규약](skills/okstra-run.md)과 [저장 계약](architecture/storage-model.md)을 함께 참고한다.
20
+
21
+ # 실행 묶음 준비
22
+
23
+ `okstra render-bundle`은 입력·지침·실행 기록을 준비하고 리드에게 제어를 넘깁니다. 새 리드 프로세스를 실행하지 않습니다. 입력 마법사에서 확정한 상태 파일을 직접 전달할 수 있습니다.
24
+
25
+ ```bash
26
+ okstra render-bundle --wizard-state-file <absolute-path> --summary-only
27
+ okstra render-bundle --wizard-state-file <absolute-path> --stage <confirmed-stage> --summary-only
28
+ ```
29
+
30
+ `--wizard-state-file`은 절대 경로를 받습니다. 코드는 상태를 한 번 판독하여 확정 여부·승인 범위를 확인하고, 역할·모델·반복 인자·빈 문자열을 기존 준비 함수에 전달합니다. 별도로 `--task-type`, `--task-brief`, `--role-model`, `--lead-runtime` 등을 섞으면 오류를 반환합니다. 기존 직접 인자 방식과 읽기 전용 `okstra wizard outcome --state-file <path>` 조회는 계속 지원합니다.
31
+
32
+ 상태 파일 방식에서 추가할 수 있는 옵션은 출력 제어 `--summary-only`, 승인된 구현 연속 실행 안의 `--stage`, 기존 별도 사용자 확인을 거친 `--tdd-bypass`와 `--qa-waiver`입니다. 단계 선택은 기존 승인 범위로 제한하며, 두 면제 옵션은 기존 태스크 제한과 원장 검사를 그대로 따릅니다. 작업 준비에 필요한 호스트 실행 권한은 입력 마법사의 사용자 승인과 별개입니다.
33
+
34
+ `release-handoff`의 PR 템플릿 저장 요청은 확정된 프로젝트 루트와 저장 범위를 사용합니다. 저장 요청을 검증한 뒤 설정을 저장하며, 저장에 실패하면 실행 준비를 시작하지 않습니다. 설정 저장 후 준비가 실패하면 설정은 남고 오류 출력에서 그 사실을 알립니다. 자동으로 이전 값을 덮어쓰는 복구는 수행하지 않습니다.
35
+
36
+ 새 확인 기록에는 설정의 키·값·저장 범위도 포함됩니다. 과거에 확정한 상태가 이 저장 요청을 기록하지 않았으면 새 경로는 자동 저장을 거부하고 해당 요청을 다시 확인하도록 안내합니다. 저장 요청이 없는 과거 확정 상태의 호환 경로는 유지합니다. 취소 응답이나 잘못된 형식의 승인 기록도 설정을 쓰기 전에 거부합니다.
37
+
38
+ 스킬은 단일 실행의 준비가 성공한 뒤 상태 파일을 정리합니다. 연속 실행에서는 승인된 마지막 단계의 준비가 성공할 때까지 파일을 보존합니다. 파일이 사라지면 다음 단계 준비를 중단하고 입력 마법사를 다시 진행합니다. 이미 준비한 실행은 기존 실행 매니페스트(manifest)로 재개하며 상태 파일을 요구하지 않습니다. 응답 유실이나 부분 실패 뒤에는 기존 실행 상태를 먼저 확인하고 같은 준비 명령을 무조건 반복하지 않습니다.
39
+
40
+ 이 경로의 강제 지점은 `wizard.launch.load_confirmed_launch()`, `render-bundle.prepareRenderBundle()`과 기존 `prepare_task_bundle()`이며, 상태 판독·전달 검사와 명령 경계 검사가 각각 이를 확인합니다.
41
+
42
+ # Implementation Trace commands
43
+
44
+ `okstra trace` manages a single-session Implementation Trace independently of
45
+ run manifests and the cross-verification lifecycle. All commands emit one JSON
46
+ object on stdout. Errors use a nonzero exit code and
47
+ `{"error":{"code":"...","message":"..."}}`.
48
+
49
+ ```bash
50
+ okstra trace new --slug <slug> [--project-root <dir>] [--task-key <key>] [--metadata <json-file>]
51
+ okstra trace status --slug <slug>
52
+ okstra trace status --path <file>
53
+ okstra trace advance --path <file> --step <id> [--host-runtime <id> --review <completion> ...] [--verdict pass|fail] [--approve "<user quote>"] [--evidence <json-file>] [--metadata <json-file>]
54
+ okstra trace reviewers --path <file> --host-runtime <id> [--count <n>]
55
+ okstra trace sync --path <file> [--task-key <key>] [--metadata <json-file>]
56
+ ```
57
+
58
+ `new` requires `.okstra/project.json`, accepts slugs matching
59
+ `^[a-z0-9]+(-[a-z0-9]+)*$`, and creates
60
+ `.okstra/traces/<slug>/<YYYYMMDD-HHMMSS>-<slug>.md`. Filename timestamps use local
61
+ time; `createdAt` includes its time-zone offset. The result is
62
+ `{path, slug, currentStep: "analysis"}`. A collision returns `TRACE_EXISTS`.
63
+
64
+ `status --slug` chooses the latest timestamped filename in that feature directory.
65
+ `--path` selects an explicit attempt. Status is read-only and returns
66
+ `{path, currentStep, steps, ids, nextAction, failStreak, commitPoint}`.
67
+ `nextAction` is `write`, `review`, `ask-user-decision`, `run-tests` or `done`.
68
+
69
+ `reviewers` works on the current review step. It returns the operation, duty,
70
+ `binding` text and reviewer `slots`. `analysis-review` and `spec-review` use the
71
+ `trace-scope-review` operation (`scope-critic`); `interface-review` uses
72
+ `trace-interface-review` (`interface-reviewer`). Slots come from the registered
73
+ model pool, ordered so models outside the host's own provider come first;
74
+ `--count` defaults to 1, must be a positive integer, and is capped by the
75
+ operation contract (`INVALID_ARGUMENT` otherwise). `independence` is
76
+ `cross-provider` when a slot's provider differs from the host's own provider,
77
+ otherwise `same-provider`. The binding names the trace path, step, next round,
78
+ the SHA-256 digest of the reviewed writing section's raw text (fenced blocks
79
+ included) and the host runtime.
80
+
81
+ `advance` accepts only the current step. A review passes in one of two ways:
82
+
83
+ - `--host-runtime <id>` with `--review <completion>`, repeated up to the
84
+ operation contract's count (the CLI also bounds the list at eight inputs).
85
+ Each completion of purpose `trace-review` must pass `verify-completion`, use
86
+ the step's duty and the same host runtime, carry the current binding text in
87
+ its prompt and return exactly one `Trace review verdict: pass|fail` line. Any
88
+ failing reviewer fails the review. When another provider is registered for
89
+ the role, at least one reviewer must use it. `--verdict` and `--approve` are
90
+ refused with `--review`. The step records
91
+ `review: {verdict, independence, reviewers}`.
92
+ - `--verdict pass --approve "<user quote>"`, the user-approval mode, which records
93
+ the quote under `approval`.
94
+
95
+ `--verdict fail` alone always fails the review. Failed reviews return to their
96
+ writing step and increment their failure streak. Three consecutive failures ask
97
+ the agent to obtain a user decision.
98
+
99
+ Writing sections use Markdown tables with fixed English headers:
100
+
101
+ - `analysis`: `Requirement` IDs (`R-NNN`) and a `Key` / `Value` table containing
102
+ `language`, `unitTestCommand`, `integrationTestCommand`, `typecheckCommand`.
103
+ - `spec`: `Spec item` / `Requirement` links.
104
+ - `interface-design`: `Use case` (`UC-NNN`) / `Requirement` links.
105
+ - `tests-red`: `Test` / `Use case` / `Kind` / `Path` rows; integration rows use
106
+ `integration` for `Kind`, with at least one integration test per UC.
107
+
108
+ Evidence files contain one object or an array of objects with `kind`
109
+ (`typecheck`, `unit`, `integration`), `command`, integer `exitCode`, `summary`,
110
+ and optional `failureCause`. The CLI adds `recordedAt`. `interface-code` requires
111
+ typecheck GREEN; `tests-red` requires unit and integration RED, each classified
112
+ `not-implemented`; `implementation` requires unit GREEN while integration may
113
+ remain RED; `integration` requires integration GREEN. Other failure causes are
114
+ `assertion`, `compile-error`, `import-error` and `other`.
115
+
116
+ The command updates JSON frontmatter and appends evidence blocks atomically.
117
+ The body belongs to the agent. `commitPoint` is set after `interface-code`,
118
+ `implementation` and `integration`; the command does not commit.
119
+
120
+ Contract errors include `PROJECT_NOT_INITIALIZED`, `INVALID_SLUG`,
121
+ `TRACE_EXISTS`, `TRACE_NOT_FOUND`, `TRACE_MALFORMED`, `STEP_MISMATCH`,
122
+ `APPROVAL_REQUIRED`, `TRACEABILITY_GAP`, `EVIDENCE_REJECTED`, `SECTION_EMPTY`,
123
+ `REVIEW_STALE` (a prompt lacks the current binding: the section, round, step,
124
+ trace or host changed, or the binding was not copied verbatim),
125
+ `REVIEW_REJECTED` (inauthentic completion, wrong duty or host, duplicate
126
+ completion, or a missing or repeated verdict line), `REVIEW_REQUIRED`,
127
+ `REVIEWER_NOT_INDEPENDENT` and `REVIEW_UNAVAILABLE` (the helper failed or timed
128
+ out after 60 seconds).
129
+ See the [skill guide](skills/okstra-tdd.md) for the agent workflow and the
130
+ boundary between validated inputs and agent judgment.
131
+
132
+ ## Shared task history and discovery
133
+
134
+ A trace may carry an optional `task` object in version-1 frontmatter. `new
135
+ --task-key` links creation; `sync --task-key` attaches an older unlinked trace.
136
+ An attempt's key is immutable and belongs to the registered project. Metadata
137
+ JSON contains `title`, `summary`, `tags`, `changedFiles`, `references` and
138
+ `relatedTasks`; omitted fields retain their values. A linked integration
139
+ completion requires a nonempty functional `summary`, separate from test evidence.
140
+ Without binding options, existing standalone creation is unchanged.
141
+
142
+ A successful linked operation also returns `taskKey`, `task` and `taskSync`.
143
+ Trace publication precedes task projection. `TASK_SYNC_FAILED` includes
144
+ `traceSaved`, `path`, `taskKey` and a retry command. Query `status`, then use
145
+ `sync` to retry projection without advancing an already saved step. Read-only
146
+ status returns `taskSync: "pending"` when acknowledgment is unavailable. History
147
+ retains prior attempts; completion uses direct-work provenance with
148
+ `crossVerification: "not-performed"`, without a verification run or phase.
149
+
150
+ ```bash
151
+ okstra task-list --query "<terms>" [--limit 20] [--after <task-key>]
152
+ okstra task-list --related-to <task-key> [--query "<terms>"] [--after <task-key>]
153
+ okstra task-show <task-key>
154
+ ```
155
+
156
+ Query terms are whitespace-separated, case-folded and AND-combined over titles,
157
+ summaries, metadata and linked trace text. Completed tasks are included. Related
158
+ results exclude the anchor itself and distinguish explicit `relatedTasks` in
159
+ either direction (`user-stated`) from shared tags, files or references
160
+ (`candidate`), with evidence. These operations do not write links or indexes.
161
+ Existing task filters still apply; ordinary listing retains its previous order.
162
+ Query pages use stable task-key order and return bounded `tasks`, `unavailable`,
163
+ `truncated` and `nextCursor` fields. Resume with `--after <nextCursor>`. An empty
164
+ page with a cursor does not establish that no matches exist. Unreadable, unsafe
165
+ or secret-containing sources are reported as `source-unavailable` without their
166
+ contents. Sources are checked for regular-file type before opening. Task details expose the latest trace and compact attempt history.
167
+
168
+ Metadata files are limited to 16 KiB; titles to 200 characters and summaries to
169
+ 2,000. List limits are 20 tags of 64 characters, 100 changed files of 512,
170
+ 20 references of 512 and 50 related task keys of 384. The retained task-level relation union is bounded by
171
+ the complete manifest byte limit; the 50-entry cap applies to each trace metadata
172
+ update. Task manifests are at most
173
+ 2 MiB and retain at most 128 trace attempts. Queries accept 256 characters and
174
+ 1–100 results (default 20), return 160-character previews, read a catalog up to
175
+ 4 MiB / 1,000 candidates and inspect at most 64 tasks per page, including a
176
+ related anchor. Candidate and anchor source reads share a 16 MiB page budget
177
+ (with at most one overflow-probe byte); project configuration and catalog reads
178
+ retain their separate limits. Each source is limited to 2 MiB; response JSON to
179
+ 256 KiB. A byte-budget stop preserves the unfinished candidate for the next page.
180
+ Pagination reports remaining candidates when an inspection or output bound is
181
+ reached. Enforcement lives in trace metadata validation and `okstra_ctl.task_query`;
182
+ regressions are in `tests-js/trace.test.mjs`, `tests/run/test_trace_tasks.py` and
183
+ `tests/run/test_task_query.py`.
184
+
185
+ ## Trace capacity limits
186
+
187
+ Supported inputs and serialized outputs satisfy all applicable limits together:
188
+
189
+ | Boundary | Limit |
190
+ |---|---:|
191
+ | Trace file, UTF-8 | 2,097,152 bytes |
192
+ | Evidence JSON file; each language configuration read by trace | 262,144 bytes each |
193
+ | Complete trace, including frontmatter, blank lines and fences | 20,000 physical lines |
194
+ | Body table data across the document, excluding headers, separators and fenced examples | 10,000 rows |
195
+ | Table width | 16 columns |
196
+ | Raw requirement list; raw use-case list; raw evidence list | 1,000 entries each, before deduplication or expansion |
197
+ | Feature directory scan, including unrelated entries | 1,024 entries |
198
+
199
+ Bounded reads and structural checks reject an excess with `INPUT_LIMIT_EXCEEDED`
200
+ and a message identifying the limit. A directory excess returns no partial
201
+ selection. The same trace byte and structural limits apply before publication;
202
+ if approvals or evidence would exceed them, `advance` preserves every original
203
+ byte. Ordinary malformed input retains its existing error code. These language
204
+ configuration limits apply only to trace reads, not other commands' settings.
205
+
206
+ Local performance acceptance targets are a whole-command 95th percentile at
207
+ most 2,000 ms and maximum resident memory at most 192 MiB per process, measured
208
+ after three warm-ups over twenty samples on Apple M4 Max, Darwin 25.6.0 and Node
209
+ 24.22.0, without another lock owner. Every capacity limit above is a prerequisite.
210
+ These are reference-environment QA targets, not universal CLI or CI guarantees.
211
+
1
212
  # Implementation design-review inputs
2
213
 
3
214
  New approved-plan implementation and final-verification preparations freeze
@@ -32,6 +243,72 @@ For a stage, pass its identified `--run-manifest <path>` to reuse the author's
32
243
  frozen policy. A missing author-policy reference is unverified policy alignment;
33
244
  do not infer a latest run or claim that independently captured policies match.
34
245
 
246
+ `okstra code-review assign --census <review-id>.census.md`는 프로젝트 `.okstra/` 아래의
247
+ 전체 census를 축별 배정 census로 나눈다. 셀이 있는 축마다 같은 디렉터리에
248
+ `<review-id>.<axis>.census.md`를 쓰고, `Axis`·`Cells`·`Census` 줄을 축 순서
249
+ (`structural`, `semantic`, `general`, `state-and-tests`)대로 출력한다. 셀이 없는 축은
250
+ `Census: -`다. `## Cells` 밖의 줄(정책 digest, 리소스 선택, 규칙 목록)은 그대로 복사한다.
251
+ 축별 셀이 서로 겹치지 않고 합치면 전체 census가 되는지 검사하며, 이미 있는 배정
252
+ 파일은 내용이 같을 때만 재사용하고 다르면 종료 코드 2로 거부한다.
253
+
254
+ `okstra agent-prompt resolve-operation --operation <id>`는 작업의 팀마다 모델을 하나씩 정한다.
255
+ `--model <provider/model>`을 팀 순서대로 반복하면 그 모델을 쓰고, 없으면 프로젝트
256
+ `.okstra/project.json`의 `operationModels.<id>`, 그다음 `~/.okstra/config.json`의 같은 키,
257
+ 그다음 공급자 어댑터의 기본 모델 순서로 고른다. 설정 범위는 서로 합치지 않는다. 팀마다
258
+ 공급자가 달라야 하고, 작업 계약의 상한을 넘을 수 없으며, 공급자가 작업의 역할을 지원해야
259
+ 한다. `--count`는 먼저 1부터 작업 계약의 상한까지인지 검사한다. `--model`과 함께 주면 개수가 같아야
260
+ 하고, 설정 목록과 함께 주면 앞에서 그 수만큼 쓴다. `--host-runtime <host>`를 주면 슬롯마다 그 호스트에서 `cli-wrapper` 배정이
261
+ 해석되는지도 확인한다. 출력의 각 슬롯에는 모델의 출처(`flag`, `project`, `global`,
262
+ `bundled`)가 붙는다. `--out <path>`는 같은 JSON 결과를 파일로도 쓰며, 그 파일이
263
+ `code-review prepare --slots`의 입력이다. 설정은 `okstra model operation set <id> <ref,ref...> --scope project|global`로
264
+ 같은 검사를 거쳐 쓰고, `okstra model operation unset <id> --scope ...`로 지운다. `okstra model default|operation set|unset`은 설정 파일의 잠금을 잡은 채 읽고 쓰며,
265
+ 해당 섹션 형태가 잘못되어 있으면 쓰지 않고 오류로 끝난다.
266
+
267
+ `okstra code-review prepare --review-id <id> --census <id>.census.md --review-policy <path>
268
+ --base <commit> --head <commit> --slots <slots.json> --brief <path> --host-runtime <host>`는
269
+ `.okstra/agent-invocations/code-review/<id>.census.md`를 축별로 나눈 뒤, 모델 팀과 축마다
270
+ `scope` 계산, 지시문 작성, 프롬프트 발행, 검증을 한 번에 한다. `--slots`는
271
+ `okstra agent-prompt resolve-operation --operation code-review --json`의 출력 파일이며, 팀마다
272
+ 공급자가 달라야 한다. 지시문은 `--brief` 본문 뒤에 팀·축·census 경로와 그 축의 `scope` 출력을
273
+ 붙인 것이다. 모든 호출은 `cli-wrapper` 실행기로 배정되고, invocation ID는
274
+ `<id>-t<team>-<axis>-a1`이다. 결과는 `<id>.batch.json`에 남고 항목마다 `Item:` 줄을 출력한다.
275
+ 같은 입력으로 다시 실행하면 발행된 파일을 재사용하고, 내용이 다른 기존 파일이 있으면 거부한다.
276
+ `--previous-batch <이전 id>.batch.json`을 주면, 비교 기준과 공유 정책이 같을 때 같은 팀 순번·축·
277
+ 공급자·모델의 이전 완료 기록(최신 시도부터)을 그 항목의 `scope`에 이전 입력으로 넘긴다. 공급자나
278
+ 모델이 다른 팀, 기준이나 정책이 바뀐 회차는 이전 입력 없이 전체 검사한다.
279
+
280
+ `okstra code-review start --batch <id>.batch.json [--max-calls <n>]`는 아직 시작하지 않은
281
+ 항목마다 감독 프로세스를 새 세션으로 띄우고 바로 반환한다. 감독 프로세스는 항목의 래퍼를
282
+ 실행하면서 표준 출력과 표준 오류를 `.tmp/<invocation-id>.returned.txt`와 `.stderr.txt`에
283
+ 쓰고, 래퍼가 끝나면 종료 코드를 `.tmp/<invocation-id>.exit.json`에 남긴다. 래퍼가 사전
284
+ 검사에서 실패해 상태 파일을 쓰지 않은 경우도 이 기록으로 끝난 것을 안다. `--max-calls`를
285
+ 주면 이 리뷰에서 이미 시작한 호출 수와 이번에 시작할 수의 합이 그 값을 넘을 때 아무것도
286
+ 시작하지 않는다. 진행 상태는 `batch.json`이 아니라 잠금으로 보호하는 `<id>.state.json`에 둔다.
287
+
288
+ `okstra code-review await --batch <id>.batch.json --timeout-seconds <s>`는 끝난 항목을
289
+ 응답 확정, 완료 기록 발행, 완료 확인 순서로 진행하고, 항목마다 그 축의 배정 census로 먼저
290
+ 감사한다. 다른 축 셀에 쓴 행은 이 감사에서 알 수 없는 셀로 남는다. 모든 항목이 끝나면 팀마다
291
+ 전체 census와 그 팀의 완료 기록으로 감사하고 `ALL_DONE`을 출력한다(빠짐 없이 끝나면 종료
292
+ 코드 0, 실패·누락·알 수 없는 셀이 있으면 1). 시간이 지나면 `POLL_TIMEOUT`과 종료 코드 75로
293
+ 끝나며 같은 명령을 다시 부르면 이어서 진행한다. 래퍼 종료 코드가 0이 아니거나 쓰기 감사
294
+ 위반이 있거나 응답 본문이 비면 실패로, 감독 프로세스가 종료 기록 없이 사라지면 `stalled`로
295
+ 기록한다. 팀·축마다 모든 시도의 완료 기록을 최신 시도부터 넣어 그 축의 첫 배정 census로
296
+ 감사하므로, 같은 셀에 대한 정정된 행이 이전 행보다 먼저 선택된다. 셀별 판정 종류와 근거는
297
+ 상태 파일의 축·팀 감사에 남는다. 두 경우는 팀·축마다 한 번씩 자동으로 다시 시도한다: 응답
298
+ 본문 없이 0이 아닌 코드로 끝난 호출(재시도), 그리고 거절된 셀의 사유가 모두 행 작성 형식에 관한
299
+ 시도(그 셀만 형식 수정, 지시문에 파서 사유를 넣는다). 형식 사유는 표 열, 중복 행·규칙 판정, N/A
300
+ 별칭, 지적 ID 형식, Coverage Verdicts 절 밖에 없는 지적 본문, clean 근거의 표기다. 판정 행 누락은
301
+ 응답에 판정이 하나도 없을 때만 형식 사유로 본다. 확인하지 않았거나 알 수 없는 규칙, 없는 파일·줄을
302
+ 가리키는 근거는 형식 사유가 아니며 `gap-fill`로 처리한다. `start --max-calls`로 정한 한도를 넘으면
303
+ 자동 시도도 하지 않는다.
304
+
305
+ `okstra code-review gap-fill --batch <id>.batch.json [--reject <team>:<cell-id> ...]`는 각 팀·축의
306
+ 최신 시도에서 남은 셀(감사 누락 셀과 `--reject`로 거절한 셀)만 담은 census로 다음 시도를
307
+ 준비하고 `batch.json`에 추가한다. 실패하거나 `stalled`가 된 시도는 그 시도의 셀 전체를 다시
308
+ 요청한다. 지시문에는 남은 셀과 사유, 이전 시도의 확인된 응답이 들어간다. 직전 보완 시도가
309
+ 요청받은 셀을 하나도 닫지 못한 팀·축은 새 시도를 만들지 않고 `NO_PROGRESS: <team>/<axis>`를
310
+ 출력한다(종료 코드 1). 새 시도는 `start`로 시작한다.
311
+
35
312
  `okstra code-review scope --review-policy <snapshot> ...` uses captured source
36
313
  bodies for its rule fingerprints. New standalone `code-reviewer` materialization
37
314
  requires `--review-policy`, `--review-census`, `--review-base`, and `--review-head`.
@@ -39,7 +316,7 @@ Repeat `--review-resource` with any explicit selections made for the census.
39
316
  The materializer reads the fixed tree, validates canonical assigned rules, and
40
317
  includes the selected frozen rules, calibration and assigned census itself.
41
318
  Do not duplicate their bodies in an instruction file or replace them with live
42
- installed paths. Both model coordinators and specialists use the same shared policy.
319
+ installed paths. Every specialist of every model team uses the same shared policy.
43
320
 
44
321
  Standalone reviews audit source and Git changes after execution. A source or
45
322
  index mutation prevents a successful review without restoring user changes.
@@ -47,6 +324,25 @@ New reviews publish version-2 completion markers bound to their integrity audit;
47
324
  historical version-1 completion markers remain verifiable. This detects observed
48
325
  mutations; it is not an operating-system write sandbox or proof of review quality.
49
326
 
327
+ # 프로젝트 그룹 명령
328
+
329
+ `okstra project-group`은 이름 붙은 그룹에 속한 프로젝트 루트를 사용자 홈에 등록한다. 실행을 시작하지 않으며, 한 프로젝트를 여러 그룹에 등록할 수 있다.
330
+
331
+ ```bash
332
+ okstra project-group add --project-group <name> --project-id <project-id> --project-root <abs-path>
333
+ okstra project-group remove --project-group <name> --project-id <project-id>
334
+ okstra project-group show --project-group <name>
335
+ okstra project-group list
336
+ ```
337
+
338
+ 기본 출력은 JSON이고 `--text`는 고정 텍스트 필드를 출력한다. 실패하면 `{"ok": false, "reason": ...}`를 출력하고 종료 코드 1을 돌려준다.
339
+
340
+ - `add`는 `added`(새 등록 여부)와 `changed`(파일 변경 여부)를 돌려준다. 같은 프로젝트를 같은 루트로 다시 등록하면 파일을 쓰지 않는다. 다른 루트로 등록하면 `projectRoot`를 갱신한다.
341
+ - `show`는 등록 행마다 `rootExists`로 루트 디렉터리의 현재 존재 여부를 표시한다.
342
+ - `list`는 그룹별 `projectCount`를 돌려주고, 읽지 못한 그룹 파일은 `errors`에 담아 종료 코드 1을 돌려준다.
343
+
344
+ 저장 위치와 소속 규칙은 [저장소 계약](architecture/storage-model.md)의 프로젝트 그룹 등록부 절을 따른다.
345
+
50
346
  # Linked work record commands
51
347
 
52
348
  `okstra doyouknow` stores linked work records in the user home without requiring
@@ -151,7 +447,7 @@ okstra doyouknow list --after <nextCursor>
151
447
  ```
152
448
 
153
449
  `sync` reads existing Memory Book entries, manager registrations, assignments,
154
- notes and snapshots, and tasks in manager-registered projects. It preserves the
450
+ notes, snapshots and manager journals, and tasks in manager-registered projects. It preserves the
155
451
  original files. `list` reads the cached sources without collecting them again;
156
452
  `--source`, `--scope`, `--limit` and `--after` select the returned page. JSON is
157
453
  the default; all commands also accept `--text`. Partial collection exits 1 with
@@ -164,7 +460,7 @@ Settings replacement uses `schemas/doyouknow-config-v1.schema.json`:
164
460
  "schemaVersion": 1,
165
461
  "autoRegister": true,
166
462
  "scope": null,
167
- "sources": ["memory", "manager", "task"],
463
+ "sources": ["memory", "manager", "task", "business"],
168
464
  "includeProjects": [],
169
465
  "excludeProjects": [],
170
466
  "includeGroups": [],
@@ -172,6 +468,27 @@ Settings replacement uses `schemas/doyouknow-config-v1.schema.json`:
172
468
  }
173
469
  ```
174
470
 
471
+ `business` 수집원은 프로젝트 그룹 등록부(`okstra project-group`)의 모든 프로젝트에서 `okstra explain-flow` 실행 기록을 읽는다. 질문 하나가 흐름 하나이고, 상태가 `complete`·`partial`이며 모드가 `current`·`post`인 실행 중 가장 최근 것을 쓴다. 흐름마다 `flow` 노드, 용어의 `concept` 노드, 관련 프로젝트의 `project` 노드를 만들고, 프로젝트 간 관계를 `call`·`event`·`queue`·`shared-data`·`file`·`batch` 관계로 넣는다. 관계의 근거는 연결된 사실의 `프로젝트:경로:줄`이고, 연결된 사실이 모두 `static`·`execution-verified`이면 `observed`, 아니면 `candidate`다. 단계·용어·사실·미확인 구간·소스 버전은 수집원의 `metadata`에 담기며, 사실의 소스 발췌문은 담지 않는다.
472
+
473
+ 실행 기록은 explain-flow가 쓰는 스키마(`schemas/business-flow-v1.schema.json`)로 읽는다. 읽지 못하거나 스키마에 맞지 않는 기록이 있으면 그 프로젝트의 결과는 `partial`과 `business-source-unavailable`이다. 뜻이나 이름이 빈 용어는 `concept` 노드를 만들지 않고 `metadata`에만 남는다. 한 프로젝트가 그룹마다 다른 루트로 등록됐으면 `conflicting-project-roots`로 `unavailable`이다. 읽지 못한 그룹 파일이 있으면 등록부 전체를 알 수 없으므로 어떤 프로젝트도 수집하지 않고 프로젝트마다 `project-group-registry-incomplete`로 `unavailable`을 돌려준다. 완료된 수집은 보지 못한 수집원을 `missing`으로 표시하므로, 루트가 하나뿐인지 확인할 수 없는 상태에서는 수집하지 않는다. `includeGroups`·`excludeGroups`는 메모리 북 항목에만 적용되고 이 수집원은 `includeProjects`·`excludeProjects`만 따른다. 설정 파일이 없을 때의 기본 `sources`에는 `business`가 포함된다. 이미 저장한 설정 파일에는 `business`를 직접 추가해야 한다. 적용 여부는 `tests/doyouknow/test_business_sources.py`가 확인한다.
474
+
475
+ ## 프로젝트 그룹 화면
476
+
477
+ ```bash
478
+ okstra doyouknow view --project-group <name>
479
+ ```
480
+
481
+ 프로젝트 그룹 하나의 프로젝트 관계, 업무 흐름, 조사 범위, 연결 기록을 HTML 파일 하나로 만든다. 출력은 `<okstra-home>/doyouknow/view/<safe-project-group>/index.html`이고 `viewPath`·`viewUrl`과 프로젝트·흐름·관계·기록 수를 돌려준다. 외부 자원을 읽지 않는 단일 파일이다.
482
+
483
+ - 화면은 저장된 수집 결과를 읽는 파생 뷰다. 수집은 하지 않으므로 먼저 `okstra doyouknow sync`를 실행한다.
484
+ - 흐름은 그룹 구성원이 저장한 `business` 수집원이다. 관계 그래프에는 구성원이 아닌 프로젝트도 관계의 상대로 나타난다.
485
+ - 흐름마다 기록된 소스 버전을 구성원 프로젝트의 현재 상태와 비교해 `current`·`historical`·`unverified`를 표시한다. 판정은 `okstra explain-flow knowledge`의 최신성과 같은 함수(`source_freshness`)를 쓴다. 비교 대상 루트는 지식 조회와 같은 집합(실행 이력의 프로젝트에 그룹 구성원을 더한 것)에서 찾는다. 그 집합에 없는 프로젝트, 루트를 읽을 수 없는 프로젝트, 기록 당시 버전이 비어 있는 프로젝트가 섞인 흐름은 `unverified`다. 흐름의 프로젝트 목록은 수집 때 저장한 `project` 노드를 그대로 쓴다. 크기가 커서 목록에 실리지 않는 수집원은 소속 그룹을 알 수 없으므로 화면 위쪽의 수집 문제에 id만 표시한다.
486
+ - 조사 범위는 그룹의 흐름이 조사한 프로젝트(`inspectedProjects`)를 기준으로 한다. 조사되지 않은 프로젝트는 관계가 없다고 확인된 것이 아니다.
487
+ - 연결 기록은 그룹 구성원을 `project` 노드로 가진 메모리·매니저·작업 수집원이다.
488
+ - 검색은 흐름의 제목·질문·요약·용어·단계·사실·근거 위치를 대상으로 하고, 공백으로 나눈 모든 단어가 들어 있는 흐름만 남긴다.
489
+
490
+ 화면의 틀·스타일·동작은 `templates/doyouknow/group-view.template.html`, `group-view.css`, `group-view.js`에 있고 `scripts/okstra_ctl/doyouknow/group_view.py`가 데이터와 함께 합친다. 적용 여부는 `tests/doyouknow/test_group_view.py`와 `tests-js/group-view.test.mjs`가 확인한다.
491
+
175
492
  An empty include list includes all; exclusions take precedence. Group filters
176
493
  apply to Memory Book groups. A mixed-project memory is skipped before reading its
177
494
  body if any related project is excluded or outside the include list. Unassigned
@@ -7,12 +7,11 @@ Use this matrix before changing high-risk repo contracts. Update the source file
7
7
  | Add CLI flag | `src/`, `scripts/okstra_ctl/run.py`, `docs/cli.md`, `prompts/wizard/` | JS CLI tests and pytest CLI contracts |
8
8
  | Add Node subcommand | `src/cli-registry.mts`, `src/commands/`, `docs/cli.md`, `docs/project-structure-overview.md` | `tests-js/cli-registry.test.mjs` plus command-specific JS/Python tests |
9
9
  | Add public skill | `src/lib/skill-catalog.mts`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/skills/<name>.md`, `docs/skills/README.md`, `docs/project-structure-overview.md`, `README.md` | `tests-js/skill-catalog.test.mjs` |
10
- | Change manager contract | `scripts/okstra_ctl/manager_*.py`, `skills/okstra-manager/SKILL.md`, `docs/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests-js/cli-wrapper-contract.test.mjs`, `tests/test_okstra_manager_*.py` |
10
+ | Change manager contract | `scripts/okstra_ctl/manager_*.py`, `skills/okstra-manager/SKILL.md`, `docs/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests/doyouknow/test_manager_sources.py`, `tests/doyouknow/test_okstra_manager_journal.py` |
11
11
  | Change a skill's behaviour | `skills/<name>/SKILL.md`, `docs/skills/<name>.md` (every Guarantees row names its enforcement or says `unenforced`) | unenforced |
12
12
  | Add phase | `scripts/okstra_ctl/phases/catalog.py`, `scripts/okstra_ctl/workflow.py`, `scripts/okstra_ctl/phases/<package>/` (`profile.md`, `profile.json`, `spec.md`, policy, report assets and tests), common assembly in `validators/` | workflow and validation contract tests |
13
13
  | Change role requirements | `scripts/okstra_ctl/phases/<package>/profile.json`, `scripts/okstra_ctl/role_requirements.py` | role requirement contract tests |
14
14
  | Change phase policy | `scripts/okstra_ctl/phases/<package>/`, its `spec.md`, and the common caller; continuation decisions belong in `prompts/lead/phase-routing.md` | phase-local tests |
15
15
  | Change report section | `schemas/final-report-v2.0.schema.json`, `templates/reports/final-report-v2.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
16
- | Maintain Korean review mirrors | `config/korean-sources.json`, `tools/korean-sources/` (`cli.mjs`, `baseline.mjs`, `config.mjs`, `markdown.mjs`, and the shared workflow), `.agents/skills/sync-korean-sources/`, `.claude/skills/sync-korean-sources/` | `tests-js/korean-sources-*.test.mjs` (`cli`, `config`, `markdown`, and `skill`) |
17
16
 
18
17
  `runtime/` is build output. Never edit it directly; change source files and rebuild the runtime payload instead.