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
@@ -12,6 +12,9 @@ from typing import Any
12
12
  from .final_report_schema import SchemaError, validate as validate_schema
13
13
 
14
14
 
15
+ OUTSIDE_WORKER_RESULT_LANES = "outside worker result lanes"
16
+
17
+
15
18
  class JsonBoundaryError(ValueError):
16
19
  """An owned JSON artifact could not satisfy its persistence contract."""
17
20
 
@@ -22,6 +25,16 @@ class JsonBoundaryError(ValueError):
22
25
  super().__init__(f"{artifact}: {reason}: {path}")
23
26
 
24
27
 
28
+ class PageBudgetExhausted(Exception):
29
+ """Let callers paginate without labeling an unread source as unavailable."""
30
+
31
+
32
+ @dataclass
33
+ class ReadBudget:
34
+ max_bytes: int
35
+ bytes_read: int = 0
36
+
37
+
25
38
  _EXTERNAL_SOURCE_SEAL = object()
26
39
 
27
40
 
@@ -86,7 +99,7 @@ def external_worker_json_source(
86
99
  )
87
100
  if not is_worker_lane or lexical_path.parent != lexical_lane:
88
101
  raise JsonBoundaryError(
89
- path, "worker JSON", "outside worker result lanes"
102
+ path, "worker JSON", OUTSIDE_WORKER_RESULT_LANES
90
103
  )
91
104
  try:
92
105
  lexical_lane.relative_to(lexical_root)
@@ -96,12 +109,12 @@ def external_worker_json_source(
96
109
  path.resolve(strict=False).relative_to(resolved_lane)
97
110
  except ValueError as exc:
98
111
  raise JsonBoundaryError(
99
- path, "worker JSON", "outside worker result lanes"
112
+ path, "worker JSON", OUTSIDE_WORKER_RESULT_LANES
100
113
  ) from exc
101
114
  if _has_symlink_component(lexical_lane, lexical_root) or _has_symlink_component(
102
115
  lexical_path, lexical_lane
103
116
  ):
104
- raise JsonBoundaryError(path, "worker JSON", "outside worker result lanes")
117
+ raise JsonBoundaryError(path, "worker JSON", OUTSIDE_WORKER_RESULT_LANES)
105
118
  return _issue_external_source(path, "worker")
106
119
 
107
120
 
@@ -204,6 +217,7 @@ def load_owned_object(
204
217
  schema: Mapping[str, Any] | None = None,
205
218
  validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
206
219
  max_bytes: int | None = None,
220
+ budget: ReadBudget | None = None,
207
221
  ) -> dict[str, Any]:
208
222
  """Load and validate one okstra-owned JSON object."""
209
223
  return load_owned_object_snapshot(
@@ -212,6 +226,7 @@ def load_owned_object(
212
226
  schema=schema,
213
227
  validate_cross_fields=validate_cross_fields,
214
228
  max_bytes=max_bytes,
229
+ budget=budget,
215
230
  ).value
216
231
 
217
232
 
@@ -222,11 +237,14 @@ def load_owned_object_snapshot(
222
237
  schema: Mapping[str, Any] | None = None,
223
238
  validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
224
239
  max_bytes: int | None = None,
240
+ budget: ReadBudget | None = None,
225
241
  ) -> OwnedJsonSnapshot:
226
242
  """한 번 읽은 바이트에서 객체를 파싱·검증해 함께 반환한다."""
243
+ if budget is not None and max_bytes is None:
244
+ max_bytes = budget.max_bytes
227
245
  try:
228
246
  raw_bytes = path.read_bytes() if max_bytes is None else read_bounded_bytes(
229
- path, max_bytes=max_bytes, artifact=artifact,
247
+ path, max_bytes=max_bytes, artifact=artifact, budget=budget,
230
248
  )
231
249
  value = json.loads(
232
250
  raw_bytes.decode("utf-8"),
@@ -254,9 +272,18 @@ def load_owned_object_snapshot(
254
272
  )
255
273
 
256
274
 
257
- def read_bounded_bytes(path: Path, *, max_bytes: int, artifact: str) -> bytes:
275
+ def read_bounded_bytes(path: Path, *, max_bytes: int, artifact: str, budget: ReadBudget | None = None) -> bytes:
276
+ maximum = max_bytes
277
+ if budget is not None:
278
+ if budget.bytes_read > budget.max_bytes:
279
+ raise PageBudgetExhausted("Page source byte budget exhausted")
280
+ maximum = min(maximum, budget.max_bytes - budget.bytes_read)
258
281
  with path.open("rb") as handle:
259
- content = handle.read(max_bytes + 1)
282
+ content = handle.read(maximum + 1)
283
+ if budget is not None:
284
+ budget.bytes_read += len(content)
285
+ if budget.bytes_read > budget.max_bytes:
286
+ raise PageBudgetExhausted("Page source byte budget exhausted")
260
287
  if len(content) > max_bytes:
261
288
  raise JsonBoundaryError(path, artifact, f"input exceeds {max_bytes} bytes")
262
289
  return content
@@ -11,7 +11,10 @@ from okstra_project.dirs import okstra_home
11
11
 
12
12
  from .manager_launch import build_launch_packet
13
13
  from .fixed_text import line, value_lines
14
+ from .manager_journal import JOURNAL_KINDS, add_journal_entry, read_body_file
15
+ from .manager_log import DEFAULT_LIMIT, read_activity_page
14
16
  from .manager_paths import ManagerPathError
17
+ from .manager_resume import DEFAULT_RECENT, resume_manager
15
18
  from .manager_store import (
16
19
  ManagerError,
17
20
  append_directive,
@@ -57,7 +60,8 @@ def render_manager_text(command: str, payload: dict | list[dict]) -> str:
57
60
  allowed = {"init", "discover-projects", "new-project", "new-task-group", "new-task",
58
61
  "task-assign", "task-note", "task-sync", "task-status", "task-run", "task-split",
59
62
  "list-managers", "list-projects", "list-task-groups", "list-tasks", "view",
60
- "task-update", "task-remove-child", "remove-project", "remove-task", "remove-task-group"}
63
+ "task-update", "task-remove-child", "remove-project", "remove-task", "remove-task-group",
64
+ "log", "journal-add", "resume"}
61
65
  if command not in allowed:
62
66
  raise ValueError("unknown manager text purpose")
63
67
  rows = [f"Okstra manager {command}\n", line("Status", "ready")]
@@ -111,9 +115,84 @@ def render_manager_text(command: str, payload: dict | list[dict]) -> str:
111
115
  rows.extend(_render_removal(payload))
112
116
  if command == "task-sync" and "syncedAt" in payload:
113
117
  rows.append(line("Synced at", payload.get("syncedAt")))
118
+ if command == "log":
119
+ rows.extend(_render_log(payload))
120
+ if command == "resume":
121
+ rows.extend(_render_resume(payload))
122
+ if command == "journal-add":
123
+ for label, key in (("Entry ID", "id"), ("Kind", "kind"), ("Body", "body"),
124
+ ("Created at", "createdAt"), ("Resolves", "resolves")):
125
+ rows.append(line(label, payload.get(key)))
114
126
  return "".join(rows)
115
127
 
116
128
 
129
+ def _list_field(payload: dict, key: str) -> list:
130
+ value = payload.get(key)
131
+ return value if isinstance(value, list) else []
132
+
133
+
134
+ def _render_entries(prefix: str, entries: list) -> list[str]:
135
+ rows = [line(f"{prefix} count", len(entries))]
136
+ for index, entry in enumerate(entries, 1):
137
+ for label, key in (("created at", "createdAt"), ("origin", "origin"), ("kind", "kind"),
138
+ ("task group", "taskGroup"), ("task ID", "taskId")):
139
+ rows.append(line(f"{prefix} {index} {label}", entry.get(key)))
140
+ rows.extend(value_lines(f"{prefix} {index} row", entry.get("row")))
141
+ return rows
142
+
143
+
144
+ def _render_log(payload: dict) -> list[str]:
145
+ rows = [line("Matched count", payload.get("matchedCount"))]
146
+ rows.extend(_render_entries("Entry", _list_field(payload, "entries")))
147
+ rows.extend(_render_damaged(_list_field(payload, "damaged")))
148
+ return rows
149
+
150
+
151
+ def _render_last_summary(payload: dict) -> list[str]:
152
+ last_summary = payload.get("lastSummary") if isinstance(payload.get("lastSummary"), dict) else None
153
+ row = last_summary["row"] if last_summary is not None else {}
154
+ rows = [line("Last session summary at", last_summary["createdAt"] if last_summary is not None else "none"),
155
+ line("Last session summary", row.get("body") or "none")]
156
+ count = payload.get("unsummarizedCount") or 0
157
+ since = payload.get("unsummarizedSince") or "the first entry"
158
+ rows.append(line("Unsummarized activity", f"{count} rows since {since}" if count else "none"))
159
+ return rows
160
+
161
+
162
+ def _render_resume(payload: dict) -> list[str]:
163
+ rows = _render_last_summary(payload)
164
+ rows.extend(_render_entries("Open follow-up", _list_field(payload, "openFollowups")))
165
+ rows.extend(_render_entries("Recent decision", _list_field(payload, "recentDecisions")))
166
+ rows.extend(_render_entries("Recent entry", _list_field(payload, "recentEntries")))
167
+ rows.extend(_render_task_overviews(_list_field(payload, "tasks")))
168
+ rows.extend(_render_damaged(_list_field(payload, "damaged")))
169
+ return rows
170
+
171
+
172
+ def _render_task_overviews(tasks: list) -> list[str]:
173
+ rows = [line("Task count", len(tasks))]
174
+ for index, task in enumerate(tasks, 1):
175
+ rows.append(line(f"Task {index} group", task.get("taskGroup")))
176
+ rows.append(line(f"Task {index} ID", task.get("taskId")))
177
+ if "error" in task:
178
+ rows.append(line(f"Task {index} error", task["error"]))
179
+ continue
180
+ rows.append(line(f"Task {index} synced at", task.get("syncedAt") or "never"))
181
+ if "syncAgeSeconds" in task:
182
+ rows.append(line(f"Task {index} sync age", _age_text(task["syncAgeSeconds"])))
183
+ rows.append(line(f"Task {index} changed since sync count", task.get("changedSinceSyncCount")))
184
+ rows.append(line(f"Task {index} unlinked child count", task.get("unlinkedChildCount")))
185
+ return rows
186
+
187
+
188
+ def _render_damaged(damaged: list) -> list[str]:
189
+ rows = [line("Damaged file count", len(damaged))]
190
+ for index, item in enumerate(damaged, 1):
191
+ rows.append(line(f"Damaged file {index} path", item.get("path")))
192
+ rows.append(line(f"Damaged file {index} lines", ", ".join(str(number) for number in item.get("lines") or [])))
193
+ return rows
194
+
195
+
117
196
  # 삭제 명령은 --confirm 이 없으면 대상만 보여 준다. 무엇이 지워지고 무엇이 남는지 한 줄씩 찍는다.
118
197
  def _render_removal(payload: dict) -> list[str]:
119
198
  rows = [line("Removed", "yes" if payload.get("removed") else "no — dry run; rerun with --confirm")]
@@ -265,6 +344,9 @@ _CLI_EPILOG = r"""Usage:
265
344
  okstra manager list task-groups --manager-id <id>
266
345
  okstra manager list tasks --manager-id <id>
267
346
  okstra manager view --manager-id <id>
347
+ okstra manager journal add --manager-id <id> --kind <decision|finding|followup|session-summary> (--body <text> | --body-file <path>) [--task-group <task-group> --task-id <task-id>] [--resolves <entry-id>]
348
+ okstra manager resume --manager-id <id> [--recent <n>]
349
+ okstra manager log --manager-id <id> [--task-group <task-group> --task-id <task-id>] [--kind <name>] [--since <ISO>] [--grep <text>] [--open-followups] [--limit <n>]
268
350
 
269
351
  remove and task remove-child only show their targets unless --confirm is given.
270
352
  --workspace-root is owned by this command.
@@ -392,12 +474,40 @@ def _parser() -> argparse.ArgumentParser:
392
474
 
393
475
  view = sub.add_parser("view")
394
476
  view.add_argument("--manager-id", required=True)
477
+
478
+ journal = sub.add_parser("journal")
479
+ journal_sub = journal.add_subparsers(dest="journal_command", required=True)
480
+ journal_add = journal_sub.add_parser("add")
481
+ journal_add.add_argument("--manager-id", required=True)
482
+ journal_add.add_argument("--kind", choices=JOURNAL_KINDS, required=True)
483
+ body = journal_add.add_mutually_exclusive_group(required=True)
484
+ body.add_argument("--body")
485
+ body.add_argument("--body-file", type=Path)
486
+ journal_add.add_argument("--task-group", default=None)
487
+ journal_add.add_argument("--task-id", default=None)
488
+ journal_add.add_argument("--resolves", default="")
489
+
490
+ resume = sub.add_parser("resume")
491
+ resume.add_argument("--manager-id", required=True)
492
+ resume.add_argument("--recent", type=int, default=DEFAULT_RECENT)
493
+
494
+ activity = sub.add_parser("log")
495
+ activity.add_argument("--manager-id", required=True)
496
+ activity.add_argument("--task-group", default=None)
497
+ activity.add_argument("--task-id", default=None)
498
+ activity.add_argument("--kind", default=None)
499
+ activity.add_argument("--since", default=None)
500
+ activity.add_argument("--grep", default=None)
501
+ activity.add_argument("--open-followups", action="store_true")
502
+ activity.add_argument("--limit", type=int, default=DEFAULT_LIMIT)
395
503
  return parser
396
504
 
397
505
 
398
506
  def _manager_state_changed(args: argparse.Namespace) -> bool:
399
507
  if args.command in ("init", "new"):
400
508
  return True
509
+ if args.command == "journal":
510
+ return args.journal_command == "add"
401
511
  if args.command == "remove":
402
512
  return args.confirm
403
513
  if args.command == "task":
@@ -545,6 +655,17 @@ def main(argv: list[str] | None = None) -> int:
545
655
  _emit("list-tasks", list_tasks(home, args.manager_id), args.json)
546
656
  elif args.command == "view":
547
657
  _emit("view", write_view(home, args.manager_id), args.json)
658
+ elif args.command == "journal" and args.journal_command == "add":
659
+ body = args.body if args.body is not None else read_body_file(args.body_file)
660
+ _emit("journal-add", add_journal_entry(home, args.manager_id, kind=args.kind, body=body,
661
+ task_group=args.task_group, task_id=args.task_id,
662
+ resolves=args.resolves), args.json)
663
+ elif args.command == "resume":
664
+ _emit("resume", resume_manager(home, args.manager_id, recent=args.recent), args.json)
665
+ elif args.command == "log":
666
+ _emit("log", read_activity_page(home, args.manager_id, task_group=args.task_group, task_id=args.task_id,
667
+ kind=args.kind, since=args.since, grep=args.grep,
668
+ open_followups=args.open_followups, limit=args.limit), args.json)
548
669
  else:
549
670
  parser.print_help()
550
671
  return 2
@@ -0,0 +1,126 @@
1
+ """Manager-only journal: decisions, findings, follow-ups and session summaries.
2
+
3
+ Child launch preparation does not read this file. Anything a child task must see
4
+ belongs in `task note` (directives.jsonl).
5
+
6
+ This module owns the journal vocabulary and the follow-up resolution rule; the log,
7
+ resume and view readers import them from here.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import secrets
12
+ from collections.abc import Mapping
13
+ from pathlib import Path
14
+
15
+ from okstra_ctl.jsonl import append_jsonl
16
+
17
+ from .doyouknow.contracts import DoyouknowError, reject_secrets
18
+ from .manager_paths import journal_jsonl_path, task_manifest_path
19
+ from .manager_store import ManagerError, _now_iso, _read_json, load_manager, read_jsonl_rows, task_selection
20
+
21
+ JOURNAL_ORIGIN = "journal"
22
+ DECISION = "decision"
23
+ FINDING = "finding"
24
+ FOLLOWUP = "followup"
25
+ SESSION_SUMMARY = "session-summary"
26
+ JOURNAL_KINDS = (DECISION, FINDING, FOLLOWUP, SESSION_SUMMARY)
27
+ MAX_BODY_CHARS = 4000
28
+
29
+
30
+ def resolved_entry_ids(journal_rows: list[dict]) -> set[str]:
31
+ """Ids that any journal row names in `resolves`."""
32
+ return {str(row["resolves"]) for row in journal_rows if row.get("resolves")}
33
+
34
+
35
+ def is_journal_kind(entry: Mapping[str, object], kind: str) -> bool:
36
+ """Whether a merged activity entry is a journal entry of `kind`."""
37
+ return entry["origin"] == JOURNAL_ORIGIN and entry["kind"] == kind
38
+
39
+
40
+ def is_open_followup(entry: Mapping[str, object], resolved: set[str]) -> bool:
41
+ row = entry["row"]
42
+ return is_journal_kind(entry, FOLLOWUP) and isinstance(row, Mapping) and row.get("id") not in resolved
43
+
44
+
45
+ def open_followups_oldest_first(entries_newest_first: list, resolved: set[str]) -> list:
46
+ return [entry for entry in reversed(entries_newest_first) if is_open_followup(entry, resolved)]
47
+
48
+
49
+ def read_body_file(path: Path) -> str:
50
+ """The `--body-file` text, read as UTF-8 and checked like `--body`."""
51
+ try:
52
+ return path.read_text(encoding="utf-8")
53
+ except (OSError, UnicodeDecodeError) as exc:
54
+ reason = exc.strerror if isinstance(exc, OSError) and exc.strerror else exc
55
+ raise ManagerError(f"failed to read --body-file {path}: {reason}") from exc
56
+
57
+
58
+ def _check_body(body: str) -> None:
59
+ if not body.strip():
60
+ raise ManagerError("journal body is empty")
61
+ if len(body) > MAX_BODY_CHARS:
62
+ raise ManagerError(f"journal body has {len(body)} characters; the limit is {MAX_BODY_CHARS}")
63
+ try:
64
+ reject_secrets(body)
65
+ except DoyouknowError as exc:
66
+ raise ManagerError(f"journal body refused: {exc}") from exc
67
+
68
+
69
+ def _check_resolves(rows: list[dict], resolves: str) -> None:
70
+ if not resolves:
71
+ return
72
+ target = next((row for row in rows if row.get("id") == resolves), None)
73
+ if target is None or target.get("kind") != FOLLOWUP:
74
+ raise ManagerError(f"--resolves must name a followup entry of this manager: {resolves}")
75
+ if resolves in resolved_entry_ids(rows):
76
+ raise ManagerError(f"followup is already resolved: {resolves}")
77
+
78
+
79
+ def _new_entry_id(when: str, rows: list[dict]) -> str:
80
+ stamp = when.replace("-", "").replace(":", "")
81
+ taken = {row.get("id") for row in rows}
82
+ while True:
83
+ candidate = f"j-{stamp}-{secrets.token_hex(2)}"
84
+ if candidate not in taken:
85
+ return candidate
86
+
87
+
88
+ def add_journal_entry(
89
+ home: Path,
90
+ manager_id: str,
91
+ *,
92
+ kind: str,
93
+ body: str,
94
+ task_group: str | None = None,
95
+ task_id: str | None = None,
96
+ resolves: str = "",
97
+ now: str | None = None,
98
+ ) -> dict:
99
+ """Append one journal entry after every check passes; a refused entry writes nothing."""
100
+ load_manager(home, manager_id)
101
+ if kind not in JOURNAL_KINDS:
102
+ raise ManagerError(f"journal kind must be one of {', '.join(JOURNAL_KINDS)}")
103
+ task = task_selection(task_group, task_id)
104
+ if task is not None:
105
+ # The path is a slug, so another spelling reaches the same task; store the manifest's names.
106
+ manifest = _read_json(task_manifest_path(home, manager_id, *task))
107
+ task = (str(manifest.get("taskGroup") or task[0]), str(manifest.get("taskId") or task[1]))
108
+ _check_body(body)
109
+ path = journal_jsonl_path(home, manager_id)
110
+ rows, _ = read_jsonl_rows(path)
111
+ _check_resolves(rows, resolves)
112
+ when = now or _now_iso()
113
+ row = {
114
+ "id": _new_entry_id(when, rows),
115
+ "kind": kind,
116
+ "body": body,
117
+ "createdAt": when,
118
+ "taskGroup": task[0] if task is not None else "",
119
+ "taskId": task[1] if task is not None else "",
120
+ "resolves": resolves,
121
+ }
122
+ try:
123
+ append_jsonl(path, row)
124
+ except OSError as exc:
125
+ raise ManagerError(f"failed to write {path}: {exc.strerror or exc}") from exc
126
+ return row
@@ -4,7 +4,7 @@ from __future__ import annotations
4
4
  import shlex
5
5
  from pathlib import Path
6
6
 
7
- from okstra_ctl.jsonl import append_jsonl, read_jsonl
7
+ from okstra_ctl.jsonl import read_jsonl
8
8
  from okstra_ctl.phases.discussion.followup import RECOMMENDED_PHASE as DISCUSSION_FOLLOW_UP_PHASE
9
9
  from okstra_ctl.phases.discussion.followup import brief_revision_ref
10
10
  from okstra_ctl.phases.discussion.store import same_task
@@ -19,7 +19,7 @@ from .manager_paths import (
19
19
  snapshots_json_path,
20
20
  task_manifest_path,
21
21
  )
22
- from .manager_store import ManagerError, _now_iso, _read_json, _read_json_default, _write_json
22
+ from .manager_store import ManagerError, _now_iso, _read_json, _read_json_default, _write_json, record_event
23
23
  from .manager_sync import _snapshot_child, summary_bucket
24
24
 
25
25
 
@@ -205,7 +205,7 @@ def _record_launch_prepared(
205
205
  )
206
206
  child["launch"] = launch
207
207
  _write_json(children_json_path(home, manager_id, task_group, task_id), children)
208
- append_jsonl(
208
+ record_event(
209
209
  events_jsonl_path(home, manager_id, task_group, task_id),
210
210
  {
211
211
  "event": "child-launch-prepared",
@@ -0,0 +1,221 @@
1
+ """Merge manager activity files for `okstra manager log`."""
2
+ from __future__ import annotations
3
+
4
+ from collections.abc import Iterator
5
+ from dataclasses import dataclass
6
+ from datetime import datetime, timezone
7
+ from pathlib import Path
8
+ from typing import TypedDict
9
+
10
+ from .manager_journal import JOURNAL_ORIGIN, is_open_followup, open_followups_oldest_first, resolved_entry_ids
11
+ from .manager_paths import directives_jsonl_path, events_jsonl_path, journal_jsonl_path, manager_events_jsonl_path
12
+ from .manager_store import ManagerError, _read_json, _task_manifest_paths, load_manager, read_jsonl_rows, task_selection
13
+
14
+ DEFAULT_LIMIT = 50
15
+ MAX_LIMIT = 1000
16
+ MANAGER_EVENT = "manager-event"
17
+ TASK_EVENT = "task-event"
18
+ DIRECTIVE = "directive"
19
+ JOURNAL = JOURNAL_ORIGIN
20
+ _NO_TASK = ("", "")
21
+
22
+
23
+ class ActivityEntry(TypedDict):
24
+ origin: str
25
+ kind: str
26
+ createdAt: str
27
+ taskGroup: str
28
+ taskId: str
29
+ row: dict
30
+
31
+
32
+ def _since_floor(value: str) -> str:
33
+ try:
34
+ parsed = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
35
+ if parsed.tzinfo is None:
36
+ parsed = parsed.replace(tzinfo=timezone.utc)
37
+ return parsed.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
38
+ except (ValueError, OverflowError) as exc:
39
+ raise ManagerError(f"--since must be an ISO date or time: {value!r}") from exc
40
+
41
+
42
+ def _task_identities(home: Path, manager_id: str) -> list[tuple[str, str]]:
43
+ """Read (task group, task id) from manifests only, so other task files cannot stop the log."""
44
+ load_manager(home, manager_id)
45
+ identities = []
46
+ for path in _task_manifest_paths(home, manager_id):
47
+ manifest = _read_json(path)
48
+ identities.append((str(manifest.get("taskGroup") or ""), str(manifest.get("taskId") or "")))
49
+ return sorted(identities)
50
+
51
+
52
+ def _sources(home: Path, manager_id: str) -> list[tuple[str, Path, tuple[str, str]]]:
53
+ sources = [(MANAGER_EVENT, manager_events_jsonl_path(home, manager_id), _NO_TASK)]
54
+ for group, task_id in _task_identities(home, manager_id):
55
+ sources.append((TASK_EVENT, events_jsonl_path(home, manager_id, group, task_id), (group, task_id)))
56
+ sources.append((DIRECTIVE, directives_jsonl_path(home, manager_id, group, task_id), (group, task_id)))
57
+ sources.append((JOURNAL, journal_jsonl_path(home, manager_id), _NO_TASK))
58
+ return sources
59
+
60
+
61
+ def _matches_task(identity: tuple[str, str], row: dict, task: tuple[str, str] | None) -> bool:
62
+ """Whether a row belongs to the `--task-group` / `--task-id` selection.
63
+
64
+ Task files belong to their own task. Manager-level rows (manager events and journal
65
+ entries) belong to a task they name, which includes removals and unlinks recorded
66
+ after the task's own files are gone.
67
+ """
68
+ if task is None:
69
+ return True
70
+ if identity != _NO_TASK:
71
+ return identity == task
72
+ group, task_id = task
73
+ if (row.get("taskGroup"), row.get("taskId")) == task:
74
+ return True
75
+ event = row.get("event")
76
+ if event == "task-group-removed":
77
+ return row.get("taskGroup") == group and task_id in (row.get("taskIds") or [])
78
+ if event == "project-unlinked":
79
+ named = row.get("tasks") or []
80
+ return any(isinstance(item, dict) and (item.get("taskGroup"), item.get("taskId")) == task for item in named)
81
+ return False
82
+
83
+
84
+ def _reads_file(identity: tuple[str, str], task: tuple[str, str] | None) -> bool:
85
+ """Manager-level files are always read; a task's own files only for that task."""
86
+ return identity == _NO_TASK or _matches_task(identity, {}, task)
87
+
88
+
89
+ def _kind(origin: str, row: dict) -> str:
90
+ if origin == DIRECTIVE:
91
+ return DIRECTIVE
92
+ if origin == JOURNAL:
93
+ return str(row.get("kind") or "")
94
+ return str(row.get("event") or "")
95
+
96
+
97
+ def _entry(origin: str, identity: tuple[str, str], row: dict) -> ActivityEntry:
98
+ group, task_id = identity
99
+ return {
100
+ "origin": origin,
101
+ "kind": _kind(origin, row),
102
+ "createdAt": str(row.get("createdAt") or ""),
103
+ "taskGroup": group or str(row.get("taskGroup") or ""),
104
+ "taskId": task_id or str(row.get("taskId") or ""),
105
+ "row": row,
106
+ }
107
+
108
+
109
+ def _string_values(value: object) -> Iterator[str]:
110
+ if isinstance(value, str):
111
+ yield value
112
+ elif isinstance(value, dict):
113
+ for child in value.values():
114
+ yield from _string_values(child)
115
+ elif isinstance(value, list):
116
+ for child in value:
117
+ yield from _string_values(child)
118
+
119
+
120
+ def _search_text(entry: ActivityEntry) -> str:
121
+ if entry["origin"] in (DIRECTIVE, JOURNAL):
122
+ return str(entry["row"].get("body") or "")
123
+ return "\n".join(_string_values(entry["row"]))
124
+
125
+
126
+ def _matches_filters(entry: ActivityEntry, kind: str | None, since_utc: str, grep_casefolded: str) -> bool:
127
+ if kind is not None and entry["kind"] != kind:
128
+ return False
129
+ if since_utc and entry["createdAt"] < since_utc:
130
+ return False
131
+ return not grep_casefolded or grep_casefolded in _search_text(entry).casefold()
132
+
133
+
134
+ def _newest_first(entries: list[ActivityEntry]) -> list[ActivityEntry]:
135
+ """Sort by createdAt, newest first.
136
+
137
+ createdAt has one-second resolution. Entries with the same createdAt come in reverse
138
+ read order: a later line of one file comes first, and so does a file read later.
139
+ Files are read manager events first, then each task's events and directives in
140
+ (task group, task id) order, then the journal, so across files a tie does not follow
141
+ write order.
142
+ """
143
+ indexed = sorted(enumerate(entries), key=lambda item: (item[1]["createdAt"], item[0]), reverse=True)
144
+ return [entry for _, entry in indexed]
145
+
146
+
147
+ @dataclass(frozen=True)
148
+ class Activity:
149
+ entries: list[ActivityEntry]
150
+ damaged: list[dict]
151
+ resolved: set[str]
152
+
153
+ def open_followups_oldest_first(self) -> list[ActivityEntry]:
154
+ return open_followups_oldest_first(self.entries, self.resolved)
155
+
156
+
157
+ def merge_activity(
158
+ home: Path,
159
+ manager_id: str,
160
+ *,
161
+ task: tuple[str, str] | None = None,
162
+ kind: str | None = None,
163
+ since_utc: str = "",
164
+ grep_casefolded: str = "",
165
+ ) -> Activity:
166
+ """Every matching entry newest first, unpaged, with damaged lines per file and resolved journal ids.
167
+
168
+ `since_utc` must already be normalised by `_since_floor` and `grep_casefolded` must be
169
+ casefolded. `resolved` comes from the whole journal, whatever the filters keep.
170
+ """
171
+ entries: list[ActivityEntry] = []
172
+ damaged: list[dict] = []
173
+ resolved: set[str] = set()
174
+ for origin, path, identity in _sources(home, manager_id):
175
+ if not _reads_file(identity, task):
176
+ continue
177
+ rows, invalid_lines = read_jsonl_rows(path)
178
+ if invalid_lines:
179
+ damaged.append({"path": str(path), "lines": invalid_lines})
180
+ if origin == JOURNAL:
181
+ resolved = resolved_entry_ids(rows)
182
+ for row in rows:
183
+ entry = _entry(origin, identity, row)
184
+ if _matches_task(identity, row, task) and _matches_filters(entry, kind, since_utc, grep_casefolded):
185
+ entries.append(entry)
186
+ return Activity(_newest_first(entries), damaged, resolved)
187
+
188
+
189
+ def read_activity_page(
190
+ home: Path,
191
+ manager_id: str,
192
+ *,
193
+ task_group: str | None = None,
194
+ task_id: str | None = None,
195
+ kind: str | None = None,
196
+ since: str | None = None,
197
+ grep: str | None = None,
198
+ open_followups: bool = False,
199
+ limit: int = DEFAULT_LIMIT,
200
+ ) -> dict:
201
+ """One page (`limit` entries) of manager events, task events, directives and journal entries, newest first.
202
+
203
+ `open_followups` keeps only followup journal entries that no journal row resolves.
204
+
205
+ Each entry names the file it came from as `origin` and keeps the stored JSONL
206
+ object under `row`; stored directive and task-split rows have their own `source`.
207
+ """
208
+ task = task_selection(task_group, task_id)
209
+ check_limit(limit, "--limit")
210
+ activity = merge_activity(home, manager_id, task=task, kind=kind,
211
+ since_utc=_since_floor(since) if since else "", grep_casefolded=(grep or "").casefold())
212
+ entries = activity.entries
213
+ if open_followups:
214
+ entries = [entry for entry in entries if is_open_followup(entry, activity.resolved)]
215
+ return {"managerId": manager_id, "matchedCount": len(entries), "entries": entries[:limit],
216
+ "damaged": activity.damaged}
217
+
218
+
219
+ def check_limit(value: int, flag: str) -> None:
220
+ if not 1 <= value <= MAX_LIMIT:
221
+ raise ManagerError(f"{flag} must be between 1 and {MAX_LIMIT}")
@@ -79,6 +79,14 @@ def projects_json_path(home: Path, manager_id: str) -> Path:
79
79
  return manager_root(home, manager_id) / "projects.json"
80
80
 
81
81
 
82
+ def manager_events_jsonl_path(home: Path, manager_id: str) -> Path:
83
+ return manager_root(home, manager_id) / "events.jsonl"
84
+
85
+
86
+ def journal_jsonl_path(home: Path, manager_id: str) -> Path:
87
+ return manager_root(home, manager_id) / "journal.jsonl"
88
+
89
+
82
90
  def task_manifest_path(home: Path, manager_id: str, task_group: str, task_id: str) -> Path:
83
91
  return task_root(home, manager_id, task_group, task_id) / "manifest.json"
84
92