okstra 0.232.0 → 0.233.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (183) hide show
  1. package/README.md +19 -283
  2. package/dist/cli-registry.mjs +8 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/trace/capacity.d.mts +12 -0
  10. package/dist/commands/trace/capacity.mjs +21 -0
  11. package/dist/commands/trace/capacity.mjs.map +1 -0
  12. package/dist/commands/trace/model.d.mts +89 -0
  13. package/dist/commands/trace/model.mjs +251 -0
  14. package/dist/commands/trace/model.mjs.map +1 -0
  15. package/dist/commands/trace/progression.d.mts +11 -0
  16. package/dist/commands/trace/progression.mjs +194 -0
  17. package/dist/commands/trace/progression.mjs.map +1 -0
  18. package/dist/commands/trace/review.d.mts +7 -0
  19. package/dist/commands/trace/review.mjs +51 -0
  20. package/dist/commands/trace/review.mjs.map +1 -0
  21. package/dist/commands/trace/task-link.d.mts +18 -0
  22. package/dist/commands/trace/task-link.mjs +72 -0
  23. package/dist/commands/trace/task-link.mjs.map +1 -0
  24. package/dist/commands/trace/trace.d.mts +1 -0
  25. package/dist/commands/trace/trace.mjs +293 -0
  26. package/dist/commands/trace/trace.mjs.map +1 -0
  27. package/dist/lib/bounded-file.d.mts +1 -0
  28. package/dist/lib/bounded-file.mjs +36 -0
  29. package/dist/lib/bounded-file.mjs.map +1 -0
  30. package/dist/lib/config-store.d.mts +34 -0
  31. package/dist/lib/config-store.mjs +70 -0
  32. package/dist/lib/config-store.mjs.map +1 -0
  33. package/dist/lib/file-lock.mjs +4 -5
  34. package/dist/lib/file-lock.mjs.map +1 -1
  35. package/dist/lib/input-limit.d.mts +4 -0
  36. package/dist/lib/input-limit.mjs +8 -0
  37. package/dist/lib/input-limit.mjs.map +1 -0
  38. package/dist/lib/memory-auto-register.mjs +2 -17
  39. package/dist/lib/memory-auto-register.mjs.map +1 -1
  40. package/dist/lib/report-language-tag.d.mts +1 -0
  41. package/dist/lib/report-language-tag.mjs +4 -0
  42. package/dist/lib/report-language-tag.mjs.map +1 -0
  43. package/dist/lib/report-language.d.mts +1 -0
  44. package/dist/lib/report-language.mjs +50 -0
  45. package/dist/lib/report-language.mjs.map +1 -0
  46. package/dist/lib/skill-catalog.mjs +3 -0
  47. package/dist/lib/skill-catalog.mjs.map +1 -1
  48. package/docs/architecture/storage-model.md +36 -5
  49. package/docs/architecture.md +10 -4
  50. package/docs/cli.md +279 -2
  51. package/docs/contributor-change-matrix.md +1 -2
  52. package/docs/project-structure-overview.md +31 -41
  53. package/package.json +1 -1
  54. package/runtime/BUILD.json +2 -2
  55. package/runtime/agents/operations/trace-interface-review.json +6 -0
  56. package/runtime/agents/operations/trace-scope-review.json +6 -0
  57. package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
  58. package/runtime/prompts/coding-preflight/clean-code.md +18 -20
  59. package/runtime/prompts/coding-preflight/overview.md +1 -1
  60. package/runtime/prompts/duties/code-reviewer.json +1 -1
  61. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  62. package/runtime/prompts/host-orchestration/README.md +18 -9
  63. package/runtime/prompts/launch.template.md +3 -2
  64. package/runtime/prompts/lead/context-loader.md +2 -0
  65. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  66. package/runtime/prompts/lead/report-writer.md +6 -6
  67. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
  68. package/runtime/prompts/profiles/_common-contract.md +1 -1
  69. package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
  70. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
  71. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  72. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
  73. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  74. package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
  75. package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
  76. package/runtime/python/okstra_ctl/code_review_census.py +93 -2
  77. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  78. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  79. package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
  80. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  81. package/runtime/python/okstra_ctl/code_review_target.py +140 -15
  82. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  83. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  84. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  85. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  86. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  87. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  88. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
  89. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  90. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  91. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  92. package/runtime/python/okstra_ctl/json_boundary.py +33 -6
  93. package/runtime/python/okstra_ctl/manager_cli.py +122 -1
  94. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  95. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  96. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  97. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  98. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  99. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  100. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  101. package/runtime/python/okstra_ctl/manager_sync.py +42 -3
  102. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  103. package/runtime/python/okstra_ctl/material.py +2 -0
  104. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  105. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  106. package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
  107. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  108. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  109. package/runtime/python/okstra_ctl/paths.py +6 -1
  110. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  111. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  112. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
  113. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  114. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  115. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  116. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
  117. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  118. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  119. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
  120. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  121. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  122. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  123. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  124. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  125. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  126. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  127. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  128. package/runtime/python/okstra_ctl/render.py +28 -2
  129. package/runtime/python/okstra_ctl/report_assembly.py +38 -11
  130. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  131. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  132. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  133. package/runtime/python/okstra_ctl/report_language.py +4 -1
  134. package/runtime/python/okstra_ctl/report_narrative.py +179 -7
  135. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  136. package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
  137. package/runtime/python/okstra_ctl/run.py +43 -35
  138. package/runtime/python/okstra_ctl/run_context.py +10 -1
  139. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  140. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  141. package/runtime/python/okstra_ctl/task_query.py +239 -0
  142. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  143. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  144. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  145. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  146. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  147. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  148. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  149. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  150. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  151. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  152. package/runtime/python/okstra_project/state.py +20 -0
  153. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  154. package/runtime/python/okstra_token_usage/cli.py +23 -10
  155. package/runtime/python/okstra_token_usage/collect.py +25 -22
  156. package/runtime/python/okstra_token_usage/policy.py +193 -0
  157. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  158. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  159. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  160. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  161. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  162. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  163. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  164. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  165. package/runtime/skills/okstra-code-review/SKILL.md +58 -50
  166. package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
  167. package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
  168. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  169. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  170. package/runtime/skills/okstra-manager/SKILL.md +24 -0
  171. package/runtime/skills/okstra-memory/SKILL.md +1 -1
  172. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  173. package/runtime/skills/okstra-run/SKILL.md +55 -183
  174. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  175. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  176. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  177. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  178. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  179. package/runtime/templates/manager/view.template.html +4 -0
  180. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  181. package/runtime/templates/trace/trace.template.md +42 -0
  182. package/runtime/validators/checks/fixtures-02.py +25 -33
  183. package/runtime/validators/validate-run.py +93 -36
@@ -65,16 +65,12 @@ Search the identifier across the file. If occurrences carry different types or r
65
65
 
66
66
  Judge cohesion, complexity and abstraction levels. Split mixed responsibilities or levels when extraction improves the flow. A name containing "and" or a scrolling body prompts inspection, not automatic splitting. An orchestrator may call several named steps at one abstraction level; name their overall purpose.
67
67
 
68
- ### Plain-English summary test
69
-
70
- For each added or meaningfully modified function, check whether short English sentences describing each line form readable prose. If that requires grouping lines under an invented name, represent the group as a named helper or intermediate value. A local readability helper may have one caller; the second-caller requirement concerns reuse-driven layers.
71
-
72
68
  ### Inspect for readability problems
73
69
 
74
- - Apply "Limit nesting depth" below; inspect mixed abstraction levels, 5+ anonymous temporaries, unnamed non-obvious transformation stages and boolean expressions with buried intent.
75
- - Name the steps of 4+ distinct inline phases, each longer than a line or two.
76
- - Use a `switch` for branches over one enum so cases and exhaustiveness are visible.
77
- - Extract a named builder when dense conditional fields are assembled inside a method doing other work.
70
+ - Inspect mixed responsibilities or abstraction levels, anonymous temporaries, unnamed non-obvious transformation stages and boolean expressions with buried intent. Trace what a reader or caller must understand and identify the concrete ambiguity or maintenance consequence.
71
+ - Name inline phases when that exposes a cohesive step or separates unrelated responsibilities; a count of phases or temporaries alone does not require extraction.
72
+ - For branches over one enum, inspect whether cases and exhaustiveness are clear; use a `switch` when it improves them.
73
+ - Extract a named builder when dense conditional fields obscure a distinct construction responsibility. Apply "Limit nesting depth" below as an inspection signal.
78
74
 
79
75
  ### Function size review signal
80
76
 
@@ -82,7 +78,7 @@ Review newly added or substantially edited functions beyond 50 effective body li
82
78
 
83
79
  ### What's fine
84
80
 
85
- Straight sequences of named steps, clear idiomatic framework patterns and guard clauses are acceptable. Short functions still follow nesting and other applicable rules.
81
+ Straight sequences of named steps, clear idiomatic framework patterns and guard clauses are acceptable. Short functions still require inspection when they obscure a decision or mix responsibilities.
86
82
 
87
83
  ## Mutation and state boundaries
88
84
 
@@ -126,7 +122,7 @@ When replacing an error, retain the original as its cause, including its diagnos
126
122
 
127
123
  ## Testing discipline
128
124
 
129
- Apply these rules to every test file; language-specific detection patterns are in `languages/*.md`. New behavior without a test is incomplete unless the user explicitly waives it for this change and project rules permit it. Record the exact waived behavior or check as unverified, including its branch-test, branch-deletion or resource-bound requirement. A waiver neither weakens existing tests nor establishes coverage; all other checks and quality rules for written or edited tests still apply.
125
+ Apply these rules to every test file; language-specific detection patterns are in `languages/*.md`. Changed core behavior and meaningful failure outcomes require tests unless the user explicitly waives them for this change and project rules permit it. Record the exact waived behavior or check as unverified, including any explicit project-required mutation check or resource-bound requirement. A waiver neither weakens existing tests nor establishes coverage; all other checks and quality rules for written or edited tests still apply.
130
126
 
131
127
  ### Reuse tests before adding coverage
132
128
 
@@ -134,7 +130,7 @@ Before function edits or new test plans, search names, behavior, callers and ass
134
130
 
135
131
  Record the changed function, search terms, existing test locations and grounds for retaining, extending, adding or retiring coverage. Use `extend <path:line>`, `new (nothing covers <behavior>)` or `retire <path:line> (behavior moved to <where>)`. New tests without survey evidence are unfinished. Retire a test in the same commit only when its behavior is gone or a replacement asserts it more strongly through the same seam; otherwise retain it.
136
132
 
137
- Keep distinct outcomes and meaningful failures, not parallel cases or cases per helper, branch, model, provider or task-type combination. Each behavior has one primary test owner; integration cases need separate wiring risks. Branch-deletion checks reuse this coverage. Completion self-check and code review assess the mapping.
133
+ Keep distinct outcomes and meaningful failures, not parallel cases or cases per helper, branch, model, provider or task-type combination. Each behavior has one primary test owner; integration cases need separate wiring risks. Selective mutation checks reuse this coverage. Completion self-check and code review assess the mapping.
138
134
 
139
135
  ### No self-mocking
140
136
 
@@ -154,9 +150,11 @@ List all writes to the asserted field in the flow. Assert the last write as well
154
150
 
155
151
  Claim an effect's coverage only where its real producing path runs. Reaching a mock that replaces that path does not verify the effect behind it.
156
152
 
157
- ### Every branch you add gets a test that dies with it
153
+ ### Focus regression tests on changed outcomes
154
+
155
+ Use retained or strengthened tests to distinguish changed core behavior and meaningful failure outcomes from an incorrect implementation. Merely reaching the method is insufficient, especially when recovery is the behavior added beyond a library's happy path.
158
156
 
159
- For every unwaived new `catch`, guard, early return or `else`, delete its body and run the suite to confirm a test fails. Merely reaching the method is insufficient, especially when recovery is the only behavior added beyond a library's happy path. This does not require a separate test function per branch.
157
+ Use a targeted mutation check when uncertainty remains about whether a test detects a regression, particularly for security, concurrency or recovery paths. Change the suspected behavior, confirm the focused test fails for that reason, then restore the source and rerun it. A manual mutation check for every syntactic branch is not required by this common pack; explicit project requirements retain their precedence.
160
158
 
161
159
  ### Shared fixtures keep the ordinary default
162
160
 
@@ -164,11 +162,11 @@ Keep shared fixture defaults on the ordinary path. Pass exceptional conditions e
164
162
 
165
163
  ### Test data must actually separate the paths
166
164
 
167
- Use distinguishing inputs for source/destination, existing/incoming and success/conflict paths; identical setup and outcome do not justify separate cases. State each test's distinguishing input, then remove that difference to check whether the assertion detects it; defaults must not let an incorrect implementation pass.
165
+ Use distinguishing inputs for source/destination, existing/incoming and success/conflict paths; identical setup and outcome do not justify separate cases. State each test's distinguishing input and inspect whether its assertions depend on that difference; defaults must not let an incorrect implementation pass.
168
166
 
169
167
  ### A test title names the unit and the one condition it isolates
170
168
 
171
- The failure line identifies the unit and isolated condition, using a grouping name where appropriate. If a parameterized case trips two guards, separate them before naming one. Remove the input credited by the title: if the test still passes, correct the setup or title to match the path actually verified.
169
+ The failure line identifies the unit and isolated condition, using a grouping name where appropriate. If a parameterized case trips two guards, separate them before naming one. Match the setup and title to the behavior the assertions actually verify.
172
170
 
173
171
  ### Test tooling you add is used in the same change
174
172
 
@@ -196,12 +194,12 @@ Use "Finding evidence and grading" below. Unreachable-state guards and extra tes
196
194
  Implementation, independent verification and review use `review-rules.json` for rule IDs and blocking severity/timing. Referenced rules define applicability; `overview.md` defines precedence.
197
195
 
198
196
  - An `execution-error` establishes a reachable input/state, expected behavior and actual wrong result.
199
- - A `design-violation` establishes the applicable rule, violating source and concrete maintenance or design consequence; no runtime failure is required. A preferred alternative alone is insufficient.
200
- - `must-fix` means a defect or a violation with substantial consequences; `should-fix` is a clear violation without immediate breakage; `nit` is a small, demonstrable improvement. Confidence is not severity; missing inspection is incomplete coverage.
197
+ - A `design-violation` establishes the violating source and either an explicit applicable project requirement or a concrete maintenance or design consequence under the applicable rule; no runtime failure is required. A preferred implementation, name or style alone is insufficient.
198
+ - `must-fix` means a defect or a violation with substantial consequences; `should-fix` requires an explicit applicable project rule breach or an evidenced maintenance or design impact without immediate breakage; `nit` is a small, demonstrable improvement. Grade the established impact rather than generic style preference or confidence; missing inspection is incomplete coverage.
201
199
  - `now` is introduced or changed by this change. `park` needs a cited scope or accepted-risk basis, not cost, passing tests or a restrictive plan. Reclassifying explicitly accepted product behavior requires new evidence.
202
200
  - Unresolved blocking `now` findings prevent acceptance: executors fix them, verifiers return `FAIL`, and reviewers preserve them for settlement. Record `nit` and justified `park` findings without blocking. Semantic grading remains worker judgment.
203
201
 
204
- M1 covers truthful, specific, standalone names; M2 covers cohesion, complexity, abstraction levels, nesting and plain-English flow. Size prompts inspection, not a finding by itself. Clear violations are normally `should-fix` / `now` even when execution is correct. Cite the construct and consequence; do not demand unrelated legacy cleanup.
202
+ M1 covers truthful, specific, standalone names; M2 covers cohesion, complexity, abstraction levels and comprehensible control flow. Size, nesting depth and counts of inline stages prompt inspection; they do not establish a finding by themselves. Correct execution does not waive an explicit project requirement or an evidenced design or maintenance impact. Cite the construct and the governing project rule or concrete consequence; do not demand unrelated legacy cleanup.
205
203
 
206
204
  `file_size_cap.py` measures physical size; reviewers judge responsibility. An oversized legacy file need not be cleaned wholesale, but adding unrelated responsibility still violates S3 or M2. Small wiring edits may remain with a cited rationale. Restrictive plan placement does not waive these rules: return a plan conflict with a conforming location and preserved acceptance behavior, and obtain plan repair before writing outside authorized scope.
207
205
 
@@ -231,11 +229,11 @@ No `eval`, `Function(...)`, dynamic `import()` of an input-chosen path, or deser
231
229
 
232
230
  ## No magic numbers
233
231
 
234
- Replace hardcoded values with named constants.
232
+ Name values when their units, governing policy or repeated use carry meaning that callers or maintainers need. Keep clear idiomatic literals, such as zero for an empty count or one for an increment, inline. A numeric literal alone does not establish a finding; identify the obscured meaning, policy drift risk or explicit project rule that requires a name.
235
233
 
236
234
  ## Limit nesting depth
237
235
 
238
- Count nested control-flow blocks within each function; the function, class, and module bodies do not count. At three levels, inspect readability rather than requiring a split solely for the count. At four or more, flatten with early returns or extract a named step before completion. Short functions follow the same threshold. Enforcement is the preflight self-check and code review.
236
+ Deeply nested control flow, including four or more nested control-flow blocks, prompts inspection of the decisions, state and exit paths a reader must track. The function, class and module bodies do not count. Flatten with early returns or extract a named step when that resolves a concrete comprehension or maintenance problem; depth alone does not require a rewrite. Explicit project limits retain their precedence. Enforcement is the preflight self-check and code review.
239
237
 
240
238
  ## Comments explain *why*, not *what*
241
239
 
@@ -60,4 +60,4 @@ Workers authorized to change source also read [authoring-checks.md](authoring-ch
60
60
 
61
61
  ## Verification commands
62
62
 
63
- Select repository-configured formatting, lint, type and test commands appropriate to the changed behavior and contracts. Execution authority and full-check timing follow the assignment and repository procedure. Do not add tools, configuration or dependencies solely for this pack. Record unavailable or unconfigured checks as unverified with reasons. Command selection does not waive applicable behavior-test, branch-deletion or cause-verification obligations.
63
+ Select repository-configured formatting, lint, type and test commands appropriate to the changed behavior and contracts. Execution authority and full-check timing follow the assignment and repository procedure. Do not add tools, configuration or dependencies solely for this pack. Record unavailable or unconfigured checks as unverified with reasons. Command selection does not waive focused behavior and failure tests, cause verification or explicit project-required mutation checks; use the selective mutation criteria in [Testing discipline](clean-code.md#testing-discipline).
@@ -22,7 +22,7 @@
22
22
  "A clean verdict explains inspected evidence. For checked G2/G3/G5, preserve the calibration's source-cited observations after ::. Missing inspection or required execution stays unaccounted; unavailable performance bounds stay unverified."
23
23
  ],
24
24
  "collaborationContract": [
25
- "Only the assigned review function belongs to this invocation. Delegation and model-team consolidation require an explicit task assignment; otherwise return your own verdicts without spawning reviewers.",
25
+ "Only the assigned review function belongs to this invocation. Return your own verdicts without spawning reviewers; the lead owns dispatch, audits and team consolidation.",
26
26
  "Return out-of-assignment evidence and aggregation conflicts to their owner without changing cell identities or borrowing another team's verdicts."
27
27
  ],
28
28
  "completionCriteria": [
@@ -0,0 +1,32 @@
1
+ {
2
+ "schemaVersion": "1.0",
3
+ "id": "interface-reviewer",
4
+ "roleId": "verifier",
5
+ "responsibilities": [
6
+ "Independently judge whether a proposed interface design serves every approved use case and requirement through sound domain boundaries and public signatures, before any interface code is written."
7
+ ],
8
+ "requiredConduct": [
9
+ "Map every approved requirement to at least one use case and every use case to the boundaries and signatures that serve it. Read the existing modules, callers and conventions the design touches, and check each signature's inputs, outputs, failure results and ownership against that use case and the surrounding code."
10
+ ],
11
+ "decisionPrinciples": [
12
+ "Prefer the smallest interface that serves the approved use cases and fits existing project boundaries. Distinguish a missing or unserved use case, a boundary that leaks another layer's concern and a signature that cannot express a required outcome from a stylistic preference, and leave scope decisions to the approved specification."
13
+ ],
14
+ "authorityAndBoundaries": [
15
+ "Review the assigned design against the approved specification and existing code without rewriting either. Do not add requirements, redesign unrelated modules or write interface code."
16
+ ],
17
+ "evidenceStandards": [
18
+ "Each finding names the requirement or use case affected, the boundary or signature at fault, the existing code it conflicts with as path:line where one exists, and the consequence for implementation or callers. A clean verdict states what was mapped and checked."
19
+ ],
20
+ "collaborationContract": [
21
+ "Return findings and the verdict to the lead with their evidence. Do not negotiate the design with its author or decide whether the specification itself should change."
22
+ ],
23
+ "completionCriteria": [
24
+ "Every requirement and use case has been traced to the design, every public signature has been checked against the use cases it serves, and unmapped items, defects and clean checks are all recorded."
25
+ ],
26
+ "prohibitions": [
27
+ "Do not pass a design with an unserved use case or unmapped requirement, turn naming or style preferences into defects, or propose implementation details beyond the interface."
28
+ ],
29
+ "blockedStateReporting": [
30
+ "Identify the missing specification, use-case table or source context, the mapping that cannot be completed, the attempts made and the requirements or use cases left unverified."
31
+ ]
32
+ }
@@ -1,17 +1,26 @@
1
1
  # Host orchestration rules
2
2
 
3
- One file per task-type whose host orchestration carries gates. A task-type with
4
- no gates has no file here, and its runs get no
5
- `instruction-set/host-orchestration-rules.md`.
3
+ The phase catalog explicitly declares which task types require host rules:
4
+ `implementation` and `implementation-planning`. Their canonical files live in
5
+ the owning phase packages as `host-rules.md`; an asset root without a Python
6
+ package uses this directory's `<task-type>.md` path. A missing declared file is
7
+ an installation error. Undeclared task types get an empty host-rules path,
8
+ regardless of whether a file exists.
6
9
 
7
- Each file is the single source for two generated surfaces:
10
+ The wizard exposes the selected canonical file's absolute path as
11
+ `outcome.orchestration.hostRulesPath`. The `okstra-run` skill reads a non-empty
12
+ path after confirmation and before the first `render-bundle`, so waiver and
13
+ recovery instructions are available even when preparation fails. It does not
14
+ embed the implementation or planning rules in its body.
8
15
 
9
- - `skills/okstra-run/SKILL.md` — a `<!-- BEGIN FRAGMENT: host-orchestration-<task-type> -->`
10
- block, synced by `tools/sync-skill-fragments.mjs` (`--check` fails on drift).
11
- - `<run>/instruction-set/host-orchestration-rules.md` — written by
12
- `scripts/okstra_ctl/run.py` at prepare time.
16
+ `scripts/okstra_ctl/run.py` copies declared rules into the prepared instruction
17
+ set as `host-orchestration-rules.md`. This frozen copy governs resumed work and
18
+ stage chaining. The launch prompt still requires the lead to read it within the
19
+ run; a pre-prepare read of the canonical file does not satisfy the implementation
20
+ session read gate. Legacy prepared runs with no frozen file retain the existing
21
+ session-conformance compatibility behavior.
13
22
 
14
- The second surface exists because a rule that lives only in the conversation is
23
+ The frozen copy exists because a rule that lives only in the conversation is
15
24
  one compaction away from gone: a DEV-10400 run operated for five turns on a
16
25
  skill body truncated mid-Step-5 and nothing signalled the loss. On disk, the
17
26
  rules survive compaction and `validators/validate_session_conformance.py` can
@@ -191,11 +191,12 @@ The **default is full re-verification**. Narrow this re-run to the impacted stag
191
191
  4. **`mode == "full"`** → run the existing full re-verification path unchanged; ignore `reverify_stages` / `carry_stages`.
192
192
  5. **`mode == "incremental"`** → scope every worker dispatch prompt to `reverify_stages` only (the downstream closure of the impacted stages). Do NOT re-analyze `carry_stages` — their prior plan-item verdicts are carried forward verbatim (see `scripts/okstra_ctl/phases/implementation_planning/profile.md` "Cross-verification mode" and `prompts/lead/convergence.md` "Convergence scope"). When the pin in step 0 was `auto`, this is the decision — do not upgrade it to full.
193
193
  6. **`mode == "unresolved"`** → ask the user for stage numbers; re-enter step 3 with those numbers in `--impacted`. Do not fall back to full. Do not record `unresolved` as `incrementalDecision`. Then continue from the new `mode`.
194
- 7. **Merge carried-forward verdicts.** In `incremental` mode the report writer receives the carried stage rows as a packet source and is told, in its own authoring contract, to copy them unchanged — you do not repeat that instruction to it. After `okstra plan-items seed --narrative ... --state ...`, the lead runs:
194
+ 7. **Merge carried-forward verdicts.** In `incremental` mode the report writer receives the carried stage rows as a packet source and is told, in its own authoring contract, to copy them unchanged — you do not repeat that instruction to it. After `okstra plan-items seed --run-manifest {{RUN_MANIFEST_RELATIVE_PATH}} --narrative <this run's reportNarrativePath> --state ...`, the lead runs:
195
195
  ```
196
196
  okstra incremental-carry \
197
+ --run-manifest {{RUN_MANIFEST_RELATIVE_PATH}} \
197
198
  --prev-data {{RUN_REPORTS_RELATIVE_PATH}}/final-report-implementation-planning-<prev-seq>.data.json \
198
- --cur-narrative <this run's report-writer narrative> \
199
+ --cur-narrative <this run's reportNarrativePath> \
199
200
  --state <this run's plan-body-verification state> \
200
201
  --prev-seq <prev-seq> \
201
202
  --decision {{INCREMENTAL_DECISION_STATE_RELATIVE_PATH}} \
@@ -45,6 +45,8 @@ Run Input is the only Phase 1 source for task identity, work category, workflow
45
45
 
46
46
  Use the `Worker Roster` section for dispatch and model assignment. Use `Artifact Paths` for prompt, result, report, status, validator, and resume locations. Use `Configuration References` for the task-level Markdown resources. Do not derive sibling paths from file names or sequence counters.
47
47
 
48
+ Use `Report authoring format` as the current run's declared writer syntax and `Report writer input` as its exact stored authoring path, including when the lead writes that input directly.
49
+
48
50
  Use the `Current phase` labels as the workflow view. Rules for `nextRecommendedPhase` are maintained by [report-writer](./report-writer.md); do not re-derive phase routing here.
49
51
 
50
52
  ## Output
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Overview
4
4
 
5
- The lead orchestrates the selected AI workers against a prepared task bundle, collects their independent outputs, supervises convergence, and ensures the final report is produced. When `Report writer worker` is in the selected roster, that worker authors the report narrative Markdown; report assembly publishes the final record from role-owned inputs. The lead never substitutes its own reasoning for a worker result and never bypasses a rostered report writer.
5
+ The lead orchestrates the selected AI workers against a prepared task bundle, collects their independent outputs, supervises convergence, and ensures the final report is produced. When `Report writer worker` is in the selected roster, that worker authors the report input in the run manifest's declared `reportAuthoringFormat`; report assembly publishes the final record from role-owned inputs. The lead never substitutes its own reasoning for a worker result and never bypasses a rostered report writer.
6
6
 
7
7
  The lead owns the approval decision ledger and writes it only through `okstra approval-decision`. The activity recorder owns the activity ledger. Runtime adapters own team state and usage. The convergence engine owns convergence state and the completed plan-body result. The design-surface detector owns the design-preparation snapshot. Report assembly validates these inputs and publishes `final-report-*.data.json` once; a failure is returned to the owner named in its diagnostic.
8
8
 
@@ -57,7 +57,7 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
57
57
  | `okstra model-io run-input --run-manifest <path>` | Read run identity, worker roster, model assignments, and artifact paths instead of opening the run manifest | `context-loader` "Step 3" |
58
58
  | `okstra model-io active-context-input --project-root <dir> --run-manifest <path>` | Read the prior executor base ref for an incremental re-run | launch prompt "Incremental re-verification" |
59
59
  | `okstra incremental-scope --prev-data <path>` | Decide re-verify vs carry-forward stages on a clarification re-run | launch prompt "Incremental re-verification" |
60
- | `okstra incremental-carry --prev-data <path> --prev-seq <seq> --cur-narrative <path>` | Merge carried-forward plan-item verdicts after `plan-items seed`; then repeat `plan-items prepare --state`, `prompt` and `validate-prepared --state` | launch prompt "Incremental re-verification" |
60
+ | `okstra incremental-carry --run-manifest <current-run-manifest> --prev-data <path> --prev-seq <seq> --cur-narrative <reportNarrativePath>` | Merge carried-forward plan-item verdicts after `plan-items seed`; then repeat `plan-items prepare --state`, `prompt` and `validate-prepared --state` using that same manifest | launch prompt "Incremental re-verification" |
61
61
  | `okstra stage-map <task-key>` | Read the prior Stage Map and done stages before re-planning | host orchestration rules (implementation-planning) |
62
62
  | `okstra stage-close <task-key> --stage <N> --from-commit <sha> [--supersede-failed <reason>]` | Close a stage whose work already landed outside okstra, or a `failed` stage whose failure no longer applies |
63
63
  | `okstra stage-reopen <task-key> --stage <N> --reason <why> [--evidence <report>]` | Reopen a `done` stage for a fix run, e.g. after a `blocked` final-verification of that stage | host orchestration rules (implementation-planning) |
@@ -160,19 +160,19 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
160
160
  |---|---|---|
161
161
  | `okstra agent-prompt check-corrections --project-root <dir> --run-manifest <path> --corrections <path>` | Check a report-writer corrections ledger before a corrective dispatch | `report-writer` "Corrective report-writer dispatch" |
162
162
  | `okstra agent-prompt apply-corrections --project-root <dir> --run-manifest <path> --corrections <path>` | Apply a ledger that `check-corrections` reported `mechanical: true`, without a writer round | `report-writer` "Corrective report-writer dispatch" |
163
- | `okstra design-snapshot --narrative <path> --output <path>` | Complete the design-surface detector snapshot; both paths come from the run manifest | `report-writer` "Implementation-planning sequence" |
163
+ | `okstra design-snapshot --run-manifest <path> --narrative <path> --output <path>` | Complete the design-surface detector snapshot; both paths and the authoring format come from that run manifest | `report-writer` "Implementation-planning sequence" |
164
164
  | `okstra plan-items prepare --run-manifest <path> --narrative <path>` | Extract this round's plan items (add `--state <path>` after a self-fix or `incremental-carry`, `--tie-vote` for a critic tie round) | `plan-body-verification` "Round protocol" |
165
165
  | `okstra plan-items prompt --run-manifest <path>` | Print the plan-items block placed verbatim in every verifier prompt | `plan-body-verification` "Round protocol" |
166
166
  | `okstra plan-items validate-prepared --run-manifest <path> --narrative <path>` | Validate the prepared envelope before dispatch; pass the same `--state` the last `prepare` used | `plan-body-verification` "Round protocol" |
167
- | `okstra plan-items seed --narrative <path>` | Create the `planItems[]` rows a round lands in | `plan-body-verification` "Round protocol" |
168
- | `okstra plan-items extract --narrative <path> --output <path>` | Re-extract plan items after a round and re-verify any item whose subject shifted | `plan-body-verification` "Round protocol" |
167
+ | `okstra plan-items seed --run-manifest <path> --narrative <path>` | Create the `planItems[]` rows a round lands in | `plan-body-verification` "Round protocol" |
168
+ | `okstra plan-items extract --run-manifest <path> --narrative <path> --output <path>` | Re-extract plan items after a round and re-verify any item whose subject shifted; use the input path declared by that run manifest | `plan-body-verification` "Round protocol" |
169
169
  | `okstra plan-items correction-prompt --run-manifest <path> --state <path> --worker <id>` | Put its output first in a `worker-correction` re-dispatch prompt | `plan-body-verification` "Round protocol" |
170
170
  | `okstra plan-items collect-verdicts --items <path> --result <worker>=<path> --output <path>` | Read a round's responses into a verdicts envelope; never parse them by hand | `plan-body-verification` "Round protocol" |
171
171
  | `okstra plan-items apply-verdicts --state <path> --round <N> --result <worker>=<path>` | Record the round's verdicts | `plan-body-verification` "Round protocol" |
172
172
  | `okstra plan-items complete-round --state <path> --run-manifest <path> --round <N>` | Record the completed round | `plan-body-verification` "Round protocol" |
173
173
  | `okstra plan-items next-dispatch --state <path>` | Decide whether the round opens another worker batch | `plan-body-verification` "Round protocol" |
174
174
  | `okstra plan-items resolve-dissent --state <path> --item <P-id> --decision-file <path>` | Record an evidence-based lead decision after the single self-fix | `plan-body-verification` "Round protocol" |
175
- | `okstra plan-verify --report <path>` | Score the plan-body gate; never tally votes in a script | `plan-body-verification` "Round protocol" |
175
+ | `okstra plan-verify --run-manifest <path> --narrative <reportNarrativePath> --state <path>` | Score the plan-body gate before report assembly, using that run's declared input format; never tally votes in a script | `plan-body-verification` "Round protocol" |
176
176
  | `okstra worktree-lock --worktree <dir> --command <text>` | Lead minor fix (implementation only, never in a run marked `verificationEvidenceVersion`): re-run each Tier 1 command and failing verifier check that covers a fixed finding, in the stage worktree, under its lock | `_implementation-deliverable.md` "Lead minor fix" |
177
177
 
178
178
  ### Phase 7 — persist
@@ -590,7 +590,7 @@ If convergence is disabled, `seed`/`finalize` produce the auto-disabled final st
590
590
 
591
591
  ### Authoring ownership (BLOCKING)
592
592
 
593
- If `Report writer worker` is in the selected roster (`recommendedWorkers` / `resultContract.workerRoles`), Lead dispatches it to author only `report-writer-narrative-<task-type>-<seq>.md`, its worker-result pointer, and its audit sidecar. The worker may read the complete run context but cannot write `final-report-*.data.json` or another role's ledger. After every required input exists, Phase 7 runs report assembly, which validates the role-owned inputs and atomically publishes the report record once. Phase 7 then renders the human HTML from that record. Contract v2 artifacts remain readable but no new run writes them. **Enforced:** report-writer dispatch completion paths in `scripts/okstra_ctl/dispatch_state.py`, granted artifacts in `scripts/okstra_ctl/dispatch_core.py`, and `scripts/okstra_ctl/report_assembly.py` `assemble_report`.
593
+ If `Report writer worker` is in the selected roster (`recommendedWorkers` / `resultContract.workerRoles`), Lead dispatches it to author only the input at the run manifest's `reportNarrativePath`, its worker-result pointer, and its audit sidecar. `reportAuthoringFormat=json-v1` selects standard JSON with ordinary Markdown inside description strings; an absent field retains `markdown-v1` and the existing narrative line grammar. Use the declared path and format, including its `.json` or `.md` extension. The worker may read the complete run context but cannot write `final-report-*.data.json` or another role's ledger. After every required input exists, Phase 7 runs report assembly, which validates the role-owned inputs and atomically publishes the report record once. Phase 7 then renders the human HTML from that record. Contract v2 artifacts remain readable but no new run writes them. **Enforced:** report-writer dispatch completion paths in `scripts/okstra_ctl/dispatch_state.py`, granted artifacts in `scripts/okstra_ctl/dispatch_core.py`, and `scripts/okstra_ctl/report_assembly.py` `assemble_report`.
594
594
 
595
595
  Before constructing the dispatch prompt, the lead MUST:
596
596
 
@@ -4,7 +4,7 @@
4
4
 
5
5
  Phase 6 gives the report writer all settled analysis, convergence, task, and planning context required for synthesis. Read access supplies context; it does not grant write authority over another owner's file.
6
6
 
7
- The report writer writes only the report narrative Markdown, its pointer record, and its audit sidecar. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
7
+ The report writer writes only the report authoring input, its pointer record, and its audit sidecar. The run manifest's `reportAuthoringFormat` selects standard JSON for `json-v1`; an absent field selects the existing `markdown-v1` line grammar. `reportNarrativePath` retains its name and identifies that exact input path. Never infer the format from its suffix or change an existing run's format. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
8
8
 
9
9
  The narrative owns judgments, plan body, summaries, user explanation, recommended steps, and follow-up descriptions. It never owns `designPreparation`, `designSurfaceCoverage`, `executionStatus`, `executionRoles`, `tokenUsage`, `crossVerification`, `approvalContext`, `clarificationItems`, `agentActivity`, or `planBodyVerification`. It must not pre-fill a future round, future gate result, activity identifier, usage value, or resolution.
10
10
 
@@ -14,7 +14,7 @@ Report assembly reads the role-owned inputs, validates them, derives links and s
14
14
 
15
15
  | Input | Owner | Write boundary |
16
16
  |---|---|---|
17
- | report narrative Markdown | report-writer | `reportNarrativePath` |
17
+ | report authoring input in the declared format | report-writer | `reportNarrativePath` |
18
18
  | approval decision ledger | lead | `approvalDecisionsPath` through `okstra approval-decision` |
19
19
  | activity ledger | activity recorder | `leadEventsPath` through `okstra agent-activity append` |
20
20
  | team state and usage | runtime/accounting adapter | `teamStatePath` |
@@ -48,7 +48,7 @@ project-relative path and value. The report writer receives the
48
48
  packet's Markdown reading projection as the only task input instead of an
49
49
  independently assembled list of raw paths.
50
50
 
51
- The packet's authoring contract names the result path, narrative format, writing
51
+ The packet's authoring contract names the result path, selected authoring format, writing
52
52
  instructions, runtime-owned content, and validation rules. Missing configured
53
53
  paths and missing files are collected across the full source set before dispatch
54
54
  and reported together with their owners. Report assembly checks source availability
@@ -89,13 +89,13 @@ For `rewrite`, the materialized correction-only prompt supplies target values, c
89
89
 
90
90
  This section adds report-specific checks to [okstra-lead-contract](./okstra-lead-contract.md) "Worker instruction quality gate"; it does not limit that common gate to report-writer calls. A follow-up dispatch that revises a narrative which already exists and whose structure parses is a corrective dispatch, and its instruction is a corrections ledger, not prose:
91
91
 
92
- 1. Preserve the attempt: copy the current narrative to `worker-results/report-writer-narrative-a<N>-<task-type>-<seq>.md`. The ledger's `baseNarrativePath` names that copy, never the live `reportNarrativePath` — the correction overwrites the live file, and the copy is what the writer (or `apply-corrections`) reads.
92
+ 1. Preserve the attempt: copy the current input to a distinct attempt file in the same `worker-results/` directory, inserting `-a<N>` into its filename and retaining its actual `.json` or `.md` extension. Take the source path from `reportNarrativePath`. The ledger's `baseNarrativePath` names that copy, never the live `reportNarrativePath` — the correction overwrites the live file, and the copy is what the writer (or `apply-corrections`) reads. The preserved copy uses the run's declared format too.
93
93
  2. The ledger lives at `runs/<task-type>/state/report-writer-corrections-<task-type>-<seq>-a<N>.json` (schema `schemas/report-writer-corrections-v1.0.schema.json`) and holds one entry per defect: `replace` with the exact replacement value (add `current` when you want it checked), `remove` for an item or optional field, `rewrite` with a `rule` when the writer has to re-author prose. Paths use the validator's grammar (`implementationOptionSelection.rankedOptions[1].coverageSummary.coveragePercent`), so a report-assembly refusal can be copied into the ledger verbatim. Never write an indirect instruction such as `use the schema value`, `use the valid status`, or `fix the enum`: a `replacement` is the literal, and a `rule` names the required outcome. You do not copy allowed enum literals by hand — okstra attaches each `rewrite`'s schema constraint from the frozen schema.
94
94
  3. Run `okstra agent-prompt check-corrections --project-root <root> --run-manifest <path> --corrections <ledger>` until it reports no defect. It applies the ledger to a scratch copy of the base narrative and validates the complete proposed narrative against the writer-owned value schema and the task's semantic validator, listing every defect at once. Validating only the edited field is insufficient because one replacement can select a different schema branch, which is why the check covers the whole narrative.
95
95
  4. When the check reports `mechanical: true` and has corrections, run `okstra agent-prompt apply-corrections` with the same arguments: okstra writes the corrected narrative to `reportNarrativePath` and records a `lead-correction-applied` activity row naming the ledger and its correction ids. This includes validated `replace`, `remove`, `add`, `move`, and derived step counts. No writer dispatch, `record-dispatch`, or `link-result` follows; the roster row's result already exists.
96
96
  5. Otherwise materialize the writer prompt with the same `--corrections <ledger>` under a new invocation id and prompt path (when the first attempt's result is linked, retire that link with `reject-result` as `plan-body-verification` (the absolute path in **Okstra Runtime Resources**) describes; a dispatch that ended in `error` has no link, so skip that step). okstra renders the correction-only field values, evidence, schema constraints, replacement-file contract, application command, and output paths. Put context in the ledger; the initial instruction body is not sent to the correction writer.
97
97
 
98
- A report-writer materialization without `--corrections` whose narrative already exists and parses is refused before any prompt is written — free-form corrections cannot be checked before the writer runs, and four of six re-runs in the 2026-09-03 measurement were lead instructions that contradicted the authoring contract. Only a narrative whose structure does not parse (line grammar, an unknown top-level field) is re-authored, not corrected: that dispatch needs no ledger, and its body quotes the parser's message. Because re-authoring overwrites the live file in place, okstra copies the existing narrative to `worker-results/<narrative-name>.pre-<invocation-id>.md` at materialization and renders a `## Previous Attempt` section naming that copy (**Enforced:** `_preserve_reauthored_narrative` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`); the 2026-09-09 dev-10642 run lost a 579-line attempt to a failed in-place re-indent command with no copy to fall back on. A narrative that breaks the line grammar is not a produced artifact: the dispatcher settles that attempt as `required worker artifact is unusable: narrative does not parse: …` and retries it inside the same batch, so you see the parser's message at collection, not at Phase 7 assembly (**Enforced:** `okstra_ctl.dispatch_state.unusable_result_defect`, read by `missing_completion_paths` and the `team await` record path). The synthesis packet's Authoring Contract carries the line grammar itself (`report_narrative.NARRATIVE_GRAMMAR_INSTRUCTIONS`), so a writer that reads only the packet still sees it. Value defects — an id outside its pattern, a value outside its enum, a missing required field — leave the structure readable and are exactly what the ledger fixes; the a3 attempt of the 2026-09-03 run carried twenty `SC-` ids that assembly refused and was still a corrective base.
98
+ A report-writer materialization without `--corrections` whose narrative already exists and parses is refused before any prompt is written — free-form corrections cannot be checked before the writer runs. Only an input whose structure does not parse under the run's declared format is re-authored: that dispatch needs no ledger, and its body quotes the parser's message. Before overwriting the live input, okstra preserves a `worker-results/<narrative-stem>.pre-<invocation-id><original-extension>` copy and renders a `## Previous Attempt` section naming it. Retain the actual `.json` or `.md` extension and the run's declared format (**Enforced:** `_preserve_reauthored_narrative` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`). An input that breaks its declared syntax is not a produced artifact: the dispatcher settles that attempt as `required worker artifact is unusable: narrative does not parse: …` and retries it inside the same batch, so the parser's message appears at collection (**Enforced:** `okstra_ctl.dispatch_state.unusable_result_defect`, read by `missing_completion_paths` and the `team await` record path). The synthesis packet carries `JSON_NARRATIVE_INSTRUCTIONS` for `json-v1` or `NARRATIVE_GRAMMAR_INSTRUCTIONS` for `markdown-v1`. Value defects — an id outside its pattern, a value outside its enum, a missing required field — leave the structure readable and are handled by the correction ledger.
99
99
 
100
100
  **Enforced:** `_with_report_writer_sections` / `_refuse_free_form_correction` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`, `report_corrections.check_corrections`, `agent/prompt_cli/corrections.run_corrections_apply`; the retired Python suite and the retired Python suite keep this procedure in the lead contract.
101
101
 
@@ -107,7 +107,7 @@ A report-writer materialization without `--corrections` whose narrative already
107
107
  4. Apply at most one automatic planner self-fix to the narrative. Skip this step when `gating` is `false`.
108
108
  5. Run targeted re-verification as round 2 when needed. Skip this step when `gating` is `false`.
109
109
  6. Persist the completed `planBodyVerification` value in convergence state. Run `okstra plan-items next-dispatch`: after the single automatic self-fix, settle eligible judgements with `resolve-dissent`; ask the user immediately for decisions outside lead authority. Preserve dissent and do not restart the automatic loop. The exact procedure and enforced authority checks are in `scripts/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md` step 8.
110
- 7. Complete the design-surface detector snapshot: `okstra design-snapshot --narrative <reportNarrativePath> --output <designPreparationPath>`, taking both paths from the run manifest. Nothing else writes that snapshot, and step 8 fails without it — `report_inputs._PLANNING_INPUT_FIELDS` lists `designPreparationPath` as a required planning input.
110
+ 7. Complete the design-surface detector snapshot: `okstra design-snapshot --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --output <designPreparationPath>`, taking both paths and the declared authoring format from that same run manifest. Nothing else writes that snapshot, and step 8 fails without it — `report_inputs._PLANNING_INPUT_FIELDS` lists `designPreparationPath` as a required planning input.
111
111
  8. Run Phase 7 report assembly.
112
112
 
113
113
  The writer never predicts steps 3–7 in its draft. The plan-body verifier reads the plan body, and report assembly adds its completed result afterward.
@@ -55,6 +55,6 @@ Load the applicable coding conventions for every language the diff will touch, t
55
55
  - **Resource selection:** use the selected frozen policy above when present. Only legacy inputs without a frozen policy use the `**Coding preflight pack:**` installed path. Read `overview.md` and `clean-code.md`, then select every matching language, framework and architecture resource for the changed files and relevant manifests. Server-side Node includes both JavaScript/TypeScript and Node-server rules. A frozen resource's absence is a blocked input, not permission to substitute live content.
56
56
  - **Project policy projection:** a `**Verification inputs:**` declaration supplies the policy and QA baseline through its named projection. Only an unfrozen legacy baseline uses `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` and its `Architecture style`, `Project Review Rule Packs` and `Project QA Commands` sections. Consume fixed text projections; do not open Okstra-owned JSON storage.
57
57
  - **Declared architecture style — an authoritative Stage 3 input.** A projected `hexagonal` selects `architectures/hexagonal.md` even without layout signals. Apply H1–H6 and the policy precedence above; declaration also makes H5's otherwise-advisory concrete-adapter item binding. A projected `layered` selects no pack resource: dependencies run from upper to lower layers, never in reverse, and variation points sit on layer boundaries; ports are not required. An explicit `none` selects no architecture overlay. Only an absent or `undeclared` style uses layout detection; an inferred hexagonal overlay retains each rule's criteria and severity, including H5's undeclared-style advisory exception. The verifier applies the same policy; an established current blocking placement violation returns `FAIL`.
58
- - **Project review rule packs:** union the policy's standing standards with exact `SKILL.md` paths cited by the task brief's `Source Material` / `Reporter Confirmations`. With a frozen policy, read their captured bodies and directly named captured `references/*.md` bodies through the verification-input projection, not live originals. A cited pack or reference missing from that capture is blocked input to report for recapture; do not omit it or substitute live content. Only unfrozen legacy inputs obtain standing standards from project-context and read those declared files and their directly named references; record an unreadable declaration as `project-review-rules: declared <path> unreadable`. Do not search parent directories or host skill catalogs. Apply those rules during implementation as a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, the executor must avoid newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, weak public names, and functions that fail the plain-English read.
59
- - **Language-agnostic principles (apply under the policy precedence above):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names that disclose caller-visible mutations and define business terms; domain-oriented query names alone are not defects when their port contract identifies the domain-owned policy; (4) cohesive responsibility, manageable complexity, consistent abstraction levels and plain-English readability. More than 50 effective lines prompts that review, not an automatic split or failure; record the reason for retaining a cohesive longer function. Self-mocking (1) — Enforced by `validators/detect_self_mock.py` (static), which the implementation **verifier** runs; it is never delegated to the executor (`_implementation-verifier.md` §"Self-mock detection"). Naming the enforcement here says who will check your diff, not that you should run the check: the executor's half is satisfying principle (1) in the code it writes, and it MUST NOT invoke the detector or write `<task_root>/qa/self-mock-*.json`. **Enforced:** that sidecar is not among the paths an executor attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so writing it closes an otherwise-passing stage as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`). The sidecar's absence BLOCKS at `validate-run.py` on the verifier's report.
58
+ - **Project review rule packs:** union the policy's standing standards with exact `SKILL.md` paths cited by the task brief's `Source Material` / `Reporter Confirmations`. With a frozen policy, read their captured bodies and directly named captured `references/*.md` bodies through the verification-input projection, not live originals. A cited pack or reference missing from that capture is blocked input to report for recapture; do not omit it or substitute live content. Only unfrozen legacy inputs obtain standing standards from project-context and read those declared files and their directly named references; record an unreadable declaration as `project-review-rules: declared <path> unreadable`. Do not search parent directories or host skill catalogs. Apply those rules during implementation as a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, inspect newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, misleading public names and mixed responsibilities under their applicable criteria. Establish the explicit project rule breach or concrete maintenance or design impact before treating a preferred alternative as a finding.
59
+ - **Language-agnostic principles (apply under the policy precedence above):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names that disclose caller-visible mutations and define business terms; domain-oriented query names alone are not defects when their port contract identifies the domain-owned policy; (4) cohesive responsibility, manageable complexity, consistent abstraction levels and comprehensible control flow. More than 50 effective lines, deep nesting or inline phases prompt inspection, not an automatic split or failure; record the concrete impact or the reason for retaining a cohesive longer function. Use focused regression and failure tests, with selective mutation checks under `clean-code.md` "Testing discipline" and explicit project requirements. Self-mocking (1) — Enforced by `validators/detect_self_mock.py` (static), which the implementation **verifier** runs; it is never delegated to the executor (`_implementation-verifier.md` §"Self-mock detection"). Naming the enforcement here says who will check your diff, not that you should run the check: the executor's half is satisfying principle (1) in the code it writes, and it MUST NOT invoke the detector or write `<task_root>/qa/self-mock-*.json`. **Enforced:** that sidecar is not among the paths an executor attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so writing it closes an otherwise-passing stage as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`). The sidecar's absence BLOCKS at `validate-run.py` on the verifier's report.
60
60
  - **Legacy graceful degradation:** if no frozen policy exists and installed resources are unreadable, apply the agnostic principles above and the project's local rules, record `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>`, and keep unavailable verification explicit. Do not degrade a readable captured policy merely because its original installation is absent. Never claim an unperformed read.
@@ -14,7 +14,7 @@ profile document.
14
14
  - For a new `implementation-planning` run, the plan-body sequence is initial verification → one planner self-fix → targeted re-verification → user gate. The initial verification is round 1, the targeted re-verification is round 2, and a second automatic self-fix is a contract violation. A user-directed correction does not consume the automatic self-fix limit, and a verification failure after that correction does not restart the automatic loop.
15
15
  - **provider-unavailable fallback (tolerance).** A worker dispatch can fail to produce a result for two distinct reasons, and both take the same recovery path. (1) **Pane budget:** the dispatch is rejected because a teammate pane could not be created — this is the harness running out of room for its own teammate panes, not okstra placing a worker. The wording is the host's, so match the condition rather than a fixed string. (2) **Sandbox CLI-start failure:** an external CLI worker wrapper exits non-zero within seconds with empty stdout and its live-log shows `operation not permitted`. In either case the lead spends the one shared retry budget through the assignment's recorded runner. If the provider is still unavailable, record that terminal status and continue only under the convergence quorum rules; never replace it silently with a fixed provider or count a substitute as the original provider's vote. Completed external-CLI workers hold no pane of their own. A pane the harness opened for its own teammate carries no id okstra recorded, so no okstra command closes it — the host and the user own that surface. (This is a prompt instruction, not a code-enforced gate.)
16
16
  - Dual-audience final-report contract (shared):
17
- - The report writer authors the report narrative Markdown. Report assembly combines it with role-owned machine inputs and publishes data.json once; the reading copy and human HTML are derived from that record.
17
+ - The report writer authors the input at the run manifest's `reportNarrativePath` using its declared `reportAuthoringFormat`: standard JSON for `json-v1`, or the existing narrative line grammar for `markdown-v1` when the field is absent. Description strings in JSON may contain ordinary Markdown. Report assembly combines it with role-owned machine inputs and publishes data.json once; the reading copy and human HTML are derived from that record.
18
18
  - User-facing information belongs in `humanSummary` and the selected task block's `userNarrative`; it must not exist only in Markdown. The HTML human main body explains the result with those fields plus task facts.
19
19
  - Agent coordination and audit details belong in `crossVerification`, `executionStatus`, and `tokenUsage`. HTML may expose them only inside collapsed audit details, never as the primary result.
20
20
  - Clarification and approval controls are rendered from the lead-owned approval decision ledger after report assembly. A question that could have been resolved before dispatch through the profile or Reporter Confirmations is an intake failure, not a final-report question.
@@ -48,6 +48,7 @@ AgentAudience = Literal[
48
48
  "report-writer",
49
49
  "code-reviewer",
50
50
  "schedule-verifier",
51
+ "interface-reviewer",
51
52
  "business-flow-investigator",
52
53
  ]
53
54
 
@@ -7,8 +7,11 @@ TypeScript 포워더가 들고 있던 USAGE 문자열이 여기로 왔다.
7
7
  from __future__ import annotations
8
8
 
9
9
  import argparse
10
+ import json
11
+ from collections.abc import Sequence
10
12
  from pathlib import Path
11
13
  import sys
14
+ from typing import TYPE_CHECKING
12
15
 
13
16
  from ..invocation import AgentInvocationError
14
17
  from ...worker_prompt_headers import WorkerPromptHeaderError
@@ -32,6 +35,9 @@ from .results import (
32
35
  _verify_completion,
33
36
  )
34
37
 
38
+ if TYPE_CHECKING:
39
+ from ...operation_invocation import OperationSlot
40
+
35
41
 
36
42
  _CLI_EPILOG = r"""Usage:
37
43
  okstra agent-prompt materialize [options] [--jobs-out <path>]
@@ -39,6 +45,7 @@ _CLI_EPILOG = r"""Usage:
39
45
  okstra agent-prompt jobs --project-root <dir> --run-manifest <path> --dispatch-kind <kind> --metadata <path> [--metadata <path>] --out <path>
40
46
  okstra agent-prompt check-corrections --project-root <dir> --run-manifest <path> --corrections <file>
41
47
  okstra agent-prompt apply-corrections --project-root <dir> --run-manifest <path> --corrections <file>
48
+ okstra agent-prompt resolve-operation --operation <id> [--count <n>] [--model <provider/model> ...] [--host-runtime <host>] [--out <path>] [--json]
42
49
  okstra agent-prompt verify [options]
43
50
  okstra agent-prompt materialize-result [options]
44
51
  okstra agent-prompt complete [options]
@@ -71,6 +78,18 @@ def _parser() -> argparse.ArgumentParser:
71
78
  "--count", type=int, default=None,
72
79
  help="slots to open, from 1 to the operation contract's count (default: the contract's count)",
73
80
  )
81
+ operation.add_argument(
82
+ "--model", action="append", default=[],
83
+ help="provider/model for one team, in team order; repeat per team (overrides operationModels)",
84
+ )
85
+ operation.add_argument(
86
+ "--host-runtime", default="",
87
+ help="also check that every slot resolves a cli-wrapper binding on this host",
88
+ )
89
+ operation.add_argument(
90
+ "--out", default="",
91
+ help="also write the JSON result to this file (the --slots input of code-review prepare)",
92
+ )
74
93
  operation.add_argument("--json", action="store_true")
75
94
  jobs = commands.add_parser("jobs", help="generate a verified jobs file without dispatching")
76
95
  _common_paths(jobs)
@@ -307,48 +326,66 @@ def _refreeze_contracts(args: argparse.Namespace) -> dict[str, object]:
307
326
  }
308
327
 
309
328
 
310
- def _resolve_operation(operation_id: str, count: int | None) -> dict[str, object]:
311
- """이 작업이 열 칸과 각 칸의 모델. 기술은 작업 이름만 알면 된다."""
329
+ def _resolve_operation(
330
+ operation_id: str, count: int | None, models: Sequence[str] = (), host_runtime: str = "",
331
+ cwd: Path | None = None,
332
+ ) -> dict[str, object]:
333
+ """The slots an operation opens and each slot's model; a skill passes only the operation name.
334
+
335
+ Model selection belongs to `resolve_operation_team()`; this function adds the
336
+ optional host binding check and the output shape.
337
+ """
312
338
  from ...model_pool import ModelPool
313
339
  from ...operation_invocation import (
314
340
  OperationPreparationError,
315
- resolve_operation_slots,
341
+ operation_contract_root,
342
+ resolve_operation_team,
343
+ slot_payload,
316
344
  )
317
- from ...paths import find_asset_root
318
345
  from ...registry.provider_registry import default_provider_registry
319
346
 
320
- root = find_asset_root(("agents", "operations"), is_present=Path.is_dir)
321
- if root is None:
322
- raise AgentPromptCliError(
323
- "operation contracts not found: no agents/operations under "
324
- "OKSTRA_HOME or this checkout"
325
- )
326
347
  try:
327
- slots = resolve_operation_slots(
328
- operation_id,
329
- contract_root=root,
330
- pool=ModelPool.from_registry(default_provider_registry()),
331
- count=count,
348
+ slots, source = resolve_operation_team(
349
+ operation_id, models, count, contract_root=operation_contract_root(),
350
+ pool=ModelPool.from_registry(default_provider_registry()), cwd=cwd or Path.cwd(),
332
351
  )
333
352
  except OperationPreparationError as exc:
334
353
  raise AgentPromptCliError(str(exc)) from exc
354
+ if host_runtime:
355
+ _check_runnable(slots, host_runtime)
335
356
  return {
336
357
  "operation": operation_id,
337
358
  "dutyId": slots[0].duty_id,
338
359
  "roleId": slots[0].role_id,
339
360
  "count": len(slots),
340
- "slots": [
341
- {
342
- "ordinal": slot.ordinal,
343
- "provider": slot.provider_id,
344
- "modelRef": slot.model_ref,
345
- "model": slot.display_name,
346
- }
347
- for slot in slots
348
- ],
361
+ "slots": [{**slot_payload(slot), "source": source} for slot in slots],
349
362
  }
350
363
 
351
364
 
365
+ def _check_runnable(slots: Sequence[OperationSlot], host_runtime: str) -> None:
366
+ """Resolve each slot's cli-wrapper binding on the host, as `code-review prepare` will."""
367
+ from ...assignment_environment import load_assignment_context
368
+ from ...assignment_resolver import AssignmentResolutionError
369
+ from ...dispatch_state import detect_terminal_backend
370
+ from ..invocation import AgentInvocationError
371
+ from ..standalone import standalone_assignment
372
+
373
+ try:
374
+ context = load_assignment_context(
375
+ host_runtime=host_runtime, terminal_backend=detect_terminal_backend(),
376
+ execution_provider_ids=tuple(slot.provider_id for slot in slots),
377
+ include_native_provider=False,
378
+ )
379
+ except ValueError as exc:
380
+ raise AgentPromptCliError(f"cannot check bindings on {host_runtime}: {exc}") from exc
381
+ for slot in slots:
382
+ try:
383
+ standalone_assignment(context=context, provider=slot.provider_id, model_role=slot.role_id,
384
+ model=slot.model_ref, requested_runner="cli-wrapper")
385
+ except (AgentInvocationError, AssignmentResolutionError, RuntimeError, ValueError) as exc:
386
+ raise AgentPromptCliError(f"{slot.model_ref} cannot run on {host_runtime}: {exc}") from exc
387
+
388
+
352
389
  def _materialize_batch_command(args: argparse.Namespace) -> int:
353
390
  payload = materialize_batch(args, _parser)
354
391
  if args.json:
@@ -380,7 +417,10 @@ def main(argv: list[str] | None = None) -> int:
380
417
  try:
381
418
  args = _parser().parse_args(argv)
382
419
  if args.command == "resolve-operation":
383
- payload = _resolve_operation(args.operation, args.count)
420
+ payload = _resolve_operation(args.operation, args.count, args.model, args.host_runtime)
421
+ if args.out:
422
+ Path(args.out).write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
423
+ encoding="utf-8")
384
424
  if args.json:
385
425
  _emit(payload, True)
386
426
  else:
@@ -393,7 +433,7 @@ def main(argv: list[str] | None = None) -> int:
393
433
  for slot in payload["slots"]:
394
434
  print(
395
435
  f" slot {slot['ordinal']}: "
396
- f"provider={slot['provider']} model={slot['modelRef']}"
436
+ f"provider={slot['provider']} model={slot['modelRef']} source={slot['source']}"
397
437
  )
398
438
  return 0
399
439
  if args.command == "jobs":