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
@@ -25,6 +25,8 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
25
25
  if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
26
26
  sys.path.insert(0, str(_ssot_dir))
27
27
 
28
+ from okstra_token_usage.policy import usage_accounting_policy, usage_diagnostics
29
+
28
30
  try:
29
31
  from okstra_ctl.final_report_schema import (
30
32
  SchemaError,
@@ -180,7 +182,6 @@ from okstra_ctl.phases.implementation_planning.plan_body import (
180
182
  from okstra_ctl.phases.error_analysis.validation import _validate_error_analysis_consistency
181
183
  from okstra_project import project_json_path # noqa: E402
182
184
  from okstra_project.dirs import tasks_root as _okstra_tasks_root # noqa: E402
183
- from okstra_project.resolver import resolve_architecture # noqa: E402
184
185
 
185
186
  from okstra_ctl.conformance import (
186
187
  conformance_entry_mismatches,
@@ -3094,7 +3095,24 @@ def validate_worker_results_audit(
3094
3095
  (advisories if advisories is not None else failures).extend(ledger)
3095
3096
 
3096
3097
 
3097
- def validate_team_state_usage(team_state: dict, failures: list[str]) -> None:
3098
+ def validate_team_state_usage(
3099
+ team_state: dict, failures: list[str], *,
3100
+ run_manifest: Mapping[str, Any] | None = None, advisories: list[str] | None = None,
3101
+ ) -> None:
3102
+ try:
3103
+ policy = usage_accounting_policy(run_manifest if run_manifest is not None else team_state)
3104
+ except ValueError as exc:
3105
+ failures.append(str(exc))
3106
+ return
3107
+ if policy == "advisory":
3108
+ errors, missing = usage_diagnostics(team_state)
3109
+ failures.extend(errors)
3110
+ if advisories is not None:
3111
+ advisories.extend(
3112
+ f"Token usage unavailable for {row['item']}: {row['risk']}"
3113
+ for row in missing
3114
+ )
3115
+ return
3098
3116
  if _session_accounting(team_state) == "artifact-only":
3099
3117
  return
3100
3118
  summary = team_state.get("usageSummary") or {}
@@ -3308,6 +3326,12 @@ def validate_final_report_data(
3308
3326
  validate_command_log_execution_evidence(
3309
3327
  data, project_root, run_manifest_path, manifest, failures,
3310
3328
  )
3329
+ try:
3330
+ from okstra_ctl.phases.final_verification.validation import validate_implementation_review_evidence
3331
+
3332
+ validate_implementation_review_evidence(project_root, run_manifest_path)
3333
+ except (OSError, ValueError) as exc:
3334
+ failures.append(f"design-review BLOCKING: {exc}")
3311
3335
  elif task_type == "implementation-planning":
3312
3336
  active_report_contracts = report_contracts or set()
3313
3337
  planning = data.get("implementationPlanning") or {}
@@ -3354,9 +3378,16 @@ def validate_final_report_data(
3354
3378
  _validate_approval_clarification_backtrace(data, failures)
3355
3379
  _validate_rerun_guidance(data, failures)
3356
3380
  _validate_approval_guidance(data, failures)
3381
+ try:
3382
+ from okstra_ctl.review_policy import read_review_architecture
3383
+
3384
+ architecture_style = read_review_architecture(_project_root_from_report(report_path), manifest)
3385
+ except (OSError, ValueError) as exc:
3386
+ failures.append(f"review-policy BLOCKING: {exc}")
3387
+ architecture_style = "undeclared"
3357
3388
  _validate_variation_point_analysis(
3358
3389
  (data.get("implementationPlanning") or {}).get("variationPointAnalysis"),
3359
- resolve_architecture(_project_root_from_report(report_path)),
3390
+ architecture_style,
3360
3391
  failures,
3361
3392
  )
3362
3393
  if not selected_direction_contract:
@@ -5521,12 +5552,17 @@ def _import_token_usage():
5521
5552
  return collect, populate_token_cells
5522
5553
 
5523
5554
 
5524
- def _needs_token_autofix(team_state: dict, report_path: Path) -> bool:
5525
- if _session_accounting(team_state) == "artifact-only":
5555
+ def _needs_token_autofix(
5556
+ team_state: dict, report_path: Path, run_manifest: Mapping[str, Any] | None = None,
5557
+ ) -> bool:
5558
+ policy = usage_accounting_policy(run_manifest if run_manifest is not None else team_state)
5559
+ if policy == "strict" and _session_accounting(team_state) == "artifact-only":
5526
5560
  return False
5527
5561
  summary = team_state.get("usageSummary") or {}
5528
5562
  if not summary or not summary.get("collectedAt"):
5529
5563
  return True
5564
+ if policy == "advisory":
5565
+ return False
5530
5566
  if report_path.is_file():
5531
5567
  content = report_path.read_text()
5532
5568
  if any(p in content for p in TOKEN_PLACEHOLDERS):
@@ -5551,7 +5587,7 @@ def _needs_token_autofix(team_state: dict, report_path: Path) -> bool:
5551
5587
 
5552
5588
 
5553
5589
  def _accuracy_failures(updated: dict) -> list[str]:
5554
- """Return human-readable reasons the collected usage is incomplete.
5590
+ """Return strict-policy failures for incomplete collected usage.
5555
5591
 
5556
5592
  Goal: never let zero-valued usage be silently written or substituted into
5557
5593
  the final report. If a session jsonl is missing, the operator must know
@@ -5590,6 +5626,7 @@ def attempt_token_usage_autofix(
5590
5626
  team_state_path: Path,
5591
5627
  report_path: Path,
5592
5628
  project_root: Path,
5629
+ *, run_manifest: Mapping[str, Any] | None = None,
5593
5630
  ) -> tuple[str, list[str]]:
5594
5631
  """Run the Phase 7 token-usage collector in-process when artifacts indicate
5595
5632
  Phase 7 was skipped.
@@ -5597,43 +5634,51 @@ def attempt_token_usage_autofix(
5597
5634
  Returns ``(state, messages)`` where ``state`` is one of:
5598
5635
 
5599
5636
  - ``"skipped"`` — opt-out or autofix not needed; messages is empty.
5600
- - ``"recovered"`` — collector ran AND every session that should have a
5601
- jsonl was found; team-state is rewritten and the final report's token
5602
- placeholders are substituted with real values. messages carries a
5603
- single info line.
5604
- - ``"accuracy-failed"`` — collector ran but at least one expected
5605
- session is missing. Nothing is written to disk; messages contains the
5606
- contract violations the validator must surface so the operator can
5607
- re-collect accurately rather than ship a report containing zeros.
5608
- - ``"import-failed"`` / ``"collector-error"`` — autofix could not run;
5609
- caller falls back to the original contract failures.
5637
+ - ``"recovered"`` — collector ran and team-state was rewritten. Strict
5638
+ runs also substitute the report; advisory runs preserve published data
5639
+ and views. Messages describe recovery; final validation reports absence.
5640
+ - ``"accuracy-failed"`` — malformed accounting, or missing sessions under
5641
+ strict policy, prevented persistence. messages contains the violations.
5642
+ - ``"import-failed"`` / ``"collector-error"`` — autofix could not run.
5643
+ Advisory runs keep these blocking; strict runs retain the original
5644
+ contract checks after reporting the skipped recovery.
5610
5645
  """
5611
5646
  if os.environ.get("OKSTRA_VALIDATE_NO_AUTOFIX") == "1":
5612
5647
  return "skipped", []
5613
- if not _needs_token_autofix(team_state, report_path):
5648
+ try:
5649
+ policy = usage_accounting_policy(run_manifest if run_manifest is not None else team_state)
5650
+ except ValueError as exc:
5651
+ return "accuracy-failed", [str(exc)]
5652
+ if not _needs_token_autofix(team_state, report_path, run_manifest):
5614
5653
  return "skipped", []
5615
5654
  try:
5616
5655
  collect, populate_token_cells = _import_token_usage()
5617
5656
  except Exception as exc: # noqa: BLE001
5618
5657
  return "import-failed", [f"okstra_token_usage import failed: {exc}"]
5619
5658
  try:
5620
- updated = collect(team_state_path, project_root)
5659
+ updated = collect(team_state_path, project_root, manifest=run_manifest)
5621
5660
  except Exception as exc: # noqa: BLE001
5622
5661
  return "collector-error", [f"token-usage collector raised: {exc}"]
5623
5662
 
5624
- accuracy_problems = _accuracy_failures(updated)
5663
+ accuracy_problems = (
5664
+ usage_diagnostics(updated)[0]
5665
+ if policy == "advisory"
5666
+ else _accuracy_failures(updated)
5667
+ )
5625
5668
  if accuracy_problems:
5626
- # Refuse to persist zeroed usage. Surface specific reasons so the
5627
- # operator can locate the missing session(s) instead of silently
5628
- # shipping a report with `0` token counts.
5669
+ # Invalid accounting is never persisted. Strict runs also refuse
5670
+ # incomplete session measurements; advisory absence is checked later.
5629
5671
  return "accuracy-failed", [
5630
- f"Phase 7 token-usage auto-recovery refused to write incomplete data: {reason}"
5672
+ f"Phase 7 token-usage auto-recovery refused invalid or incomplete accounting: {reason}"
5631
5673
  for reason in accuracy_problems
5632
5674
  ]
5633
5675
 
5634
5676
  team_state_path.write_text(
5635
5677
  json.dumps(updated, indent=2, ensure_ascii=False) + "\n"
5636
5678
  )
5679
+ if policy == "advisory":
5680
+ message = "usageSummary recollected in team-state; published report data and HTML were preserved."
5681
+ return "recovered", [message]
5637
5682
  data_path = _data_path_for(report_path)
5638
5683
  try:
5639
5684
  replaced = populate_token_cells(data_path, updated)
@@ -5777,16 +5822,14 @@ def run_plan_body_section(
5777
5822
  return 0 if not failures else 2
5778
5823
 
5779
5824
 
5780
- def run_plan_body_inputs(narrative_path: Path, state_path: Path) -> int:
5825
+ def run_plan_body_inputs(
5826
+ narrative_path: Path, state_path: Path, *, run_manifest_path: Path | None = None,
5827
+ ) -> int:
5781
5828
  """게시 전 서사와 수렴 소유 상태에서 같은 계획 게이트를 채점한다."""
5782
- from okstra_ctl.report_narrative import parse_narrative
5783
- from okstra_ctl.final_report_schema import load_schema_version
5829
+ from okstra_ctl.report_narrative import load_writer_input
5784
5830
 
5785
5831
  try:
5786
- narrative = parse_narrative(
5787
- narrative_path.read_text(encoding="utf-8"),
5788
- load_schema_version("3.0"),
5789
- )
5832
+ narrative = load_writer_input(narrative_path, run_manifest=run_manifest_path)
5790
5833
  state = json.loads(state_path.read_text(encoding="utf-8"))
5791
5834
  except (OSError, UnicodeError, ValueError) as exc:
5792
5835
  print(f"validate-run: plan-body inputs are invalid ({exc})", file=sys.stderr)
@@ -5971,7 +6014,8 @@ def main() -> int:
5971
6014
  if args.section == SECTION_PLAN_BODY:
5972
6015
  if args.narrative and args.state and not args.report:
5973
6016
  return run_plan_body_inputs(
5974
- Path(args.narrative).resolve(), Path(args.state).resolve()
6017
+ Path(args.narrative).absolute(), Path(args.state).resolve(),
6018
+ run_manifest_path=Path(args.run_manifest).absolute() if args.run_manifest else None,
5975
6019
  )
5976
6020
  if args.report and not args.narrative and not args.state:
5977
6021
  return run_plan_body_section(
@@ -6015,16 +6059,26 @@ def main() -> int:
6015
6059
  report_path = resolve_input(args.report)
6016
6060
  team_state = load_json(team_state_path)
6017
6061
 
6018
- autofix_state, autofix_messages = attempt_token_usage_autofix(
6019
- team_state, team_state_path, report_path, project_root
6020
- )
6062
+ usage_failures: list[str] = []
6063
+ try:
6064
+ usage_policy = usage_accounting_policy(run_manifest)
6065
+ except ValueError as exc:
6066
+ usage_policy = None
6067
+ usage_failures.append(str(exc))
6068
+ autofix_state, autofix_messages = "skipped", []
6069
+ else:
6070
+ autofix_state, autofix_messages = attempt_token_usage_autofix(
6071
+ team_state, team_state_path, report_path, project_root,
6072
+ run_manifest=run_manifest,
6073
+ )
6021
6074
  if autofix_state == "recovered":
6022
6075
  team_state = load_json(team_state_path)
6023
6076
  for msg in autofix_messages:
6024
6077
  print(f"validate-run: Phase 7 auto-recovery — {msg}", file=sys.stderr)
6025
6078
  elif autofix_state in ("import-failed", "collector-error"):
6079
+ outcome = "failed" if usage_policy == "advisory" else "skipped"
6026
6080
  for msg in autofix_messages:
6027
- print(f"validate-run: Phase 7 auto-recovery skipped — {msg}", file=sys.stderr)
6081
+ print(f"validate-run: Phase 7 auto-recovery {outcome} — {msg}", file=sys.stderr)
6028
6082
 
6029
6083
  failures: list[str] = []
6030
6084
  # Findings that are reported but do not fail the run.
@@ -6038,9 +6092,17 @@ def main() -> int:
6038
6092
  # wrong. Those findings are surfaced and carried in the run manifest
6039
6093
  # instead — currently the worker citation ledger and the PROGRESS narration
6040
6094
  # lines.
6041
- advisories: list[str] = []
6095
+ advisories: list[str] = (
6096
+ list(autofix_messages)
6097
+ if autofix_state == "recovered" and usage_policy == "advisory"
6098
+ else []
6099
+ )
6042
6100
  versioned_session_failures: list[str] = []
6043
- if autofix_state == "accuracy-failed":
6101
+ if usage_policy == "advisory" and autofix_state in {
6102
+ "accuracy-failed", "collector-error", "import-failed",
6103
+ }:
6104
+ usage_failures.extend(autofix_messages)
6105
+ elif autofix_state == "accuracy-failed":
6044
6106
  failures.extend(autofix_messages)
6045
6107
  _validate_execution_identity_v2(run_manifest, failures)
6046
6108
  contract = extract_contract(run_manifest, task_manifest, failures)
@@ -6097,7 +6159,11 @@ def main() -> int:
6097
6159
  report_data=validation_data,
6098
6160
  team_state=team_state,
6099
6161
  )
6100
- validate_team_state_usage(team_state, failures)
6162
+ if usage_policy is not None:
6163
+ validate_team_state_usage(
6164
+ team_state, usage_failures if usage_policy == "advisory" else failures,
6165
+ run_manifest=run_manifest, advisories=advisories,
6166
+ )
6101
6167
 
6102
6168
  if task_type:
6103
6169
  validate_worker_results_audit(report_path, task_type, failures, advisories)
@@ -6246,6 +6312,9 @@ def main() -> int:
6246
6312
  # 근거와 정책: scripts/okstra_ctl/blocking_checks.py
6247
6313
  failures, demoted = partition_blocking(failures)
6248
6314
  advisories.extend(demoted)
6315
+ # Accounting contract errors have explicit policy ownership. They do not
6316
+ # pass through the legacy message-based classification for report checks.
6317
+ failures.extend(dict.fromkeys(usage_failures))
6249
6318
 
6250
6319
  validation_status = "passed" if not failures else "failed"
6251
6320
  update_validation_metadata(