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
@@ -20,6 +20,20 @@
20
20
 
21
21
  ## 1. Project identity
22
22
 
23
+ `skills/okstra-tdd/SKILL.md` adds a single-session implementation flow independent
24
+ of the cross-verification lifecycle. Its TypeScript state authority is
25
+ `src/commands/trace/trace.mts`, registered as `okstra trace` in
26
+ `src/cli-registry.mts`. It uses `src/lib/report-language.mts` and the built-in
27
+ `templates/trace/trace.template.md`, retaining attempts under `.okstra/traces/`.
28
+ `src/commands/trace/task-link.mts` connects saved traces to the Python task
29
+ projection in `scripts/okstra_ctl/trace_tasks.py`. Registration and completion
30
+ reuse `direct_work.py`; bounded read-only task discovery lives in `task_query.py`
31
+ and is exposed by `task_list_cli.py`. Task manifests retain latest trace metadata
32
+ and compact attempt history without a verification run. Regression owners are
33
+ `tests/run/test_trace_tasks.py`, `tests/run/test_task_query.py` and
34
+ `tests-js/trace.test.mjs`; run `npm run test:js`
35
+ separately from `npm run check`.
36
+
23
37
  `okstra` is a host-aware, multi-provider cross-verification runtime distributed as the npm package `okstra`. It is not a one-shot reviewer; it runs one neutral lifecycle core through Claude Code, Codex, or an explicit external adapter around a stable task key.
24
38
 
25
39
  Current baseline:
@@ -55,8 +69,6 @@ okstra/
55
69
  │ ├── okstra_vendor/ vendored Jinja2 / MarkupSafe (final-report rendering)
56
70
  │ └── lib/okstra/ Bash helpers for okstra.sh
57
71
  ├── skills/ User-invocable skills (15); `_fragments/` holds shared marker blocks
58
- ├── .agents/skills/ Codex repo-local maintainer skills
59
- ├── .claude/skills/ Claude Code project-only mirror-sync surface
60
72
  ├── .codex/hooks.json Codex project lifecycle hooks
61
73
  ├── agents/ native Claude execution-adapter definitions
62
74
  ├── prompts/ launch/profile contracts, duty catalog, wizard prompt JSON
@@ -65,8 +77,6 @@ okstra/
65
77
  ├── validators/ run / brief / schedule / view validators
66
78
  ├── tools/build.mjs source → runtime sync
67
79
  ├── tools/sync-skill-fragments.mjs expand shared fragment blocks into skills/*/SKILL.md
68
- ├── tools/korean-sources/ maintainer-only Korean mirror drift report
69
- ├── config/korean-sources.json configured English Markdown source roots
70
80
  ├── runtime/ generated install payload; do not edit directly
71
81
  ├── tests/ pytest unit suite
72
82
  ├── tests-e2e/ Bash end-to-end scenarios
@@ -179,6 +189,7 @@ The Module column below is where the command's behaviour lives — a `src/` modu
179
189
  | `task-list`, `task-show` | `scripts/okstra_ctl/task_list_cli.py`, `scripts/okstra_ctl/task_show_cli.py` | Task/run introspection for skills; `task-show` consumes the Python task read-side snapshot |
180
190
  | `resolve-task-key` | `scripts/okstra_ctl/resolve_task_key.py` | Resolve a bare task-id to candidate task-keys from the project catalog |
181
191
  | `set-work-status` | `scripts/okstra_ctl/set_work_status.py`, `scripts/okstra_ctl/direct_work.py` | Set user-managed `workStatus`, register an existing brief without a run, and share direct completion records through group memory and task queries |
192
+ | `doyouknow` | `scripts/okstra_ctl/doyouknow/cli.py`, `source_store.py`, `sources/` | Store manual records; configure, collect and list memory, manager and project-task source projections |
182
193
  | `time-report`, `log-report`, `error-report`, `error-zip` | `scripts/okstra_ctl/time_report.py`, `scripts/okstra_ctl/log_report.py`, `scripts/okstra_ctl/error_report.py`, `scripts/okstra_ctl/error_zip.py` | Read-side task runtime, wrapper log, and error aggregation helpers |
183
194
  | `run-audit` | `scripts/okstra_ctl/run_audit.py` | Anomaly detection — checks run artifacts against progress invariants and reports invariant violations, read-only (Python: `okstra_ctl.run_audit`) |
184
195
  | `worker-liveness` | `scripts/okstra_ctl/worker_liveness.py` | Report whether pending workers are still alive, so the lead's poll ends a stalled wait early instead of paying the deadline (Python: `okstra_ctl.worker_liveness`) |
@@ -204,7 +215,7 @@ The Module column below is where the command's behaviour lives — a `src/` modu
204
215
  | `wizard` | `src/commands/execute/wizard.mts` | Drive the `okstra-run` interactive state machine, including the final outcome envelope |
205
216
  | `token-usage` | `scripts/okstra-token-usage.py` | Wrap installed Python token usage CLI |
206
217
  | `spawn-followups`, `error-log` | `scripts/okstra-spawn-followups.py`, `scripts/okstra-error-log.py` | Follow-up task bundle creation and run error-log append helpers |
207
- | `memory` | `src/commands/memory/memory.mts` | Store/find global conversation memory under `~/.okstra/memory-book`; `add --source-key` returns the stored entry for a key it already holds, under a per-key lock (`src/lib/file-lock.mts`, shared with `chat`) |
218
+ | `memory` | `src/commands/memory/memory.mts`, `src/lib/memory-entry-contract.mts` | Store/find global conversation memory under `~/.okstra/memory-book`; share entry validation with Python through `schemas/memory-entry-contract-v1.json`; `add --source-key` returns the stored entry for a key it already holds, under a per-key lock (`src/lib/file-lock.mts`, shared with `chat`) |
208
219
  | `pr` | `src/commands/pr/pr.mts` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (default `templates/pr/pr-body.template.md`, shared with release-handoff), base-branch recommendation, and a fixed-text generation bundle — template, `<base>..<head>` commits, `<base>...<head>` diffstat and the `templates/pr/drafting-rules.md` drafting rules — used by the okstra-pr-gen skill and the release-handoff lead; `check` lists okstra identifiers left in a drafted body. `--json` preserves the same fields as a machine contract. Git-only; no project registration required |
209
220
  | `recap` | `scripts/okstra_ctl/recap.py` | `okstra recap <assemble\|record\|note>` Node wrapper for task and group recaps — `assemble` is a read-only phase-transition summary for a task or, with `--task-group`, the group's start order plus each task's latest conclusion; `record` appends one line to `recap/recap-log.jsonl` (task) or `.okstra/tasks/<group>/.recap/recap-log.jsonl` (`--task-group`); `note` writes an agent-authored note under `notes/` and prints the `--clarification-response` argument for a follow-up run |
210
221
  | `stage-map` | `scripts/okstra_ctl/stage_map_cli.py` | `okstra stage-map <task-key>` — exposes a task's implementation-planning Stage Map as JSON (`stages[].{stage_number,title,depends_on,step_count}` + consumer-state-based `doneStages[]`). If there is no Stage Map, `stages: []`. The read-side basis from which `okstra-schedule-gen` derives stage units and dependency closure |
@@ -264,7 +275,7 @@ Important modules:
264
275
  | `self_mock_signals.py` | self-mock signal SSOT — language-keyed regexes (`SIGNALS`), the `EXT_TO_LANG` extension map, and the waiver-matching mechanics both gates share — `selfmock_path_key` (the one path-normalization), `waiver_entry_key` (the `(file, line, <discriminator>)` triple, with the hand-typed line coerced to `int`) and `partition_waived_entries` (the split into still-failing vs waived). Gate A passes the discriminator `signal`, gate B `mutant`; one definition means the two cannot disagree about whether a waiver matches a finding. The signals are each ported from a `prompts/coding-preflight/languages/<lang>.md` "Self-mock signals to refuse" bullet with the source `doc_keyword` retained so a drift guard fails when doc and module diverge. Patterns stay deliberately narrow (only the "stub the subject's own method, then assert the stub" shape and reaching into the subject's privates; subject identity is never inferred beyond the literal `sut` token). The static detector `validators/detect_self_mock.py`, the drift guard and `mutation_probe.py` MUST import from here; four documented shapes needing subject identity no regex has are left to the mutation gate (`mutation_probe.py`) |
265
276
  | `mutation_probe.py` | gate B of the self-mock gate — the tool-agnostic mutation probe. `ADAPTERS` maps an `EXT_TO_LANG` language key to an adapter (`ts_js` → Stryker, `python` → Cosmic Ray, `rust` → cargo-mutants, `java`/`kotlin` → PIT, which reports `unsupported` because its SCM scoping is a Maven-only goal and the report↔path mapping is unverified). The Python adapter activates only when the worktree has both an installed `cosmic-ray` executable and `cosmic-ray.toml`; Okstra never installs it. It verifies that `module-path` covers every changed Python target and that no target is excluded, snapshots the configured Python source bytes and modes, restores them after every run, and filters the JSONL dump to diff-added lines. A completed session with no applicable operator on a changed line is `nothing-to-verify`; malformed configuration, command/report failures, incomplete trials, and failed source restoration are blocking `integrity-inspection` results. `run_probe` owns everything that must not differ between tools: production-source selection, the refusal to run on an empty target set, the requirement that the diff name EVERY changed source, the adapter result-shape check and the user-acknowledged waiver application; adapters only parse. `evaluate` counts a mutant only when it covers a line the diff added or modified, and records the pre-cap `survivedTotal` so a trimmed report cannot be fully waived to PASS. Anything that stops a real inspection — no adapter, tool not installed, unreadable report, unknown outcome word, no conclusive trial, a diff that misses a changed source — answers `unsupported(<reason>)`, never `PASS`. `classify_reason` is the 3-class SSOT (capability-gap / nothing-to-verify / integrity-inspection, unknown → integrity) read by BOTH the cross-language merge here and the blocking decision in `validators/validate-run.py` |
266
277
  | `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
267
- | `path_hints.py` | Compact path-hint persistence + legacy context hydration — stores `run-context` / `active-run-context` in the schemaVersion `2.0` `identity` + `pathHints` compact schema, and hydrates the legacy flat path keys (`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH`, etc.) in memory the moment the host-side reader reads them |
278
+ | `path_hints.py` | `run-context`·`active-run-context`의 schemaVersion `2.0` `identity` + `pathHints` 저장과 기존 평면 경로 키 복원을 담당한다. 작성자 형식과 사용량 정책도 보존해 재개 시 입력 경로와 정책을 설치본 기본값으로 바꾸지 않는다 |
268
279
  | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
269
280
  | `implementation_outcome.py` | Artifact-derived reconstruction of the implementation phase outcome — reads `runs/implementation/carry/stage-<N>.json` + `consumers.jsonl` + the approved Stage Map to derive `phaseOutcome.implementation`, and when every stage has pass-grade carry evidence it raises `workflow.nextRecommendedPhase.status` to `ready` (keeping the `contract-violated` audit information). It never picks the phase — `phase` is left as the last stage's report routing settled it, and the status is raised only while `phase` is non-empty |
270
281
  | `paths.py` | Path/sequence computation for task/run artifacts (including recap directory/log paths) |
@@ -302,9 +313,9 @@ Important modules:
302
313
  | `report_execution_evidence.py` | Derives each verifier's execution evidence references and final-verification command rows from the verification execution records, and compares a report's references with them for the phase validators |
303
314
  | `report_assembly.py` | Validates the role-owned report inputs and publishes the contract 3.0 record once (assembled in a temp file, then atomically promoted); a bad input aborts with owner / artifact path / field path / reason and preserves the existing `data.json` |
304
315
  | `report_projections.py` | Pure projections turning role-owned execution inputs (agent activity, execution status, convergence, design, token usage) into canonical final-report fragments |
305
- | `report_narrative.py` | Lossless read/write contract for the report-writer-owned narrative Markdown (`report-narrative-<task-type>-<seq>.md`) — the only artifact the report-writer authors under contract 3.0 |
306
- | `report_corrections.py` | The lead's corrective request to the report writer as a machine-checked ledger (`report-writer-corrections-<task-type>-<seq>-a<N>.json`, schema `schemas/report-writer-corrections-v1.0.schema.json`): applies `replace` / `remove` entries to the base narrative, validates the result against the writer-owned schema and the task's semantic validator, attaches the schema constraint to each `rewrite`, reports every defect at once, renders the prompt's `## Corrections` / `## Output` sections, and renders the corrected narrative for a mechanical (replace/remove only) ledger. Consumed by `agent/prompt_cli/corrections.py` |
307
- | `report_synthesis_packet.py` | Builds the frozen, read-only synthesis input packet handed to the report-writer — collects each source's label / owner / path / content digest into `report-writer-synthesis-packet-<task-type>-<seq>.{json,md}`, materialized at dispatch by `initial_prompt_materialization.py` so the writer synthesizes from a byte-stable snapshot. `report_assembly.py` calls `verify_report_synthesis_packet_sources` at publish time so a drifted source aborts the record; schema is `schemas/report-synthesis-packet-v1.0.schema.json` |
316
+ | `report_narrative.py` | 계약 3.0의 작성자 소유 입력을 manifest의 `reportAuthoringFormat`에 따라 읽고 쓴다. 새 `json-v1`은 표준 JSON 객체와 Markdown 설명 문자열을 사용하며, 기존 `markdown-v1` 줄 문법도 유지한다. 중첩된 기계 소유 필드까지 소유권을 검사한다 |
317
+ | `report_corrections.py` | 리더의 교정 원장(`report-writer-corrections-<task-type>-<seq>-a<N>.json`)을 작성자 소유 스키마·태스크 계약으로 검사하고 선언된 입력 형식으로 교정한다. `replace`·`remove`만 있는 원장은 기계적으로 적용하며, JSON 입력의 필드 이름과 경로는 JSON 키로 안내한다. 호출자는 `agent/prompt_cli/corrections.py`다 |
318
+ | `report_synthesis_packet.py` | 작성자에게 전달할 자료의 소유자·경로·digest와 저작 계약을 `report-writer-synthesis-packet-<task-type>-<seq>.{json,md}`로 동결한다. `initial_prompt_materialization.py`가 디스패치 시 생성하며, 선언된 작성 형식과 해당 확장자를 사용한다. 게시 시 `report_assembly.py`가 원본 digest를 대조한다. 스키마는 `schemas/report-synthesis-packet-v1.0.schema.json`이다 |
308
319
  | `approval_decisions.py` | Lead-owned approval-decision input ledger — `disposition` (`select`/`accept-risk`/`request-revision`/`reject`), reach, scope effect, and classification invariants (`correctness-critical`/`noncritical-dissent`/`user-decision`) |
309
320
  | `design_snapshot.py` | Builds the design-surface-detector-owned snapshot from the report narrative — reproducible design surfaces plus conservative `PREP-NNN` preparation items (delegates surface detection to `design_surfaces.py`) |
310
321
  | `report_markdown.py` | Schema-ordered Markdown serialisation of a data.json subtree for the full reading copy — headings, tables for uniform row sets, prose for narrative fields; field order read from the schema, not from the mapping |
@@ -338,6 +349,8 @@ Important modules:
338
349
  | `resolve_task_key.py` | shared skill helper resolving a bare task-id → `task-catalog.json` candidate entries (`okstra resolve-task-key`) |
339
350
  | `code_review_paths.py` | filesystem-layout SSOT for code-review result files — `stage_review_dir` / `branch_review_dir` plus `next_stage_review` / `next_branch_review`, which read the existing files to derive the next round's name (`stage-<NN>.md`, then `-r2`, `-r3`, …) or the next same-day sequence (`<YYYY-MM-DD>-<NN>.md`), so skill markdown never re-derives a literal review path |
340
351
  | `code_review_target.py` | `okstra code-review` argument and output boundary. Stage mode reads recorded stage targets; branch mode requires an explicit frozen base. Routes citation checks, verified coverage and conservative follow-up scope proposals. Read-only: it never creates the review directory |
352
+ | `code_review_invocation.py` | binds a standalone code review to its assigned census, selected frozen review policy and fixed comparison range, so the prompt carries applicable rules and calibration |
353
+ | `code_review_integrity.py` | records immutable source/Git integrity evidence (baseline before, audit after execution) for standalone review completions; source, protected-input or semantic Git index changes fail the run. Detects changes after execution; not an OS write sandbox |
341
354
  | `code_review_scope.py` | Proposes per-reviewer carry candidates using verified prior coverage, frozen range and rule/policy fingerprints, and recorded source dependencies. Current reviewers still attest the impact boundary and publish current verdicts |
342
355
  | `session.py`, `seeding.py`, `locks.py`, `invocation.py`, `sequence.py`, `ids.py`, `material.py` | Supporting lifecycle helpers |
343
356
  | `pane_reclaim.py` | resolves which runs of the current project still hold a non-terminal dispatch, so the `SessionStart(compact)` hook can re-inject the pane-cleanup obligation for them. The signal is the newest `team-state` per run directory, not the central run index — an in-session run never appears there (ADR-0011). Imports the status split from the `dispatch_state.NON_TERMINAL_WORKER_STATUSES` SSOT |
@@ -405,7 +418,7 @@ Important modules:
405
418
  | `task_target.py` | shared helper resolving `task-key → (task_root, project_root)` (`resolve_task_root`) |
406
419
  | `contract_refreeze.py` | re-freezes a running run's frozen contracts in the installed format. A run freezes its duty/role/common contracts at start and pins their digest, so installing a release that changed the contract format leaves that run unable to produce another prompt (`run duty snapshot catalog digest does not match`). Backs `okstra agent-prompt refreeze-contracts`, rewrites the frozen copies and the manifest digest only, and never touches a prompt, result or ledger |
407
420
  | `operation_invocation.py` | prepares an Okstra-owned LLM operation that runs outside `okstra-run` — the operation contract (`agents/operations/<id>.json`) owns the duty and the worker count, and the role is derived from that duty's `roleId`, so a skill passes the operation name instead of assembling role/provider/model itself (ADR-0017). Backs `okstra agent-prompt resolve-operation` |
408
- | `phases/catalog.py` | Fixed map from the 12 public task types to their phase package names, whether each phase has moved into `phases/<package>/`, and its HTML view builder. Resolves a task type's profile Markdown/JSON and phase-owned report templates inside one asset root (repo checkout, `runtime/python`, or `~/.okstra/lib/python`) and resolves `{{INCLUDE:...}}` targets for a phase `profile.md`. Importing it loads no phase module |
421
+ | `phases/catalog.py` | 13개 태스크의 패키지·프로필·보고서 자산과 호스트 지침 필요 여부를 한 자산 루트에서 해석한다. `implementation`·`implementation-planning`만 호스트 지침을 선언하며, 선언한 파일이 없으면 오류를 반환한다. phase 모듈을 import하지 않고 `{{INCLUDE:...}}`도 해석한다 |
409
422
  | `phases/final_verification/` | Final-verification policy and assets: `profile.md`/`profile.json` (recorded under the logical paths `prompts/profiles/final-verification.*`), `spec.md` (process note and guarantees), `entry.py` (verification-target request, snapshot writer, prepare-flag checks), `validation.py` (added-surface, verdict, and scope checks that `validate-run` calls before its routing check), `wizard.py` (whole-task pick condition), `target.py` (`acquire_final_verification_target()`: chooses single-stage, containing-stage, or integrated whole-task target behind one task-key mutex), `report.py` (HTML view builder and `verificationScope` reader), and `report_assets/` (report body templates). Its `tests/` directory is collected by pytest and left out of the runtime copy |
410
423
  | `report_template_loader.py` | Jinja loader for report templates: a logical name owned by a migrated phase opens from that phase's `report_assets/`, and every other name opens from `templates/reports` |
411
424
  | `contract_graph.py`, `contract_graph_cli.py` | runtime-contract graph loader + cross-reference/dependency-closure validator and its `okstra contract-check --root <dir> (--profile\|--operation)` CLI boundary. Loads the agent contract schemas (`common`/`role`/`duty`/`profile`/`operation`), validates known role capabilities, and reports the dependency closure with per-file `path`/`schemaVersion`/`sha256`; an invalid contract raises `ContractGraphError` |
@@ -437,7 +450,7 @@ Important modules:
437
450
  | `worker_artifacts.py` | the roster worker-id vocabulary and the artifact paths derived from it |
438
451
  | `worker_state.py` | `okstra worker-state transition` — the authoritative status transitions of one persisted team-state |
439
452
  | `usage_cells.py` | how a token, cost, or duration figure reads in a report cell; shared by the Markdown and HTML report renderers |
440
- | `report_contract.py` | single registry of the public final-report task contracts, read by prepare, rendering, approval decisions, and the report synthesis packet |
453
+ | `report_contract.py` | 공개 final-report 태스크 계약과 작성자 형식의 정본이다. 보고서 스키마는 `3.0`을 유지하며, `json-v1`·`markdown-v1`과 확장자를 해석한다. 형식 필드가 없는 기존 실행은 `markdown-v1`이고, 알 수 없는 형식이나 3.0 이전 계약의 `json-v1`은 거부한다 |
441
454
 
442
455
  > `i18n.py` (the final-report i18n dictionary loader + Jinja2 lookup) is an intentionally undocumented internal helper — it is a render helper that users and contributors do not need to know about in the canonical docs, so it is excluded from the module map.
443
456
 
@@ -476,10 +489,10 @@ Project resolver and read-only state helpers:
476
489
  Token/cost accounting:
477
490
 
478
491
  - provider adapters: `claude.py`, `codex.py`, `antigravity.py`, `grok.py`, `kimi.py`, `zai/adapter.py` (`grok.py` reads the Grok Build session docs under `~/.grok/sessions/<percent-encoded-cwd>/`, taking cumulative tokens from the last `params.update.usage.modelUsage` snapshot in `updates.jsonl`; `zai/adapter.py` wraps the Claude Code executor for GLM workers — reads `ZAI_API_KEY` from the process env or the current user's `~/.env`, runs each child against `https://api.z.ai/api/anthropic` with `--setting-sources ""`, attests the served model only from response `message.model`, and prices usage at Z.ai's public API rates for `glm-5.3` / `glm-5.3-flash`)
479
- - aggregation: `collect.py`, `blocks.py`, `jsonl_io.py`, `paths.py`
492
+ - 집계: `collect.py`, `blocks.py`, `jsonl_io.py`, `paths.py`. `policy.py`가 manifest의 `usageAccountingPolicy`와 진단을 공유한다. 새 실행의 `advisory`는 확인된 사용량 부재와 불완전 합계를 `null`·진단으로 남기며, 필드가 없는 기존 실행은 `strict`를 유지한다. 잘못된 값·귀속 모호성·예상하지 못한 수집 오류는 실패로 남는다.
480
493
  - incremental scan cache: `cursor.py` (`$OKSTRA_HOME/cache/token-usage/` byte cursor + usage event extracts; bypass with `--no-cache`)
481
494
  - pricing: `pricing.py`
482
- - report substitution: `report.py`
495
+ - 보고서 반영: `report.py`. `advisory` 실행의 게시 후 재수집은 team-state에만 저장하며, 게시된 `data.json`·HTML을 덮어쓰지 않는다.
483
496
  - CLI: `cli.py` via `scripts/okstra-token-usage.py` and `okstra token-usage`
484
497
 
485
498
  ### 4.6 `prompts/`
@@ -513,7 +526,7 @@ Token/cost accounting:
513
526
 
514
527
  ### 4.8 `schemas/`
515
528
 
516
- `schemas/final-report-v3.0.schema.json` is the current final-report data.json contract. The report-writer worker writes only the narrative Markdown. Report assembly combines it with the role-owned machine inputs and atomically publishes `final-report-<task-type>-<seq>.data.json`; independent renderers produce the full reading copy Markdown and task-specific human HTML. `schemas/final-report-v2.0.schema.json` is the historical read contract.
529
+ 현재 final-report 데이터 계약은 `schemas/final-report-v3.0.schema.json`이다. 작성자는 새 `json-v1`이나 기존 `markdown-v1`의 허용 필드만 작성하고, 조립기가 역할별 기계 소유 입력을 결합해 `final-report-<task-type>-<seq>.data.json`을 원자적으로 게시한다. 두 렌더러가 읽기용 Markdown과 태스크별 HTML을 독립적으로 생성한다. 형식 변경으로 최종 스키마 버전을 올리지 않으며, 기존 v1·v2 판독도 유지한다.
517
530
 
518
531
  The deterministic convergence inputs are `schemas/convergence-groups-v1.0.schema.json`, `schemas/convergence-round-results-v1.0.schema.json`, and `schemas/convergence-critic-results-v1.0.schema.json`. `tools/build.mjs` syncs the entire source `schemas/` directory to `runtime/schemas/`; these JSON Schema files are runtime contracts, not Markdown publication-inventory entries.
519
532
 
@@ -540,7 +553,7 @@ Optional (v1.0 backward-compatible) top-level keys:
540
553
 
541
554
  14 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mts`; the Claude plugin manifest and the installer both derive from it.
542
555
 
543
- Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflight, python bootstrap note) is kept canonical in `skills/_fragments/*.md` and expanded in place inside each `SKILL.md` between `<!-- BEGIN FRAGMENT: <name> -->` / `<!-- END FRAGMENT: <name> -->` markers by `tools/sync-skill-fragments.mjs` (`--check` fails on drift). Sources stay fully expanded, so `runtime/` and installed copies remain self-contained; the guards are `tests-js/skill-fragments.test.mjs` and the retired Python suite.
556
+ 여러 스킬이 공유하는 bash 호출·CLI 버전 확인·Python 준비 문구는 `skills/_fragments/*.md`를 정본으로 두고 `tools/sync-skill-fragments.mjs`가 각 `SKILL.md`의 fragment 마커 사이에 전개한다. `node tools/sync-skill-fragments.mjs --check`로 불일치를 확인한다. 구현·계획의 호스트 절차는 스킬 본문에 미리 전개하지 않는다. wizard가 선택한 태스크의 `orchestration.hostRulesPath`를 반환하면 첫 준비 전에 읽고, 준비 후에는 동결된 `instruction-set/host-orchestration-rules.md`를 사용한다. 설치된 스킬도 이 절차에는 설치 런타임의 지침 경로를 사용한다.
544
557
 
545
558
  | Skill | User-invocable | Role |
546
559
  |---|---:|---|
@@ -577,28 +590,6 @@ These are provider-neutral contracts rendered into every dispatch prompt, not ho
577
590
  - Tests replace operating-system resources and wall-clock waits with controlled doubles.
578
591
  - A higher-layer test keeps only the minimum positive flow needed to detect wiring failures.
579
592
 
580
- ### 4.13 `tools/korean-sources/`
581
-
582
- The maintainer-only Korean review mirrors. The tool reports which mirrors have
583
- drifted and checks a translation's structure; a maintainer session does the
584
- translating and the writing. Nothing here observes edits or runs on its own.
585
-
586
- | File | Role |
587
- |---|---|
588
- | `cli.mjs` | The three commands: `status`, `validate --source`, `mark --source` |
589
- | `baseline.mjs` | Drift report and the source/mirror hash pair recorded at the last sync |
590
- | `config.mjs` | `config/korean-sources.json` validation and source↔mirror path mapping |
591
- | `markdown.mjs` | Protected-Markdown structure comparison behind `validate` |
592
- | `path-safety.mjs` | Symlink-refusing repository reads and atomic writes |
593
-
594
- Source and mirror hold the same document in two languages, so they never hash
595
- alike and drift cannot be read from the two files alone. `mark` records the pair
596
- of hashes in `.project-docs/ko-sources/.sync-baseline.json`, which is the only
597
- state the tool keeps. Maintainers follow `tools/korean-sources/workflow.md`; the
598
- paired local skills only delegate to it and are not published user skills.
599
-
600
- ---
601
-
602
593
  ## 5. Key runtime modules
603
594
 
604
595
  ### 5.1 Prepare flow
@@ -647,9 +638,9 @@ Current report pipeline:
647
638
 
648
639
  1. Analysis workers write worker result files and the separate audit sidecars named by `Audit sidecar path`.
649
640
  2. The lead writes semantic groups; the convergence engine persists working state, per-round plans/results, an optional critic transition, and then a validated `state/convergence-<task-type>-<seq>.json` terminal state: schema v1.4 when newly finalized, or an unchanged historical final schema v1.0, v1.1, v1.2, or v1.3 returned by `reuse-final`.
650
- 3. Report-writer worker writes `worker-results/report-writer-narrative-<task-type>-<seq>.md`, including `humanSummary` and one task-type deliverable; Phase 7 later assembles the schema v3 report record.
651
- 4. For implementation-planning, `okstra plan-items extract` creates the complete `P-*` queue, `validate` proves it still matches data.json, and the analyser instances run the separate plan-body verification round.
652
- 5. Token usage substitution fills usage/cost cells in the report record. The full reading copy is rendered on demand with `okstra render-final-report` from `templates/reports/final-report-v2.template.md`.
641
+ 3. 작성자는 manifest의 `reportNarrativePath`에 허용된 값을 쓴다. 새 `json-v1`의 경로는 `worker-results/report-writer-narrative-<task-type>-<seq>.json`이며, 기존 `markdown-v1`은 `.md` 경로를 유지한다. Phase 7이 최종 schema v3 보고서를 조립한다.
642
+ 4. 구현 계획에서는 `okstra plan-items extract`가 `P-*` 큐를 추출하고 `validate`가 작성자 입력 또는 기존 `data.json`과 대조한다. 새 JSON 입력에는 `--run-manifest`를 함께 전달한다. 분석자별 계획 본문 검증 라운드는 별도로 유지한다.
643
+ 5. 게시 시 사용량·비용을 보고서에 투영하며, 새 `advisory` 실행의 미수집 값과 불완전 합계는 `null`·진단으로 남긴다. 게시 후 재수집은 team-state만 갱신한다. 읽기용 Markdown은 `okstra render-final-report`가 `templates/reports/final-report-v2.template.md`에서 필요할 때 생성한다.
653
644
  6. `scripts/okstra-render-report-views.py` independently selects one of twelve dedicated task templates and emits human-facing HTML directly from the same data.json; run validation checks the record and the human HTML. A quick Markdown input retains its legacy conditional path.
654
645
 
655
646
  For the three analysis sidetracks, the HTML view also exports an immutable-source `## ANALYSIS REVIEW` sidecar. A revision rerun carries that sidecar, reanalyzes the whole confirmed scope, and records one `analysisReviewResolution` row for every affected ID before `validate_analysis_report.py` accepts the result.
@@ -660,7 +651,7 @@ Both Markdown and HTML are derived, not authoring sources. The schema is the con
660
651
 
661
652
  - `scripts/okstra_ctl/domain/role.py` — canonical roles and duty mapping.
662
653
  - `scripts/okstra_ctl/model_pool.py` — unified catalog lookup.
663
- - `scripts/okstra_ctl/model_cli.py` — `okstra model list` and atomic `modelDefaults` writes. No inference call.
654
+ - `scripts/okstra_ctl/model_cli.py` — `okstra model list` and locked, atomic `modelDefaults` and `operationModels` writes. No inference call. `operation_invocation.py` reads `operationModels` and selects an operation's models for `resolve-operation`.
664
655
  - `scripts/okstra_ctl/doctor.py` — `model_pool_diagnostics()` for `okstra doctor --json`.
665
656
 
666
657
  ---
@@ -763,7 +754,7 @@ When changing code, keep these docs in sync:
763
754
  - New report field/section: update schema, template, report-writer worker, validator tests, this file's report model if user-visible.
764
755
  - New phase/profile behavior: update the phase directory under `scripts/okstra_ctl/phases/` and its `spec.md`, plus `docs/architecture.md`, `docs/cli.md`, and `README.md` if user-facing.
765
756
 
766
- Edit English canonical Markdown sources directly; nothing asks you to touch the Korean mirror in the same change. A maintainer session reconciles the mirrors on its own schedule with `$sync-korean-sources` or `/sync-korean-sources`, which begins by reading `node tools/korean-sources/cli.mjs status`. `.project-docs/ko-sources/**` is maintainer-local only: it is neither published nor committed.
757
+ Edit canonical Markdown sources directly. Maintainer-local notes under `.project-docs/` are neither published nor committed.
767
758
 
768
759
  ---
769
760
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "okstra",
3
- "version": "0.231.1",
3
+ "version": "0.233.0",
4
4
  "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
5
5
  "license": "MIT",
6
6
  "author": "devonshin",
@@ -1,5 +1,5 @@
1
1
  {
2
- "package": "0.231.1",
3
- "builtAt": "2026-11-04T03:59:49.260Z",
2
+ "package": "0.233.0",
3
+ "builtAt": "2026-11-15T10:23:38.395Z",
4
4
  "repoRoot": "/home/runner/work/okstra/okstra"
5
5
  }
@@ -2,27 +2,27 @@
2
2
  "schemaVersion": "1.0",
3
3
  "id": "common",
4
4
  "assignmentFidelity": [
5
- "Perform the assigned work exactly as scoped. Preserve explicit inclusions, exclusions, priorities, and acceptance conditions, and stay inside the project's established architecture, terminology, and ownership boundaries. Do not silently broaden, narrow, replace, or reinterpret the assignment; prefer the smallest change that satisfies it over a novel abstraction or unrelated cleanup."
5
+ "Follow the assigned scope, priorities and acceptance conditions. Preserve project architecture, terminology and ownership; choose the smallest conforming change without unrelated cleanup."
6
6
  ],
7
7
  "requiredInputs": [
8
- "Read every required input before acting and cover it completely. Report a missing, unreadable, stale, or contradictory input instead of inventing its contents or relying on an expected shape."
8
+ "Read required inputs completely. Report missing, unreadable, stale or contradictory inputs instead of inventing their contents."
9
9
  ],
10
10
  "evidenceFirst": [
11
- "Base conclusions on inspected inputs and observed results. Trace material claims to concrete evidence, prefer stronger evidence over repetition or vote count, and distinguish verified facts from inferences and unknowns. Prioritize the checks that can change the outcome; a settled fact does not need re-verification without a stated cause."
11
+ "Ground claims in inspected sources and observed results. Distinguish verified facts, inferences and unknowns; evidence outweighs repetition or votes. Recheck settled facts only for a stated cause."
12
12
  ],
13
13
  "authorityAndScope": [
14
- "Use only the permissions, tools, and project scope granted by the invocation. Do not perform unrelated work, assume missing authority, or take outward-facing action unless the assignment explicitly authorizes it."
14
+ "Use only granted permissions, tools and project scope. Outward-facing actions require explicit authorization."
15
15
  ],
16
16
  "collaborationAndIndependence": [
17
- "Respect the boundaries of every assigned duty. Produce independent judgment when independence is required, do not seed or coordinate another agent's conclusion, preserve evidence-backed dissent, and do not transfer your own required decision to another role."
17
+ "Respect duty ownership and required independence. Preserve evidence-backed dissent; do not seed another agent's verdict or transfer your required decision to another role."
18
18
  ],
19
19
  "instructionPrecedence": [
20
- "When this contract and the task instructions both govern one action, the task instructions win: they are written for this invocation and name the concrete procedure, exemption, gate, or artifact this contract states only in general terms. What no task instruction may grant is the authority, independence, and honesty boundaries above — an instruction that widens one of those is a conflict to report, not an override to apply."
20
+ "Task instructions specialize this contract's procedures. They cannot expand authority or override independence and honesty; report such conflicts."
21
21
  ],
22
22
  "conflictHandling": [
23
- "When instructions conflict, preserve safety, evidence, and the boundaries this contract reserves. Identify the exact conflict, continue any separable safe work, and return the smallest unresolved decision to the responsible lead."
23
+ "Preserve the reserved boundaries, continue separable safe work and return the exact unresolved conflict to the responsible lead."
24
24
  ],
25
25
  "completionHonesty": [
26
- "Do not report unperformed work as complete, and do not stop at a plausible partial result: carry the assignment through every required check and deliverable, recovering from safe local failures where possible. Name remaining work, failed or skipped checks, unresolved uncertainty, and blockers precisely, including their effect on the requested outcome."
26
+ "Finish the assigned checks and deliverables, recovering from safe local failures. Report remaining work, failed or skipped checks and uncertainty; never present unperformed or partial work as complete."
27
27
  ]
28
28
  }
@@ -0,0 +1,6 @@
1
+ {
2
+ "schemaVersion": "1.0",
3
+ "id": "trace-interface-review",
4
+ "dutyId": "interface-reviewer",
5
+ "count": 3
6
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "schemaVersion": "1.0",
3
+ "id": "trace-scope-review",
4
+ "dutyId": "scope-critic",
5
+ "count": 3
6
+ }
@@ -2,17 +2,15 @@
2
2
  "schemaVersion": "1.0",
3
3
  "id": "verifier",
4
4
  "legacyAliases": [],
5
- "identity": "Rechecks evidence against requirements independently of whoever produced it.",
5
+ "identity": "Independently judges assigned artifacts against their acceptance criteria.",
6
6
  "responsibilities": [
7
- "Apply the assigned verdict criteria to the artifact itself, reading the evidence rather than the claim about it.",
8
- "Report a failure with the specific condition that failed and what would satisfy it."
7
+ "Own the verdict and identify each unmet criterion and the evidence or correction that would satisfy it."
9
8
  ],
10
9
  "requiredCapabilities": [
11
10
  "source-readonly",
12
11
  "worker-artifact-io"
13
12
  ],
14
13
  "prohibitions": [
15
- "Do not accept a claim on the strength of who made it, how many agreed, or how much effort it represents.",
16
14
  "Do not repair the artifact you are verifying."
17
15
  ]
18
16
  }
@@ -41,6 +41,7 @@ from okstra_ctl.dispatch_core import verify_served_model, verify_served_model_re
41
41
  from okstra_ctl.dispatch_state import DispatchError # noqa: E402
42
42
  from okstra_ctl.execution_manifest import read_execution_manifest_view # noqa: E402
43
43
  from okstra_ctl.write_policy import ( # noqa: E402
44
+ build_standalone_review_write_contract,
44
45
  WriteEnforcement,
45
46
  WritePolicy,
46
47
  write_enforcement_from_payload,
@@ -366,10 +367,15 @@ def _standalone_context(
366
367
  return str(exc)
367
368
  return ""
368
369
 
369
- return _V2InvocationContext(
370
- {"standaloneInvocationId": metadata["invocationId"], "role": actual_role},
371
- verify_attestation, None, None, "",
372
- )
370
+ status = {"standaloneInvocationId": metadata["invocationId"], "role": actual_role}
371
+ policy, enforcement = None, None
372
+ if metadata["audience"] == "code-reviewer":
373
+ policy, enforcement = build_standalone_review_write_contract(
374
+ project_root, prompt_path, metadata_path, metadata,
375
+ )
376
+ status.update(standalonePurpose="code-review", writePolicyDigest=policy.digest,
377
+ writeEnforcement=enforcement.to_payload())
378
+ return _V2InvocationContext(status, verify_attestation, policy, enforcement, "")
373
379
 
374
380
 
375
381
  def _execution_authority(
@@ -11,13 +11,15 @@ If unsure, ask the user once: *"Does this project use ports-and-adapters? What f
11
11
 
12
12
  These rules are language-agnostic. The examples use TypeScript/Java-ish syntax; translate to Rust traits, Kotlin interfaces, etc., as needed.
13
13
 
14
+ Apply the policy precedence in `../overview.md`: explicit repository instructions and declared architecture, this common resource pack, then surrounding code conventions. Once this overlay is selected, apply each rule's stated criteria and severity whether selection came from a declaration or layout signals. H5 alone keeps its undeclared-style advisory exception. Existing concrete dependencies or misplaced rules do not create an exception to an applicable architecture rule.
15
+
14
16
  ---
15
17
 
16
18
  ## Rule H1 — Ports stay thin
17
19
 
18
- A port is the interface (or abstract class) at the domain/application boundary. The port declares **shape**, not behavior.
20
+ A port is the interface (or abstract class) at the domain/application boundary. It declares an operation's inputs, outputs, errors and domain-owned query specifications without implementing business decisions. Describing those behavioral contracts is part of the port's interface.
19
21
 
20
- A port file's method body — or the interface contract itself — must **not** contain:
22
+ A port file's executable method body does not implement:
21
23
 
22
24
  - `if` statements that branch on domain state.
23
25
  - Validation that throws or returns errors based on input shape.
@@ -53,36 +55,29 @@ Not a violation:
53
55
 
54
56
  ---
55
57
 
56
- ## Rule H2 — Adapters do I/O, not business logic
57
-
58
- Same principle as H1, on the adapter side. The adapter's job is to implement **just** the I/O — a SQL query, an HTTP call, a filesystem read. It is **not** the place to filter by domain state, branch on domain values, or compute business answers.
58
+ ## Rule H2 — Adapters execute I/O; the domain owns business policy
59
59
 
60
- Smells in adapter methods:
60
+ An adapter translates a port operation into a SQL query, HTTP call, filesystem operation or other I/O. The domain owns the policy that determines eligibility, validity or a business outcome; the adapter may execute that policy's query specification efficiently without redefining its meaning.
61
61
 
62
- - A `.filter(x => x.status === 'active')` predicate over domain state, *after fetching rows*.
63
- - An `if` that rejects results based on a domain rule (*"skip if expired"*, *"exclude shared items"*).
64
- - A method whose name encodes a business rule — `findValid*` / `findActive* `/ `findEligible*`. The adapter should fetch *things*; the caller (or the query itself) should apply the rule.
65
- - Multiple joins and conditions assembled specifically to satisfy a compound domain rule — the adapter is answering a business question rather than offering a primitive fetch.
62
+ Inspect policy ownership and preservation of the port contract:
66
63
 
67
- Judgment: an adapter **can** push filtering into SQL (`WHERE status = 'active'`) — that's still I/O-shaped. The smell is when:
64
+ - A predicate or business calculation invented inside an adapter, with no domain-owned policy or defined port contract, hides the decision in infrastructure.
65
+ - An adapter that changes, omits or duplicates the policy's conditions can return a different business answer. Cite the governing policy and the differing condition.
66
+ - Post-fetch filtering merits inspection of its owner and cost. Technical row mapping or execution of a domain-owned specification is not inherently a policy violation.
68
67
 
69
- - The filtering is *application code after the fetch*, or
70
- - The method name itself encodes a domain rule that a reader cannot tell from the name alone.
68
+ SQL predicates, joins, aggregation, ordering and pagination may implement a domain-owned query specification at the storage boundary. Complexity or the number of conditions alone does not establish a misplaced rule. Check where the policy is defined and whether the query preserves its semantics.
71
69
 
72
- A domain-flavored method name (`findValid*` / `findActive*` / `findEligible*`) is not automatically a violation. Accept it when **either** holds:
70
+ A name such as `findValid*`, `findActive*` or `findEligible*` is valid when the port contract defines that term and identifies its governing policy or specification. An undefined or misleading term is a contract or naming problem, not proof that every business-oriented query belongs outside the adapter.
73
71
 
74
- - The query body is still simple — a single `WHERE` clause on an obvious column, no compound predicate.
75
- - Moving the predicate out would force an N+1 (the caller would have to fetch all rows and round-trip per row to decide which are valid).
72
+ Keep efficient execution near the data. Do not replace a policy-driven query with `findAll` plus in-memory filtering merely to move the predicate's syntax. Express the policy at the domain/application boundary and let the adapter translate it while preserving bounded work and avoiding N+1 calls.
76
73
 
77
- Reject it when the query is complex enough that a reader can't tell what "valid"/"active"/"eligible" means without reverse-engineering the SQL. At that point the rule really is hiding in infrastructure — move the predicate to the domain and rename the adapter to `findAll` / `findByX`.
78
-
79
- Not a smell:
74
+ Examples of adapter responsibilities:
80
75
 
81
76
  - Simple `WHERE` clauses for *data-shape* reasons (`WHERE user_id = ?`) — that's scoping the fetch, not a business rule.
82
77
  - Pagination, ordering, basic projection.
83
78
  - Mapping raw rows to domain objects — that's the adapter's translation job.
84
79
 
85
- Why it matters: when adapters hold business rules, the rules become invisible from the domain. A reviewer reading the domain sees a clean method; the rule is hidden two layers down in a repository. Changes to the rule require editing infrastructure code. Tests of the rule are forced through I/O. The whole point of ports-and-adapters collapses.
80
+ The review distinguishes changing business policy from translating it for a storage or transport system. A finding names the policy hidden or changed by the adapter and the concrete consequence; a complex query or a domain-oriented name alone is not evidence.
86
81
 
87
82
  ---
88
83
 
@@ -109,7 +104,7 @@ The test: **is this type/class a thing the business talks about, or is it plumbi
109
104
 
110
105
  ## Rule H4 — Dependency direction: the domain imports nothing outward
111
106
 
112
- The cardinal rule of ports and adapters: dependencies point inward. A file under the domain folder imports only from the domain itself and from pure utility code. Unlike H1–H3 this verdict is **mechanical** — read the import list of every changed domain file; no judgment about what the code means is required.
107
+ Dependencies point inward. A file under the domain folder imports only from the domain itself and from pure utility code. Read each changed domain file's imports and resolve their targets against the declared boundaries; apply the explicit repository instructions before judging an outward dependency.
113
108
 
114
109
  Violations — any import of:
115
110
 
@@ -131,9 +126,9 @@ When the domain needs something the outside owns, invert it: declare the shape a
131
126
 
132
127
  When a change adds or modifies a service's dependency on a concrete adapter — constructor injection of a repository class, or direct model / DB access from a service — that boundary should be a port the adapter implements, so the caller depends on shape rather than on infrastructure.
133
128
 
134
- The verdict is mechanical: this change adds or modifies such a dependency → finding; the injection sits entirely on lines this change did not touch → clean.
129
+ Inspect dependencies this change adds or modifies against the declared boundary and explicit repository instructions. An injection entirely outside the changed scope is not a new finding merely because it already uses a concrete class.
135
130
 
136
- **An existing convention does not clear this one.** A codebase that injects concrete `*Repository` classes everywhere is precisely the debt this rule pays down, one touched injection at a time — matching the surrounding style is the condition being flagged, not a defence against it. Record it, say so in the note (*"matches existing convention — advisory"*), and propose the port: its name and the two or three method signatures it would declare — unless the project declares `architecture.style = hexagonal` in `.okstra/project.json`, where this item is blocking and that same port sketch is what you write rather than what you record: fix the injection before the write, never record-and-pass.
131
+ Existing concrete `*Repository` injections do not waive a declared hexagonal boundary. Apply the precedence in `../overview.md` and cite any explicit repository exception. Under a declared hexagonal style, fix a current violating dependency through a port before completion. Without that declaration, record the advisory and a proposed port with the method signatures it needs; do not require unrelated legacy cleanup.
137
132
 
138
133
  ---
139
134
 
@@ -145,7 +140,7 @@ Violations:
145
140
 
146
141
  - An `if` / `else` chain over domain fields that decides an outcome — eligibility, validity, which branch of a business process runs.
147
142
  - Arithmetic expressing a business formula: money, ranking, quota, date-based entitlement.
148
- - A private service method whose name is a domain concept (`isEligible…`, `computeDowngrade…`, `resolve…Status`). The name is telling you where it belongs.
143
+ - A private service method that implements a business decision such as eligibility, a downgrade formula or status transition. Inspect its body and governing rule; a domain-oriented name alone is not a violation.
149
144
 
150
145
  Not a violation:
151
146
 
@@ -155,21 +150,19 @@ Not a violation:
155
150
 
156
151
  The test: **if this decision changed, would the change be described as a business rule change or as a plumbing change?** A business rule change that lands in a service is the violation — the rule is now invisible to the domain's own tests, and the next caller that needs it writes its own copy.
157
152
 
158
- Severity: `should-fix`, and blocking when the embedded rule is substantial — money, permissions, or a state machine. Under a declared `architecture.style = hexagonal` the substantial case is fixed before the write, never record-and-pass.
153
+ Grade an established H6 violation by `clean-code.md` "Finding evidence and grading". A substantial embedded rule, such as money, permissions or a state machine, is a current blocking finding even when layout signals selected this overlay. Current blocking findings are fixed before completion, subject to the explicit repository instructions.
159
154
 
160
155
  ---
161
156
 
162
- **How far a project convention reaches.** H5 above is the one rule in this overlay a project-local convention cannot clear. Elsewhere here, a documented convention does resolve the conflict in the project's favour — but that latitude stops at okstra's own gates. It never clears a check the implementation verifier's blocking list declares **mechanical**: a changed file under the domain folder importing an ORM / DB layer, a framework or its DI decorators, or anything under adapters / infrastructure / services is decided by reading the import list, and no convention argument reaches that verdict (`prompts/profiles/_implementation-verifier.md` §"Static design & test-quality review" → Hexagonal). Resolving a declared-mechanical finding as "project convention" is the failure this paragraph exists to prevent — a real run did exactly that, returned `clean`, and the team's own PR review then flagged the same import.
163
-
164
- Severity: advisory in a project that has not declared `architecture.style = hexagonal` — a direction-of-travel rule there, not a correctness gate, so it never blocks on its own. Under that declaration it is blocking: the injection is fixed before the write.
157
+ **Conflict resolution.** The precedence in `../overview.md` applies to every rule in this overlay, including H4 and H5. A surrounding code pattern alone cannot clear an explicit architecture violation. Cite an explicit repository instruction when it overrides a common-pack rule; record an unresolved conflict instead of treating it as a clean result. Boundary interpretation and grading are self-check and review judgments, not a guarantee from import scanning alone.
165
158
 
166
159
  ---
167
160
 
168
161
  ## Quick checklist before declaring a port/adapter change complete
169
162
 
170
163
  - [ ] No `if` / `.filter` / validation / business math inside any port body.
171
- - [ ] Adapter methods are I/O only — any post-fetch JS filtering moved into the query or back to the caller.
172
- - [ ] Adapter method names are neutral (`findAll`, `findByUserId`) unless the domain-flavored name passes the H2 judgment test.
164
+ - [ ] The domain owns business policy; adapter queries and any post-fetch processing preserve that policy and the port contract without redefining it.
165
+ - [ ] Domain-oriented adapter names identify a policy defined by the port contract; query complexity or the name alone is not a violation.
173
166
  - [ ] Every entity, value object, domain enum, and domain error is declared under `domain/`.
174
167
  - [ ] Port files only declare shape and `import` domain types — they don't *define* them.
175
168
  - [ ] No changed domain file imports an ORM, a framework, or anything under adapters / infrastructure / services.
@@ -0,0 +1,17 @@
1
+ # Authoring checks
2
+
3
+ These execution procedures apply only to the worker authorized to change project source. Read-only reviewers evaluate the shared criteria and report findings; this resource grants no write authority. Enforcement is author self-check and code review unless a referenced rule names an automated gate.
4
+
5
+ ## Mandatory pre-write checks (every language)
6
+
7
+ - [ ] Read project instructions, configured conventions and every selected resource for this turn. Apply the shared [quality outcomes](clean-code.md#five-simultaneous-quality-outcomes) before editing.
8
+ - [ ] Before adding a unit, search identifiers, behavior, callers, domain literals, error strings and returned-data shapes; read the candidates. Record search terms, nearest implementation and `extend <path:line>` or `new (nothing covers <behavior>)`. Name-only uniqueness does not establish absence; missing survey evidence leaves the addition unfinished.
9
+ - [ ] **Tests planned:** identify retained or extended tests for changed core behavior and meaningful failure outcomes under [Testing discipline](clean-code.md#testing-discipline) and [test reuse](clean-code.md#reuse-tests-before-adding-coverage). Select mutation checks only where needed under those criteria or an explicit project requirement. Record uncovered outcomes, any permitted waiver and its unverified scope there.
10
+ - [ ] Apply the detailed checks in `clean-code.md`, including mutation/state, security, testing, third-party wrappers and failure paths where applicable.
11
+ - [ ] If the hexagonal overlay is selected, apply its H1–H6 criteria and stated exceptions under the policy precedence in `overview.md`.
12
+
13
+ ## Completion sweep (before declaring a multi-file change done)
14
+
15
+ - [ ] Review the combined change for shared decisions and exported-name distinctions using `clean-code.md`'s DRY and naming checks, not only per-file checks.
16
+ - [ ] Manually inspect changed tests using the selected language's self-mock signals and `clean-code.md`'s testing criteria. Distinguish the tested unit from injected collaborators. In implementation runs, `validators/detect_self_mock.py` execution and its result files belong to the verifier designated by "Self-mock detection"; authors perform this manual sweep only. `validate-run.py` checks the result.
17
+ - [ ] Run the authorized repository commands selected under [Verification commands](overview.md#verification-commands). Report results, unresolved findings, waivers and unavailable checks without claiming unverified coverage.