okstra 0.231.1 → 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 (265) hide show
  1. package/README.md +19 -271
  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/memory/memory.mjs +9 -55
  10. package/dist/commands/memory/memory.mjs.map +1 -1
  11. package/dist/commands/trace/capacity.d.mts +12 -0
  12. package/dist/commands/trace/capacity.mjs +21 -0
  13. package/dist/commands/trace/capacity.mjs.map +1 -0
  14. package/dist/commands/trace/model.d.mts +89 -0
  15. package/dist/commands/trace/model.mjs +251 -0
  16. package/dist/commands/trace/model.mjs.map +1 -0
  17. package/dist/commands/trace/progression.d.mts +11 -0
  18. package/dist/commands/trace/progression.mjs +194 -0
  19. package/dist/commands/trace/progression.mjs.map +1 -0
  20. package/dist/commands/trace/review.d.mts +7 -0
  21. package/dist/commands/trace/review.mjs +51 -0
  22. package/dist/commands/trace/review.mjs.map +1 -0
  23. package/dist/commands/trace/task-link.d.mts +18 -0
  24. package/dist/commands/trace/task-link.mjs +72 -0
  25. package/dist/commands/trace/task-link.mjs.map +1 -0
  26. package/dist/commands/trace/trace.d.mts +1 -0
  27. package/dist/commands/trace/trace.mjs +293 -0
  28. package/dist/commands/trace/trace.mjs.map +1 -0
  29. package/dist/lib/bounded-file.d.mts +1 -0
  30. package/dist/lib/bounded-file.mjs +36 -0
  31. package/dist/lib/bounded-file.mjs.map +1 -0
  32. package/dist/lib/config-store.d.mts +34 -0
  33. package/dist/lib/config-store.mjs +70 -0
  34. package/dist/lib/config-store.mjs.map +1 -0
  35. package/dist/lib/file-lock.mjs +4 -5
  36. package/dist/lib/file-lock.mjs.map +1 -1
  37. package/dist/lib/input-limit.d.mts +4 -0
  38. package/dist/lib/input-limit.mjs +8 -0
  39. package/dist/lib/input-limit.mjs.map +1 -0
  40. package/dist/lib/memory-auto-register.d.mts +1 -0
  41. package/dist/lib/memory-auto-register.mjs +98 -0
  42. package/dist/lib/memory-auto-register.mjs.map +1 -0
  43. package/dist/lib/memory-entry-contract.d.mts +12 -0
  44. package/dist/lib/memory-entry-contract.mjs +46 -0
  45. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  46. package/dist/lib/python-helper.d.mts +1 -1
  47. package/dist/lib/python-helper.mjs +3 -2
  48. package/dist/lib/python-helper.mjs.map +1 -1
  49. package/dist/lib/record-secrets.d.mts +1 -0
  50. package/dist/lib/record-secrets.mjs +28 -0
  51. package/dist/lib/record-secrets.mjs.map +1 -0
  52. package/dist/lib/report-language-tag.d.mts +1 -0
  53. package/dist/lib/report-language-tag.mjs +4 -0
  54. package/dist/lib/report-language-tag.mjs.map +1 -0
  55. package/dist/lib/report-language.d.mts +1 -0
  56. package/dist/lib/report-language.mjs +50 -0
  57. package/dist/lib/report-language.mjs.map +1 -0
  58. package/dist/lib/skill-catalog.mjs +3 -0
  59. package/dist/lib/skill-catalog.mjs.map +1 -1
  60. package/dist/lib/types.d.mts +2 -1
  61. package/docs/architecture/storage-model.md +163 -5
  62. package/docs/architecture.md +17 -4
  63. package/docs/cli.md +511 -0
  64. package/docs/contributor-change-matrix.md +1 -2
  65. package/docs/project-structure-overview.md +33 -42
  66. package/package.json +1 -1
  67. package/runtime/BUILD.json +2 -2
  68. package/runtime/agents/common.json +8 -8
  69. package/runtime/agents/operations/trace-interface-review.json +6 -0
  70. package/runtime/agents/operations/trace-scope-review.json +6 -0
  71. package/runtime/agents/roles/verifier.json +2 -4
  72. package/runtime/bin/okstra-provider-exec.py +10 -4
  73. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  74. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  75. package/runtime/prompts/coding-preflight/clean-code.md +88 -286
  76. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  77. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  78. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  79. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  80. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  81. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  82. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  83. package/runtime/prompts/coding-preflight/overview.md +25 -38
  84. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  85. package/runtime/prompts/duties/code-reviewer.json +15 -18
  86. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  87. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  88. package/runtime/prompts/host-orchestration/README.md +18 -9
  89. package/runtime/prompts/launch.template.md +3 -2
  90. package/runtime/prompts/lead/context-loader.md +2 -0
  91. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  92. package/runtime/prompts/lead/report-writer.md +6 -6
  93. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  94. package/runtime/prompts/profiles/_common-contract.md +1 -1
  95. package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
  96. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
  97. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  98. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
  99. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  100. package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
  101. package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
  102. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  103. package/runtime/python/okstra_ctl/code_review_census.py +162 -7
  104. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  105. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  106. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  107. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  108. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  109. package/runtime/python/okstra_ctl/code_review_scope.py +49 -9
  110. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  111. package/runtime/python/okstra_ctl/code_review_target.py +212 -13
  112. package/runtime/python/okstra_ctl/consumers.py +12 -9
  113. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  114. package/runtime/python/okstra_ctl/design_review.py +207 -0
  115. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  116. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  117. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  118. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  119. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  120. package/runtime/python/okstra_ctl/doctor.py +8 -25
  121. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  122. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  123. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  124. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  125. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  126. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  127. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  128. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  129. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  130. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  131. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  132. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  133. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +300 -0
  134. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  135. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  136. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  137. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  138. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  139. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  140. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  141. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  142. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  143. package/runtime/python/okstra_ctl/json_boundary.py +51 -5
  144. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  145. package/runtime/python/okstra_ctl/manager_cli.py +148 -1
  146. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  147. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  148. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  149. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  150. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  151. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  152. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  153. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  154. package/runtime/python/okstra_ctl/manager_sync.py +45 -25
  155. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  156. package/runtime/python/okstra_ctl/material.py +2 -0
  157. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  158. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  159. package/runtime/python/okstra_ctl/model_io/renderers.py +16 -2
  160. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  161. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  162. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  163. package/runtime/python/okstra_ctl/paths.py +6 -1
  164. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  165. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  166. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  167. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
  168. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +23 -8
  169. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
  170. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
  171. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  172. package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
  173. package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
  174. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  175. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  176. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -9
  177. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  178. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  179. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +6 -6
  180. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  181. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  182. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  183. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  184. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  185. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  186. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  187. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  188. package/runtime/python/okstra_ctl/render.py +28 -2
  189. package/runtime/python/okstra_ctl/report_assembly.py +53 -11
  190. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  191. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  192. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  193. package/runtime/python/okstra_ctl/report_language.py +4 -1
  194. package/runtime/python/okstra_ctl/report_narrative.py +182 -7
  195. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  196. package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
  197. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  198. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  199. package/runtime/python/okstra_ctl/run.py +67 -36
  200. package/runtime/python/okstra_ctl/run_context.py +10 -1
  201. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  202. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  203. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  204. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  205. package/runtime/python/okstra_ctl/task_query.py +239 -0
  206. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  207. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  208. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  209. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  210. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  211. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  212. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  213. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  214. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  215. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  216. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  217. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  218. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  219. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  220. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  221. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  222. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  223. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  224. package/runtime/python/okstra_project/__init__.py +2 -0
  225. package/runtime/python/okstra_project/dirs.py +18 -0
  226. package/runtime/python/okstra_project/state.py +45 -20
  227. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  228. package/runtime/python/okstra_token_usage/cli.py +23 -10
  229. package/runtime/python/okstra_token_usage/collect.py +25 -22
  230. package/runtime/python/okstra_token_usage/policy.py +193 -0
  231. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  232. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  233. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  234. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  235. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  236. package/runtime/schemas/record-secret-patterns.json +41 -0
  237. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  238. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  239. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  240. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  241. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  242. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  243. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  244. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  245. package/runtime/skills/okstra-code-review/SKILL.md +92 -136
  246. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  247. package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
  248. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  249. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  250. package/runtime/skills/okstra-manager/SKILL.md +31 -0
  251. package/runtime/skills/okstra-memory/SKILL.md +8 -1
  252. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  253. package/runtime/skills/okstra-run/SKILL.md +55 -183
  254. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  255. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  256. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  257. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  258. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  259. package/runtime/templates/implementation-worker-preamble.md +4 -9
  260. package/runtime/templates/manager/view.template.html +4 -0
  261. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  262. package/runtime/templates/trace/trace.template.md +42 -0
  263. package/runtime/templates/worker-prompt-preamble.md +4 -12
  264. package/runtime/validators/checks/fixtures-02.py +25 -33
  265. package/runtime/validators/validate-run.py +107 -38
@@ -35,9 +35,9 @@ from ...report_corrections import (
35
35
  load_corrections,
36
36
  render_applied_narrative,
37
37
  )
38
- from ...report_inputs import report_narrative_path, uses_report_contract_v3
38
+ from ...report_inputs import report_authoring_format, report_narrative_path, uses_report_contract_v3
39
39
  from ...paths import STAGE_VALIDATOR_RELATIVE, find_asset_root
40
- from ...report_narrative import task_narrative_errors
40
+ from ...report_narrative import load_report_narrative, task_narrative_errors
41
41
  from ...report_synthesis_packet import (
42
42
  ReportSynthesisPacketError,
43
43
  ReportSynthesisPacket,
@@ -68,13 +68,13 @@ def run_corrections_check(
68
68
  if not uses_report_contract_v3(manifest):
69
69
  return CorrectionsCheck(ledger, (), None, False, {}, (
70
70
  "owner=lead correction=ledger path=- reason=corrections require report "
71
- "contract 3.0 (a Markdown narrative); this run uses an older contract",
71
+ "contract 3.0; this run uses an older contract",
72
72
  ))
73
73
  contract = manifest.get("agentContract")
74
74
  authorized = contract.get("authorizedPaths") if isinstance(contract, Mapping) else None
75
75
  authorized = authorized if isinstance(authorized, Mapping) else {}
76
76
  try:
77
- base_path = _authorized_path(
77
+ _authorized_path(
78
78
  project_root,
79
79
  str(ledger.get("baseNarrativePath") or ""),
80
80
  authorized.get("resultRoots"),
@@ -85,6 +85,19 @@ def run_corrections_check(
85
85
  return CorrectionsCheck(ledger, (), None, False, {}, (
86
86
  f"owner=lead correction=ledger path={ledger.get('baseNarrativePath')} reason={exc}",
87
87
  ))
88
+ # Keep the original spelling so the JSON boundary can inspect symlink components.
89
+ base_path = Path(str(ledger["baseNarrativePath"]))
90
+ if not base_path.is_absolute():
91
+ base_path = project_root / base_path
92
+ try:
93
+ input_format = report_authoring_format(manifest)
94
+ load_report_narrative(project_root, manifest, load_schema_version("3.0"),
95
+ path=base_path, structure_only=True,
96
+ allow_preserved_attempt=True)
97
+ except (OSError, UnicodeError, ValueError) as exc:
98
+ return CorrectionsCheck(ledger, (), None, False, {}, (
99
+ f"owner=lead correction=ledger path={base_path} reason=base narrative does not parse: {exc}",
100
+ ))
88
101
  try:
89
102
  packet = build_report_synthesis_packet(
90
103
  project_root=project_root,
@@ -109,6 +122,7 @@ def run_corrections_check(
109
122
  rewrite_results is None and any(item.get("kind") == "rewrite" for item in ledger["corrections"]),
110
123
  ),
111
124
  rewrite_results=rewrite_results,
125
+ input_format=input_format,
112
126
  )
113
127
 
114
128
 
@@ -195,8 +209,7 @@ def run_corrections_apply(
195
209
  """
196
210
  if not uses_report_contract_v3(manifest):
197
211
  raise AgentPromptCliError(
198
- "apply-corrections requires report contract 3.0 (a Markdown "
199
- "narrative); this run uses an older contract"
212
+ "apply-corrections requires report contract 3.0; this run uses an older contract"
200
213
  )
201
214
  narrative_path = report_narrative_path(project_root, manifest)
202
215
  events_value = manifest.get("leadEventsPath")
@@ -225,12 +238,14 @@ def run_corrections_apply(
225
238
  )
226
239
  return _apply_checked_corrections(
227
240
  project_root, manifest_path, narrative_path, corrections_path, check, rewrite_results_path,
241
+ input_format=report_authoring_format(manifest),
228
242
  )
229
243
 
230
244
 
231
245
  def _apply_checked_corrections(
232
246
  project_root: Path, manifest_path: Path, narrative_path: Path,
233
247
  corrections_path: Path, check: CorrectionsCheck, rewrite_results_path: Path | None,
248
+ *, input_format: str = "markdown-v1",
234
249
  ) -> dict[str, Any]:
235
250
  corrections_rel = _relative(project_root, corrections_path)
236
251
  if check.defects:
@@ -253,7 +268,7 @@ def _apply_checked_corrections(
253
268
  "baseNarrativePath is the live narrative "
254
269
  f"({_relative(project_root, narrative_path)}); applying would "
255
270
  "overwrite the only copy of the attempt being corrected. Copy it "
256
- "to worker-results/report-writer-narrative-a<N>-<task-type>-<seq>.md "
271
+ f"to worker-results/report-writer-narrative-a<N>-<task-type>-<seq>{narrative_path.suffix} "
257
272
  "first and point the ledger at that copy"
258
273
  )
259
274
  previous = _already_applied(project_root, manifest_path, corrections_rel)
@@ -265,7 +280,7 @@ def _apply_checked_corrections(
265
280
  )
266
281
  applied_ids = [str(item.get("id")) for item in check.corrections]
267
282
  narrative_rel = _relative(project_root, narrative_path)
268
- rendered = render_applied_narrative(check, load_schema_version("3.0"))
283
+ rendered = render_applied_narrative(check, load_schema_version("3.0"), input_format=input_format)
269
284
  if narrative_path.is_file() and narrative_path.read_text(encoding="utf-8") not in (
270
285
  base_path.read_text(encoding="utf-8"), rendered,
271
286
  ):
@@ -32,7 +32,10 @@ from ..invocation import (
32
32
  )
33
33
  from ...assignment_environment import load_assignment_context
34
34
  from ..standalone import StandaloneInvocationRequest, prepare_standalone_invocation
35
+ from ...code_review_invocation import CodeReviewInputs
35
36
  from ...path_hints import hydrate_active_run_context
37
+ from ...json_boundary import JsonBoundaryError, OUTSIDE_WORKER_RESULT_LANES
38
+ from ...phases.improvement_discovery.resolved_census import prepare_resolved_lens_census
36
39
  from ...worker_prompt_headers import worker_prompt_headers
37
40
  from ...worker_prompt_contract import (
38
41
  complete_reverify_instruction,
@@ -43,6 +46,7 @@ from ...worker_prompt_policy import (
43
46
  critic_assignment_ref,
44
47
  is_critic_verification,
45
48
  is_verification_dispatch_kind,
49
+ resolve_prompt_plan_for_manifest,
46
50
  )
47
51
  from ...paths import okstra_home
48
52
  from ...contract_refreeze import (
@@ -57,8 +61,8 @@ from ...initial_prompt_materialization import (
57
61
  )
58
62
  from ...final_report_paths import final_report_data_path
59
63
  from ...final_report_schema import load_schema_version
60
- from ...report_inputs import report_narrative_path, uses_report_contract_v3
61
- from ...report_narrative import NarrativeContractError, parse_narrative_structure
64
+ from ...report_inputs import report_authoring_format, report_narrative_path, uses_report_contract_v3
65
+ from ...report_narrative import NarrativeContractError, load_report_narrative
62
66
  from ...report_synthesis_packet import (
63
67
  ReportSynthesisPacketError,
64
68
  materialize_report_synthesis_packet,
@@ -134,6 +138,9 @@ def _materialize_run(
134
138
  "model-role": args.model_role,
135
139
  "model": args.model,
136
140
  "purpose": args.purpose,
141
+ **{f"review-{name}": getattr(args, f"review_{name}", None)
142
+ for name in ("policy", "census", "base", "head")},
143
+ "review-resource": getattr(args, "review_resource", ()),
137
144
  }
138
145
  present = [name for name, value in forbidden.items() if value]
139
146
  if present:
@@ -310,6 +317,15 @@ def _materialize_run(
310
317
  active_context = hydrate_active_run_context(
311
318
  _read_json_object(active_context_path, "active run context")
312
319
  )
320
+ if args.dispatch_kind == "initial" and manifest.get("taskType") == "improvement-discovery":
321
+ try:
322
+ plan = resolve_prompt_plan_for_manifest(
323
+ manifest=manifest, worker_id=args.worker_id, dispatch_kind="initial",
324
+ )
325
+ if plan.audience == "analysis":
326
+ prepare_resolved_lens_census(project_root, manifest)
327
+ except (ValueError, JsonBoundaryError, OSError, UnicodeError) as exc:
328
+ raise AgentPromptCliError(str(exc)) from exc
313
329
  metadata_path = prompt_path.with_name(prompt_path.name + ".meta.json")
314
330
  generation = _reuse_or_seal_verifier_generation(
315
331
  args, project_root, manifest_path, manifest, active_context, metadata_path,
@@ -366,7 +382,7 @@ def _materialize_run(
366
382
  f"audience {args.audience} has no corrections ledger"
367
383
  )
368
384
  raise AgentPromptCliError(
369
- "--corrections requires report contract 3.0 (a Markdown narrative); "
385
+ "--corrections requires report contract 3.0; "
370
386
  "this run uses an older contract"
371
387
  )
372
388
  if args.audience in _RESOURCE_AUDIENCES and not is_reverify:
@@ -593,19 +609,20 @@ def _with_report_writer_sections(
593
609
  check,
594
610
  base_narrative_rel=str(check.ledger.get("baseNarrativePath") or ""),
595
611
  corrections_rel=_relative(project_root, corrections_path),
612
+ input_format=report_authoring_format(manifest),
596
613
  ))
597
614
  body = "## Inputs\n\nCorrection-only task: use the checked field values and evidence below."
598
615
  sections.extend(_render_correction_application(args, project_root, narrative_path, corrections_path, check))
599
616
  sections.append("")
600
617
  else:
601
- _refuse_free_form_correction(project_root, narrative_path)
618
+ _refuse_free_form_correction(project_root, narrative_path, manifest)
602
619
  preserved = _preserve_reauthored_narrative(
603
620
  project_root, narrative_path, invocation_id=str(args.invocation_id),
604
621
  )
605
622
  if preserved is not None:
606
623
  sections.extend(_render_previous_attempt_section(preserved))
607
624
  sections.append("")
608
- sections.extend(render_output_section())
625
+ sections.extend(render_output_section(input_format=report_authoring_format(manifest)))
609
626
  return body.rstrip("\n") + "\n\n" + "\n".join(sections) + "\n"
610
627
 
611
628
 
@@ -673,7 +690,9 @@ def _render_previous_attempt_section(preserved_rel: str) -> list[str]:
673
690
  ]
674
691
 
675
692
 
676
- def _refuse_free_form_correction(project_root: Path, narrative_path: Path) -> None:
693
+ def _refuse_free_form_correction(
694
+ project_root: Path, narrative_path: Path, manifest: Mapping[str, Any],
695
+ ) -> None:
677
696
  """서사가 이미 있고 구조가 읽히면 이 디스패치는 교정이다 — 원장 없이는 거절한다.
678
697
 
679
698
  구조가 읽히지 않는 서사(줄 문법·소유권 결함)는 교정 대상이 아니라 재저작
@@ -684,9 +703,12 @@ def _refuse_free_form_correction(project_root: Path, narrative_path: Path) -> No
684
703
  if not narrative_path.is_file():
685
704
  return
686
705
  try:
687
- parse_narrative_structure(
688
- narrative_path.read_text(encoding="utf-8"), load_schema_version("3.0"),
689
- )
706
+ load_report_narrative(project_root, manifest, load_schema_version("3.0"),
707
+ path=narrative_path, structure_only=True)
708
+ except JsonBoundaryError as exc:
709
+ if exc.reason == OUTSIDE_WORKER_RESULT_LANES:
710
+ raise AgentPromptCliError(str(exc)) from exc
711
+ return
690
712
  except NarrativeContractError:
691
713
  return
692
714
  narrative_rel = _relative(project_root, narrative_path)
@@ -701,7 +723,7 @@ def _refuse_free_form_correction(project_root: Path, narrative_path: Path) -> No
701
723
  "--corrections here. A ledger of only replace/remove/add/move entries needs no "
702
724
  "writer round: `okstra agent-prompt apply-corrections` writes the "
703
725
  "narrative and records the activity row. Only a narrative whose "
704
- "structure does not parse (line grammar, unknown top-level field) is "
726
+ "structure does not parse (declared syntax or writer ownership) is "
705
727
  "re-authored without a ledger; value defects are what the ledger fixes"
706
728
  )
707
729
 
@@ -922,10 +944,9 @@ def _roster_result_path(
922
944
  return None
923
945
 
924
946
 
925
- def _materialize_standalone(
926
- args: argparse.Namespace,
927
- project_root: Path,
928
- ) -> PreparedAgentInvocation:
947
+ def _standalone_input_paths(
948
+ args: argparse.Namespace, project_root: Path,
949
+ ) -> tuple[Path, Path]:
929
950
  required = {
930
951
  "host-runtime": args.host_runtime,
931
952
  "provider": args.provider,
@@ -967,15 +988,38 @@ def _materialize_standalone(
967
988
  expected_prompt = root / f"{args.invocation_id}.prompt.md"
968
989
  instruction_path = _exact_path(args.instruction, expected_instruction, True, "instruction")
969
990
  prompt_path = _exact_path(args.prompt, expected_prompt, False, "prompt")
991
+ return instruction_path, prompt_path
992
+
993
+
994
+ def _materialize_standalone(
995
+ args: argparse.Namespace,
996
+ project_root: Path,
997
+ ) -> PreparedAgentInvocation:
998
+ instruction_path, prompt_path = _standalone_input_paths(args, project_root)
970
999
  assignment_context = load_assignment_context(
971
1000
  host_runtime=args.host_runtime,
972
1001
  terminal_backend=args.terminal_backend or detect_terminal_backend(),
973
1002
  execution_provider_ids=(args.provider,),
974
1003
  include_native_provider=False,
975
1004
  )
1005
+ review_values = [getattr(args, f"review_{name}", None)
1006
+ for name in ("policy", "census", "base", "head")]
1007
+ review_inputs = None
1008
+ if args.audience == "code-reviewer" or any(review_values):
1009
+ if args.audience != "code-reviewer" or not all(review_values):
1010
+ raise AgentPromptCliError(
1011
+ "code-reviewer requires --review-policy, --review-census, --review-base and --review-head"
1012
+ )
1013
+ review_inputs = CodeReviewInputs(
1014
+ _project_input(project_root, args.review_policy, "review policy"),
1015
+ _project_input(project_root, args.review_census, "review census"),
1016
+ args.review_base, args.review_head,
1017
+ tuple(getattr(args, "review_resource", ())),
1018
+ )
976
1019
  return prepare_standalone_invocation(StandaloneInvocationRequest(
977
1020
  project_root=project_root, invocation_id=args.invocation_id, audience=args.audience,
978
1021
  purpose=args.purpose, context=assignment_context, provider=args.provider,
979
1022
  model_role=args.model_role, model=args.model, instruction_path=instruction_path,
980
1023
  prompt_path=prompt_path, requested_runner=args.execution_runner,
1024
+ review_inputs=review_inputs,
981
1025
  ))
@@ -12,6 +12,7 @@ from datetime import datetime, timezone
12
12
  from pathlib import Path
13
13
 
14
14
  from ..invocation import (
15
+ AgentInvocationError,
15
16
  AgentModelAssignment,
16
17
  agent_model_assignment_from_payload,
17
18
  materialize_standalone_result,
@@ -28,7 +29,6 @@ from ...dispatch_state import (
28
29
  from .emit import _emit
29
30
  from .inputs import (
30
31
  AgentPromptCliError,
31
- _is_relative_to,
32
32
  _mapping,
33
33
  _project_input,
34
34
  _project_root,
@@ -149,27 +149,24 @@ def _verify(args: argparse.Namespace) -> None:
149
149
 
150
150
 
151
151
  def _materialize_result(args: argparse.Namespace) -> None:
152
+ from ..standalone import standalone_returned_body
153
+
152
154
  project_root = _project_root(args.project_root)
153
155
  metadata_path = _project_input(project_root, args.metadata, "metadata")
154
- root = project_root / ".okstra" / "agent-invocations" / args.purpose
155
- temporary_root = root / ".tmp"
156
156
  returned_body_path = _project_input(
157
157
  project_root,
158
158
  args.returned_body_file,
159
159
  "returned body",
160
160
  )
161
- if not temporary_root.is_dir() or not _is_relative_to(
162
- returned_body_path,
163
- temporary_root.resolve(strict=True),
164
- ):
165
- raise AgentPromptCliError(
166
- "returned body file must be inside the standalone purpose .tmp directory"
167
- )
161
+ try:
162
+ returned_body = standalone_returned_body(project_root, args.purpose, returned_body_path)
163
+ except AgentInvocationError as exc:
164
+ raise AgentPromptCliError(str(exc)) from exc
168
165
  result = materialize_standalone_result(
169
166
  project_root=project_root,
170
167
  purpose=args.purpose,
171
168
  metadata_path=metadata_path,
172
- returned_body=returned_body_path.read_bytes(),
169
+ returned_body=returned_body,
173
170
  )
174
171
  _emit({
175
172
  "ok": True,
@@ -7,6 +7,7 @@ from dataclasses import dataclass
7
7
  from pathlib import Path
8
8
 
9
9
  from ..assignment_resolver import AssignmentContext, resolve_dispatch_assignment
10
+ from ..code_review_invocation import CodeReviewInputs
10
11
  from .invocation import (
11
12
  AgentAudience,
12
13
  AgentInstruction,
@@ -20,6 +21,18 @@ from .invocation import (
20
21
  )
21
22
 
22
23
 
24
+ def standalone_returned_body(project_root: Path, purpose: str, body_path: Path) -> bytes:
25
+ """Read a raw return only from the purpose's `.tmp/` directory."""
26
+ temporary_root = project_root / ".okstra" / "agent-invocations" / purpose / ".tmp"
27
+ if not temporary_root.is_dir() or not body_path.resolve(strict=True).is_relative_to(
28
+ temporary_root.resolve(strict=True),
29
+ ):
30
+ raise AgentInvocationError(
31
+ "returned body file must be inside the standalone purpose .tmp directory"
32
+ )
33
+ return body_path.read_bytes()
34
+
35
+
23
36
  @dataclass(frozen=True)
24
37
  class StandaloneInvocationRequest:
25
38
  project_root: Path
@@ -33,6 +46,7 @@ class StandaloneInvocationRequest:
33
46
  instruction_path: Path
34
47
  prompt_path: Path
35
48
  requested_runner: str | None = None
49
+ review_inputs: CodeReviewInputs | None = None
36
50
 
37
51
 
38
52
  def prepare_standalone_invocation(
@@ -83,6 +97,7 @@ def prepare_standalone_invocation(
83
97
  duty_id=None,
84
98
  invocation_ref=None,
85
99
  attempt=1,
100
+ review_inputs=request.review_inputs,
86
101
  )
87
102
  )
88
103
 
@@ -5,6 +5,8 @@ import hashlib
5
5
  import re
6
6
  from pathlib import Path
7
7
 
8
+ from okstra_project.dirs import contained_relative_path as project_relative_ref
9
+
8
10
  from . import group_context
9
11
 
10
12
 
@@ -239,17 +241,10 @@ def reference_source_extracts(
239
241
  reference_text: str, clarification_text: str,
240
242
  ) -> str:
241
243
  """합성 입력 안에 원문이 함께 있을 때 일치하는 발췌만 참조로 바꾼다."""
242
- lines = packet_text.splitlines()
243
- headings = _heading_lines(lines)
244
- if headings and headings[0][1] == "## Section Index":
245
- start = headings[0][0] - 2
246
- end = start + _INDEX_PREAMBLE_LINES + len(headings) - 1
247
- unindexed = "\n".join(lines[:start] + lines[end:]) + "\n"
248
- # 생성기가 만든 목차임을 재구성으로 확인한다. 수정된 목차가 있으면
249
- # 원문 전체를 유지해 내용 손실이나 잘못된 줄번호를 만들지 않는다.
250
- if _with_section_index(unindexed) != packet_text:
251
- return packet_text
252
- lines = unindexed.splitlines()
244
+ unindexed = _without_generated_section_index(packet_text)
245
+ if unindexed is None:
246
+ return packet_text
247
+ lines = unindexed.splitlines()
253
248
  blocks = (
254
249
  ("Task brief", brief_text, _brief_block(brief_text)),
255
250
  ("Analysis profile", profile_text, _profile_block(task_type, profile_text)),
@@ -275,6 +270,24 @@ def reference_source_extracts(
275
270
  return "\n".join(lines).rstrip() + "\n" if changed else packet_text
276
271
 
277
272
 
273
+ def replace_analysis_packet_block(packet_text: str, expected: str, replacement: str) -> str:
274
+ unindexed = _without_generated_section_index(packet_text)
275
+ if unindexed is None or unindexed.count(expected) != 1:
276
+ raise ValueError("analysis packet has no matching pending resolved-lens census or valid section index")
277
+ return _with_section_index(unindexed.replace(expected, replacement))
278
+
279
+
280
+ def _without_generated_section_index(packet_text: str) -> str | None:
281
+ lines = packet_text.splitlines()
282
+ headings = _heading_lines(lines)
283
+ if not headings or headings[0][1] != "## Section Index":
284
+ return packet_text
285
+ start = headings[0][0] - 2
286
+ end = start + _INDEX_PREAMBLE_LINES + len(headings) - 1
287
+ unindexed = "\n".join(lines[:start] + lines[end:]) + "\n"
288
+ return unindexed if _with_section_index(unindexed) == packet_text else None
289
+
290
+
278
291
  def _with_section_index(body: str) -> str:
279
292
  """Prefix the rendered packet with every section's line range.
280
293
 
@@ -575,25 +588,6 @@ def exceeds_cited_document_limit(size: int) -> bool:
575
588
  return size > MAX_CITED_DOCUMENT_BYTES
576
589
 
577
590
 
578
- def project_relative_ref(ref: str, root: Path) -> str | None:
579
- """The posix path of a Source Material `ref` relative to the resolved `root`.
580
-
581
- None when the ref resolves outside the root, or names the home directory of
582
- a user this machine does not know (`~200` in prose). Every reader and
583
- writer of a `### Source N — file` ref goes through here so they agree on
584
- which file it names.
585
- """
586
- try:
587
- candidate = Path(ref).expanduser()
588
- except RuntimeError:
589
- return None
590
- path = (candidate if candidate.is_absolute() else root / candidate).resolve()
591
- try:
592
- return path.relative_to(root).as_posix()
593
- except ValueError:
594
- return None
595
-
596
-
597
591
  def _by_reference_file_refs(source_material: str) -> list[str]:
598
592
  refs = [ref for ref, fmt in file_source_entries(source_material) if fmt == BY_REFERENCE_FORMAT]
599
593
  return list(dict.fromkeys(refs))
@@ -164,6 +164,16 @@ def _stream_payload(path: Path) -> dict[str, Any]:
164
164
  }
165
165
 
166
166
 
167
+ def read_sealed_artifact(seal: AttemptEvidenceSeal, path: Path) -> bytes:
168
+ row = next((row for row in seal.artifacts if row.get("normalizedPath") == str(path)), None)
169
+ if row is None or path.is_symlink() or not path.is_file():
170
+ raise AttemptEvidenceError(f"artifact is absent from the attempt seal: {path}")
171
+ data = path.read_bytes()
172
+ if len(data) != row.get("byteLength") or _sha(data) != row.get("sha256"):
173
+ raise AttemptEvidenceError(f"sealed artifact bytes changed: {path}")
174
+ return data
175
+
176
+
167
177
  def _build_seal(
168
178
  attempt_ref: str, terminal: TerminalObservation
169
179
  ) -> AttemptEvidenceSeal: