okstra 0.232.0 → 0.233.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 (183) hide show
  1. package/README.md +19 -283
  2. package/dist/cli-registry.mjs +8 -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 +36 -5
  49. package/docs/architecture.md +10 -4
  50. package/docs/cli.md +279 -2
  51. package/docs/contributor-change-matrix.md +1 -2
  52. package/docs/project-structure-overview.md +31 -41
  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/code_review_census.py +93 -2
  77. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  78. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  79. package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
  80. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  81. package/runtime/python/okstra_ctl/code_review_target.py +140 -15
  82. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  83. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  84. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  85. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  86. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  87. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  88. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
  89. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  90. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  91. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  92. package/runtime/python/okstra_ctl/json_boundary.py +33 -6
  93. package/runtime/python/okstra_ctl/manager_cli.py +122 -1
  94. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  95. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  96. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  97. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  98. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  99. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  100. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  101. package/runtime/python/okstra_ctl/manager_sync.py +42 -3
  102. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  103. package/runtime/python/okstra_ctl/material.py +2 -0
  104. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  105. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  106. package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
  107. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  108. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  109. package/runtime/python/okstra_ctl/paths.py +6 -1
  110. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  111. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  112. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
  113. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  114. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  115. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  116. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
  117. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  118. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  119. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
  120. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  121. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  122. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  123. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  124. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  125. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  126. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  127. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  128. package/runtime/python/okstra_ctl/render.py +28 -2
  129. package/runtime/python/okstra_ctl/report_assembly.py +38 -11
  130. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  131. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  132. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  133. package/runtime/python/okstra_ctl/report_language.py +4 -1
  134. package/runtime/python/okstra_ctl/report_narrative.py +179 -7
  135. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  136. package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
  137. package/runtime/python/okstra_ctl/run.py +43 -35
  138. package/runtime/python/okstra_ctl/run_context.py +10 -1
  139. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  140. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  141. package/runtime/python/okstra_ctl/task_query.py +239 -0
  142. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  143. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  144. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  145. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  146. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  147. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  148. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  149. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  150. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  151. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  152. package/runtime/python/okstra_project/state.py +20 -0
  153. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  154. package/runtime/python/okstra_token_usage/cli.py +23 -10
  155. package/runtime/python/okstra_token_usage/collect.py +25 -22
  156. package/runtime/python/okstra_token_usage/policy.py +193 -0
  157. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  158. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  159. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  160. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  161. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  162. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  163. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  164. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  165. package/runtime/skills/okstra-code-review/SKILL.md +58 -50
  166. package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
  167. package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
  168. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  169. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  170. package/runtime/skills/okstra-manager/SKILL.md +24 -0
  171. package/runtime/skills/okstra-memory/SKILL.md +1 -1
  172. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  173. package/runtime/skills/okstra-run/SKILL.md +55 -183
  174. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  175. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  176. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  177. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  178. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  179. package/runtime/templates/manager/view.template.html +4 -0
  180. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  181. package/runtime/templates/trace/trace.template.md +42 -0
  182. package/runtime/validators/checks/fixtures-02.py +25 -33
  183. package/runtime/validators/validate-run.py +93 -36
@@ -393,15 +393,14 @@ class _Validator:
393
393
  self.errors.append(f"{_format_path(path)}: {message}")
394
394
 
395
395
 
396
- def follow_up_task_rules(schema: Mapping[str, Any], task_type: str) -> tuple[str, ...]:
397
- """이 task type 의 `followUpTasks` 에 스키마가 못 박은 행 규칙, 저작 문장으로.
398
-
399
- `allOf` 의 if/then 가지 하나가 비종결 task type 에 phase-continuation 행
400
- 하나를 요구하고(`minItems`, `contains.origin.const`), `FollowUpRow` 의
401
- 가지가 그 행의 `autoSpawn` 을 `no` 로 고정한다. 작성자는 둘 다 읽지 못해
402
- 빈 배열을 냈고 조립이 `array length 0 < minItems 1` 로 거절했다(2026-09-09
403
- 실측, dev-10642 requirements-discovery: 이 계열로만 라운드 3회). 가지가
404
- 이 task type 에 없으면 빈 튜플이다 — 제약이 없다는 뜻이지 실패가 아니다.
396
+ def follow_up_task_rules(
397
+ schema: Mapping[str, Any], task_type: str, *, authoring_format: str = "markdown-v1",
398
+ ) -> tuple[str, ...]:
399
+ """Describe schema-pinned follow-up rows in the declared authoring format.
400
+
401
+ Task-specific conditions supply minimum counts and the continuation origin;
402
+ FollowUpRow conditions supply pinned values such as autoSpawn. A task with
403
+ no matching condition has no additional rules.
405
404
  """
406
405
  def _task_matches(condition: Any) -> bool:
407
406
  if not isinstance(condition, dict):
@@ -413,6 +412,10 @@ def follow_up_task_rules(schema: Mapping[str, Any], task_type: str) -> tuple[str
413
412
  allowed = [selector["const"]]
414
413
  return isinstance(allowed, list) and task_type in allowed
415
414
 
415
+ follow_up_label = "followUpTasks" if authoring_format == "json-v1" else "Follow Up Tasks"
416
+ origin_label = "origin" if authoring_format == "json-v1" else "Origin"
417
+ row_label = "array item(s)" if authoring_format == "json-v1" else "`- Item N` row(s)"
418
+ key_note = "" if authoring_format == "json-v1" else "(schema key; write its Title Case label) "
416
419
  rules: list[str] = []
417
420
  for branch in schema.get("allOf") or []:
418
421
  if not isinstance(branch, dict) or not _task_matches(branch.get("if")):
@@ -426,12 +429,12 @@ def follow_up_task_rules(schema: Mapping[str, Any], task_type: str) -> tuple[str
426
429
  ).get("const")
427
430
  if isinstance(min_items, int) and min_items > 0:
428
431
  rules.append(
429
- f"`Follow Up Tasks`: at least {min_items} `- Item N` row(s) for task "
432
+ f"`{follow_up_label}`: at least {min_items} {row_label} for task "
430
433
  f"type `{task_type}`; an empty list is refused."
431
434
  )
432
435
  if isinstance(origin, str) and origin:
433
436
  rules.append(
434
- f"`Follow Up Tasks`: one row must carry `Origin` `{origin}` — the "
437
+ f"`{follow_up_label}`: one row must carry `{origin_label}` `{origin}` — the "
435
438
  "next phase of this task."
436
439
  )
437
440
  row_schema = (schema.get("$defs") or {}).get("FollowUpRow") or {}
@@ -445,8 +448,8 @@ def follow_up_task_rules(schema: Mapping[str, Any], task_type: str) -> tuple[str
445
448
  for key, value in pinned.items():
446
449
  if isinstance(value, dict) and "const" in value:
447
450
  rules.append(
448
- f"`Follow Up Tasks`: the `{origin}` row's `{key}` "
449
- f"(schema key; write its Title Case label) is exactly "
451
+ f"`{follow_up_label}`: the `{origin}` row's `{key}` "
452
+ f"{key_note}is exactly "
450
453
  f"`{value['const']}`."
451
454
  )
452
455
  return tuple(rules)
@@ -492,19 +495,14 @@ def verdict_token_rule(schema: Mapping[str, Any], task_type: str) -> tuple[str,
492
495
  return _walk(dict(schema))
493
496
 
494
497
 
495
- def task_block_rules(schema: Mapping[str, Any], block_key: str) -> tuple[str, ...]:
496
- """최상위 필드(`properties[block_key]`)가 요구하는 모양을 한
497
- 객체당 한 줄의 저작 계약 문장으로 편다.
498
+ def task_block_rules(
499
+ schema: Mapping[str, Any], block_key: str, *, authoring_format: str = "markdown-v1",
500
+ ) -> tuple[str, ...]:
501
+ """Describe a top-level block using the declared format's value grammar.
498
502
 
499
- 리드는 report-writer 지시문을 쓸 때 블록 안쪽의 필수 필드·식별자 패턴·
500
- 정수 필드·고정 길이 배열을 알 길이 프롬프트 경로에 없어 스키마 JSON 을
501
- 손으로 파싱했고, 그래도 놓친 만큼 같은 리포트를 다시 썼다(2026-09-03 실측,
502
- dev-10626 implementation-option-selection: 네 회차). 여기서 뽑아 합성 묶음의
503
- 저작 계약에 싣는다. 필드가 없으면 빈 튜플이다.
504
-
505
- 경로는 스키마 키다(`rankedOptions[]` 는 `- Item N` 목록의 각 항목). 같은
506
- 정의(`$ref`)가 두 경로에 나오면 두 번째는 첫 경로를 가리킨다 — 랭킹 옵션과
507
- 감사 항목이 하위 구조 여섯 개를 공유한다.
503
+ Emit one rule per object using exact schema-key paths; [] denotes each
504
+ array item. Repeated references point to their first described path.
505
+ Schema values remain unchanged; only the authoring vocabulary varies.
508
506
  """
509
507
  root = dict(schema)
510
508
  block = (root.get("properties") or {}).get(block_key)
@@ -514,14 +512,14 @@ def task_block_rules(schema: Mapping[str, Any], block_key: str) -> tuple[str, ..
514
512
  described: dict[str, str] = {}
515
513
  resolved, _ = _resolved(root, block)
516
514
  if resolved.get("type") == "object" or "properties" in resolved:
517
- _describe_object(root, block, block_key, lines, described)
515
+ _describe_object(root, block, block_key, lines, described, authoring_format)
518
516
  else:
519
517
  nested: list[tuple[str, Any]] = []
520
- constraint = _describe_property(root, block, block_key, nested)
518
+ constraint = _describe_property(root, block, block_key, nested, authoring_format)
521
519
  if constraint:
522
520
  lines.append(f"`{block_key}`: {constraint}")
523
521
  for child_path, child in nested:
524
- _describe_object(root, child, child_path, lines, described)
522
+ _describe_object(root, child, child_path, lines, described, authoring_format)
525
523
  return tuple(lines)
526
524
 
527
525
 
@@ -558,6 +556,7 @@ def _resolved(root: dict, node: Any) -> tuple[dict, str | None]:
558
556
 
559
557
  def _describe_object(
560
558
  root: dict, node: Any, path: str, lines: list[str], described: dict[str, str],
559
+ authoring_format: str,
561
560
  ) -> None:
562
561
  schema, ref_name = _resolved(root, node)
563
562
  if ref_name and ref_name in described:
@@ -575,18 +574,19 @@ def _describe_object(
575
574
  parts.append("optional " + ", ".join(f"`{key}`" for key in optional))
576
575
  nested: list[tuple[str, Any]] = []
577
576
  for key, value in properties.items():
578
- constraint = _describe_property(root, value, f"{path}.{key}", nested)
577
+ constraint = _describe_property(root, value, f"{path}.{key}", nested, authoring_format)
579
578
  if constraint:
580
579
  parts.append(f"`{key}` {constraint}")
581
580
  lines.append(f"`{path}`: " + "; ".join(parts))
582
581
  for child_path, child in nested:
583
- _describe_object(root, child, child_path, lines, described)
582
+ _describe_object(root, child, child_path, lines, described, authoring_format)
584
583
 
585
584
 
586
585
  def _describe_property(
587
586
  root: dict, node: Any, path: str, nested: list[tuple[str, Any]],
587
+ authoring_format: str,
588
588
  ) -> str:
589
- """한 속성의 제약을 한 구절로. 객체 자식은 `nested` 에 넣어 자기 줄을 받는다."""
589
+ """Describe one field and queue nested objects for their own rule lines."""
590
590
  schema, _ref = _resolved(root, node)
591
591
  branches = schema.get("oneOf") or schema.get("anyOf") or []
592
592
  nullable = False
@@ -601,7 +601,8 @@ def _describe_property(
601
601
  if "null" in types:
602
602
  nullable = True
603
603
  types = [item for item in types if item != "null"]
604
- suffix = " or `_none_`" if nullable else ""
604
+ null_value = "`null`" if authoring_format == "json-v1" else "`_none_`"
605
+ suffix = f" or {null_value}" if nullable else ""
605
606
  if "const" in schema:
606
607
  return f"exactly `{schema['const']}`{suffix}"
607
608
  if isinstance(schema.get("enum"), list):
@@ -610,7 +611,7 @@ def _describe_property(
610
611
  nested.append((path, schema.get("__branch", node)))
611
612
  return f"object (see `{path}`){suffix}"
612
613
  if types == ["array"] or "items" in schema or "prefixItems" in schema:
613
- return _describe_array(root, schema, path, nested) + suffix
614
+ return _describe_array(root, schema, path, nested, authoring_format) + suffix
614
615
  if types == ["integer"]:
615
616
  return "integer" + _range(schema) + suffix
616
617
  if types == ["number"]:
@@ -625,11 +626,13 @@ def _describe_property(
625
626
 
626
627
  def _describe_array(
627
628
  root: dict, schema: dict, path: str, nested: list[tuple[str, Any]],
629
+ authoring_format: str,
628
630
  ) -> str:
629
631
  minimum = schema.get("minItems")
630
632
  maximum = schema.get("maxItems")
631
633
  if maximum == 0:
632
- return "must be empty (`> _none_`)"
634
+ empty_value = "[]" if authoring_format == "json-v1" else "> _none_"
635
+ return f"must be empty (`{empty_value}`)"
633
636
  if minimum is not None and minimum == maximum:
634
637
  size = f"exactly {maximum} items"
635
638
  else:
@@ -10,8 +10,7 @@ from pathlib import Path
10
10
  from typing import Any, Mapping
11
11
 
12
12
  from .convergence_store import write_json_atomic
13
- from .final_report_schema import load_schema_version
14
- from .report_narrative import parse_narrative, writer_owned_data
13
+ from .report_narrative import load_writer_input, writer_owned_data
15
14
  from .json_boundary import load_owned_object
16
15
  from .plan_item_evidence import dependency_scopes, reusable_item_ids
17
16
  from .plan_items import (
@@ -579,7 +578,7 @@ def _load_data(path: str, *, option: str) -> dict:
579
578
 
580
579
 
581
580
  _CLI_EPILOG = r"""Usage:
582
- okstra incremental-carry --prev-data <path> --cur-narrative <path> \
581
+ okstra incremental-carry --run-manifest <path> --prev-data <path> --cur-narrative <path> \
583
582
  --state <path> --prev-seq <str> --carry-stages <csv> \
584
583
  --reverify-stages <csv> --out-state <path>
585
584
  okstra incremental-carry --prev-data <path> --cur-data <path> \
@@ -600,7 +599,8 @@ def main(argv: list[str]) -> int:
600
599
  ap.add_argument("--prev-data", required=True, help="prior run final-report data.json")
601
600
  current = ap.add_mutually_exclusive_group(required=True)
602
601
  current.add_argument("--cur-data", help="historical v2 current data.json")
603
- current.add_argument("--cur-narrative", help="contract v3 current narrative Markdown")
602
+ current.add_argument("--cur-narrative", help="contract v3 current writer input")
603
+ ap.add_argument("--run-manifest", type=Path)
604
604
  ap.add_argument("--state", help="contract v3 convergence-owned plan state")
605
605
  ap.add_argument("--prev-seq", required=True, help="prior run seq, tagged onto carried items")
606
606
  ap.add_argument(
@@ -639,9 +639,8 @@ def main(argv: list[str]) -> int:
639
639
  if carry_stages is None or reverify_stages is None:
640
640
  raise CarryError("contract v3 carry requires both stage sets")
641
641
  try:
642
- narrative = parse_narrative(
643
- Path(args.cur_narrative).read_text(encoding="utf-8"),
644
- load_schema_version("3.0"),
642
+ narrative = load_writer_input(
643
+ Path(args.cur_narrative), run_manifest=args.run_manifest,
645
644
  )
646
645
  except (OSError, UnicodeError, ValueError) as exc:
647
646
  raise CarryError(f"--cur-narrative could not be read: {exc}") from exc
@@ -25,9 +25,11 @@ from .agent.invocation import (
25
25
  verify_agent_invocation,
26
26
  )
27
27
  from .path_hints import hydrate_active_run_context
28
+ from .coverage_census import CensusError
29
+ from .phases.improvement_discovery.resolved_census import prepare_resolved_lens_census
28
30
  from .verification_dispatch import VerificationDispatchError, seal_dispatch_generation
29
31
  from .verification_invocation import VerificationGenerationReference
30
- from .report_inputs import report_narrative_path, uses_report_contract_v3
32
+ from .report_inputs import report_authoring_format, report_narrative_path, uses_report_contract_v3
31
33
  from .report_synthesis_packet import (
32
34
  ReportSynthesisPacketError,
33
35
  materialize_report_synthesis_packet,
@@ -352,6 +354,11 @@ def _materialize_initial_prompts(
352
354
  _resolve_prompt_item(context, worker)
353
355
  for worker in request.workers
354
356
  ]
357
+ if any(item.plan.audience == "analysis" for item in resolved_items):
358
+ try:
359
+ prepare_resolved_lens_census(context.project_root, context.manifest)
360
+ except (CensusError, JsonBoundaryError, OSError, UnicodeError) as exc:
361
+ raise InitialPromptMaterializationError("required_input_missing", str(exc)) from exc
355
362
  items: list[_PromptItem] = []
356
363
  completed = False
357
364
  try:
@@ -785,7 +792,7 @@ def _report_writer_packet_source(
785
792
  if not _report_writer_reads_a_packet(context, plan):
786
793
  return None
787
794
  _, markdown_path = report_synthesis_packet_paths(
788
- _report_writer_narrative_path(context)
795
+ _report_writer_narrative_path(context), report_authoring_format(context.manifest),
789
796
  )
790
797
  return AgentInstructionSource(
791
798
  "project",
@@ -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