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
@@ -60,7 +60,6 @@ Load this **in addition to** [javascript-typescript.md](../languages/javascript-
60
60
  - `testcontainers` for DBs when the production DB has features (locks, full-text, JSONB, partitioning) you depend on. In-memory fakes lie about behaviour.
61
61
  - Test the error paths. Coverage of the happy path only is not coverage.
62
62
 
63
- ## Formatter / linter / tools
63
+ ## Verification
64
64
 
65
- - Same as JS / TS: `prettier`, `eslint`, `tsc`.
66
- - `npm run lint && npm test` (or the project's equivalent) must pass before any commit.
65
+ Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
@@ -41,7 +41,7 @@ Google Java Style Guide is the default. If the project ships its own (`CONTRIBUT
41
41
  - Framework: **JUnit 5** unless the project uses TestNG or JUnit 4.
42
42
  - File suffix: `*Test.java` for unit, `*IT.java` for integration.
43
43
  - Method naming: `methodUnderTest_condition_expectedResult` (e.g. `parse_emptyInput_throws`).
44
- - Use **AssertJ** or JUnit's `assertThat` for fluent assertions; avoid bare `assertTrue(a == b)`.
44
+ - Use JUnit Jupiter's `Assertions` for basic assertions, such as `assertEquals(expected, actual)` instead of `assertTrue(expected == actual)`. AssertJ and Hamcrest provide external fluent assertions; use them when the project already includes them rather than adding a dependency for this style preference.
45
45
  - One logical assertion per test. Multiple `assertThat` lines on the *same state* are fine.
46
46
  - No `Thread.sleep` in tests — use **Awaitility** for async.
47
47
  - Mock at process boundaries only (HTTP, DB, time, randomness). Do not mock value objects or DTOs.
@@ -57,8 +57,6 @@ Google Java Style Guide is the default. If the project ships its own (`CONTRIBUT
57
57
 
58
58
  What's fine: `@Mock` on collaborators injected into `@InjectMocks`, `verify(collaborator).methodCall(...)` on outcome boundaries (repository save, mailer send, gateway charge).
59
59
 
60
- ## Formatter / linter to run
60
+ ## Verification
61
61
 
62
- - `google-java-format` (preferred) or the `spotless` Gradle/Maven plugin.
63
- - `checkstyle`, `spotbugs`, `error-prone` if configured by the project.
64
- - Run before commit: `./gradlew spotlessApply check` (or the project's equivalent).
62
+ Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
@@ -29,7 +29,7 @@ Airbnb JavaScript Style Guide is the common baseline. The project's `.eslintrc(.
29
29
  ## TypeScript-specific (mandatory)
30
30
 
31
31
  - `tsconfig.json`: `"strict": true`. No exceptions. `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` are recommended.
32
- - **Never** use `any`. If a type is truly unknown, use `unknown` and narrow.
32
+ - Avoid `any` in production code. If a type is truly unknown, use `unknown` and narrow. The test-only typing exception below still applies.
33
33
  - Let inference do its job for locals. Declare explicit types at:
34
34
  - Exported function signatures (parameters **and** return type).
35
35
  - Public class members.
@@ -37,7 +37,7 @@ Airbnb JavaScript Style Guide is the common baseline. The project's `.eslintrc(.
37
37
  - Use `readonly` for arrays, properties, and parameters that must not mutate.
38
38
  - Discriminated unions over loose objects with optional flags. Use a literal `kind` / `type` field.
39
39
  - **Never re-declare an authoritative type.** When the domain or a dependency already exports the enum / union for a set of state values (`FontStatus`, `OrderState`), import it — do not hand-maintain a parallel string union or literal list. Before writing a new state type, grep the state literals *and* the intended type name for an existing declaration. A new type's name must say whose values it holds.
40
- - Type guards (`function isX(v): v is X`) over casts (`as X`). Casts are a last resort.
40
+ - Prefer type guards (`function isX(v): v is X`) over type assertions (`as X`). Allow `as const` to preserve literal and readonly types. At library or platform boundaries, use a minimal, justified assertion only when inference or narrowing cannot express an established contract. Validate untrusted input before asserting its type.
41
41
  - `interface` for object shapes that may be extended; `type` for unions / mapped / conditional types.
42
42
  - Generics: meaningful names when single letters are unclear (`TUser`, `TResult`).
43
43
  - Never disable rules inline (`// eslint-disable`, `// @ts-ignore`, `// @ts-expect-error`) without a one-line comment explaining why.
@@ -59,7 +59,7 @@ Airbnb JavaScript Style Guide is the common baseline. The project's `.eslintrc(.
59
59
  - File suffix: `*.test.ts` or `*.spec.ts`, colocated with source (`src/foo/bar.ts` → `src/foo/bar.test.ts`).
60
60
  - Structure: `describe(unit, () => { it('does X when Y', () => { ... }) })`.
61
61
  - **One behaviour per `it` block.**
62
- - Async tests: `await` every promise. Returning a promise without `await` hides assertion failures.
62
+ - Async tests: return or `await` the promise covering asynchronous work and assertions so the runner waits and observes failures. Omitting both can finish the test before assertions run.
63
63
  - Mocking: prefer dependency injection over module mocks. When you must mock, use `vi.mock` / `jest.mock` and reset between tests (`beforeEach(() => vi.clearAllMocks())`).
64
64
  - React: **React Testing Library**, not Enzyme. Query by role / label / text, not by class or test-id, unless nothing else works.
65
65
  - Snapshot tests only for stable, intentional output. Snapshots that "just changed" are noise.
@@ -86,13 +86,6 @@ expect(repository.save).toHaveBeenCalledWith(id, versionId, expectedInfos, trans
86
86
 
87
87
  When the *absence* of a property is the point, assert the exact object or that property's absence directly — a loose `expect.objectContaining` passes even when the property is present. If positional access is genuinely unavoidable, name the index once inside a test helper (`savedInfosOf(repository.save)`) so the meaning lives in one place. Detect with `rg 'mock\.calls'` over the changed test files.
88
88
 
89
- ## Formatter / linter to run
89
+ ## Verification
90
90
 
91
- - `prettier --write .` (formatting).
92
- - `eslint --fix .` (style + correctness).
93
- - `tsc --noEmit` (type check).
94
- - All three should pass before commit. CI should fail on warnings, not just errors.
95
-
96
- ## Forbidden and Prohibited
97
-
98
- - never use any type assertions (`as` or ``)
91
+ Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
@@ -62,8 +62,6 @@ Kotlin official coding conventions (kotlinlang.org/docs/coding-conventions.html)
62
62
 
63
63
  What's fine: `mockk<Collaborator>()` for injected dependencies, `coEvery {}` on those collaborators, and `verify {}` on outcome boundaries (mailer, gateway, repository write).
64
64
 
65
- ## Formatter / linter to run
65
+ ## Verification
66
66
 
67
- - **ktlint** and / or **detekt**.
68
- - `./gradlew ktlintFormat detekt` if the plugins are configured.
69
- - Run before commit.
67
+ Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
@@ -163,14 +163,9 @@ When the project is ports-and-adapters, also read [../architectures/hexagonal.md
163
163
 
164
164
  What's fine: mocking injected dependencies (`Mock(spec=UserRepository)`, `httpx.MockTransport`), asserting on return values / raised exceptions / emitted events / boundary calls.
165
165
 
166
- ## Required tooling
166
+ ## Verification
167
167
 
168
- Run before declaring a Python change complete:
169
-
170
- - `ruff check .` — lint
171
- - `ruff format --check .` — formatting (or `black --check .`)
172
- - `mypy .` or `pyright` — type check (if configured)
173
- - `pytest` — tests
168
+ Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
174
169
 
175
170
  Dependency/project management: `uv`, Poetry, or `pip-tools`. Pin dependencies in application projects; reach for the standard library before adding third-party deps, and avoid importing heavy deps at module-import time when unnecessary.
176
171
 
@@ -25,7 +25,6 @@ style_edition = "2024"
25
25
 
26
26
  - Indent: **4 spaces**.
27
27
  - Max line length: **100** (`rustfmt` default).
28
- - Always run `cargo fmt` before commit.
29
28
 
30
29
  ## Ownership & borrowing
31
30
 
@@ -95,11 +94,6 @@ Rust's trait-based DI makes self-mocking rarer than in JVM/JS, but it still happ
95
94
 
96
95
  What's fine: `mockall` mocks of injected trait dependencies (`MockHttpClient`, `MockUserRepository`), `unwrap()` in tests for setup that genuinely cannot fail, `assert_eq!` on returned values, `assert_matches!` on returned `Result` / `Option`.
97
96
 
98
- ## Required tooling
97
+ ## Verification
99
98
 
100
- Run before any commit:
101
-
102
- - `cargo fmt --all` — formatting.
103
- - `cargo clippy --all-targets --all-features -- -D warnings` — lint (warnings are errors).
104
- - `cargo check --all-targets` — fast type check.
105
- - `cargo test --all` — tests.
99
+ Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
@@ -61,8 +61,6 @@ Defaults below target PostgreSQL. MySQL-specific notes are marked.
61
61
  - Seed test data via factory functions (one per table), not raw `insert` statements copy-pasted into each test.
62
62
  - Verify performance assumptions with `explain` in CI for queries flagged as hot.
63
63
 
64
- ## Tools
64
+ ## Verification
65
65
 
66
- - Formatting: `pg_format`, `sqlfluff`, `sql-formatter`.
67
- - Linting / safety: `squawk` (Postgres migration linter — catches missing `concurrently`, locking foot-guns, etc.).
68
- - Schema diff: `migra` (Postgres), `mysqldiff` (MySQL).
66
+ Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
@@ -1,20 +1,25 @@
1
1
  # Okstra Coding Preflight
2
2
 
3
- These rules apply to every worker writing or editing project code (executor and verifiers alike). Enforcement is self-check: the agent runs each rule's check immediately before reporting "done"; skipping a check is itself a contract violation.
3
+ These criteria apply to source authors and read-only reviewers. The assignment determines which execution procedures are authorized; shared standards grant no write permissions. Apply every applicable criterion before reporting completion. Conformance remains self-check and review judgment unless a resource names an automated gate; respect its execution owner.
4
+
5
+ Resolve conflicts in this order: explicit repository instructions and declared architecture, this common resource pack, then surrounding code conventions. Cite the governing instruction when resolving a conflict. Existing code alone does not waive an explicit architecture rule.
6
+
7
+ Apply [Five simultaneous quality outcomes](clean-code.md#five-simultaneous-quality-outcomes) throughout design, implementation and review. Retain correctness, coding principles, performance, safety and security as separate acceptance conditions in existing evidence.
4
8
 
5
9
  ## Core principles
6
10
 
7
- 1. **DRY — single reference point** — One implementation per capability. A second caller signals "extract shared logic", not "duplicate path".
8
- 2. **KISS — simplest sufficient design** — Add reusable abstraction layers (helper modules, strategy/factory, configuration flags, indirection) only when current callers require them. For reuse-driven extraction, name the second caller now; otherwise inline. A local helper with one caller is appropriate when it names a distinct step in a mixed-level function or brings a body under the 50-line cap. Keep that helper local rather than introducing a reusable layer. Project-required architecture boundaries still apply. *Example violation: extracting a shared `formatUserName()` module used by exactly one call site, "in case we need it elsewhere".*
9
- 3. **YAGNI — build only for current requirements** — No speculative parameters, optional configs, "future-proof" hooks, or pre-1.0 backwards-compat shims. *Self-check: every newly introduced identifier serves a current internal use, an established external contract, a runtime entry point, or an explicit user requirement. Cite the caller, contract, registration, or requirement; a hypothetical future consumer is not evidence.* *Example violation: adding `options?: { retries?, timeout? }` parameter when the current call passes nothing.*
10
- 4. **Clean Code — names carry WHAT, comments explain WHY** — Identifiers must make intent obvious; replace comments that merely narrate executable code with clearer names. Reserve implementation comments for non-obvious WHY (hidden constraint, workaround, surprising invariant). Interface documentation may state caller-visible contracts that names and types cannot express, such as error versus mismatch results or required work for missing inputs; verify those claims against implementations and callers. Delete dead/commented-out code immediately — git history is the archive. *Example — WHAT (rename instead): `// increment counter` above `i++`. WHY (keep): `// retry up to 3x: upstream returns 502 during deploys`.*
11
- 5. **Function length cap — 50 lines** — A single function/method body must stay within 50 lines, counting only effective code (exclude blank lines, comments, and pure data declarations such as large enums, lookup tables, or constant maps). Crossing the cap is an extraction signal, not a style nit. *Self-check: for any function newly added or substantially edited, count effective body lines; if over 50, split before declaring complete, or surface the violation and confirm with the user.*
12
- 6. **Simplest conforming approach** — When choosing how to implement or fix something, pick the simplest, most direct solution path that still conforms to the project's architecture and established conventions. This is broader than KISS (#2): KISS bounds abstraction; this bounds the whole approach. Simplicity never licenses bending the structure or a convention — rule out non-conforming paths first, then take the plainest of what remains. Self-check: name the architecture/convention boundary the chosen approach respects; if a simpler path respects it too, take that one.
13
- 7. **Fix at the cause, inside the change set** — An error surfacing during your work is fixed in the code that produced it — the files you are changing and the modules they directly call. A build/deploy/test failure is NOT a license to edit configuration or manifest files (`package.json`, lockfiles, `tsconfig`, CI config, build scripts) that were already passing before this change; a regression in something previously green almost always lives in the new code, not in long-stable config. If a config/manifest edit looks unavoidable, stop and confirm with the user first — state which file, why the current code can't carry the fix, and what was passing before. *Self-check: every file edited to resolve the error is in the current change set or a module it directly calls; no previously-passing config/manifest was touched to silence the failure without the user's explicit sign-off.* *Example violation: tests fail to import a new module, so you loosen `package.json`/`tsconfig` paths instead of fixing the import in the code you just wrote.*
11
+ 1. **DRY** — Share one implementation of a capability; distinguish shared decisions from incidental similarity. See [DRY](clean-code.md#dry--dont-repeat-yourself).
12
+ 2. **KISS** — Use the simplest sufficient design. For reuse-driven layers, name the second caller or inline; a cohesive local helper may have one caller. See [KISS](clean-code.md#kiss--keep-it-simple).
13
+ 3. **YAGNI** — Cite a current caller, external contract, runtime registration or explicit requirement for each new identifier. See [YAGNI](clean-code.md#yagni--you-arent-gonna-need-it).
14
+ 4. **Clean Code** — Use truthful names and explain non-obvious constraints in comments; verify public contract documentation against implementations and callers. See [naming](clean-code.md#meaningful-naming) and [comments](clean-code.md#comments-explain-why-not-what).
15
+ 5. **Function size** — Review newly added or substantially edited functions beyond 50 effective body lines; length alone does not require a split. See [function design](clean-code.md#functions-do-one-thing) for counting and evidence.
16
+ 6. **Fix the demonstrated cause** — Establish the cause from code and observed evidence. A fix changes only necessary files, including configuration or manifests when justified, within the assignment's authority. Do not weaken code, tests, checks or configuration to hide a regression.
14
17
 
15
18
  ## Routed resource selection
16
19
 
17
- Read `clean-code.md` for the language-agnostic principles, then select language, framework, and architecture resources in three ordered stages. Each stage is a list of rules; a rule has one or more conditions; if ANY condition matches, include that rule's resource. Iterate EVERY rule in a stage — do not stop at the first match, because one change set can touch multiple languages, frameworks, or architectures. De-duplicate the final set, then state in one sentence which resources you applied (e.g., *"Applying TS + Node server + hexagonal; domain at src/domain/."*).
20
+ Read [clean-code.md](clean-code.md), then evaluate every row in the following three stages in order. Include a resource when any of its conditions matches; accumulate and de-duplicate all matches. State the applied resources and architecture boundary in one sentence.
21
+
22
+ Use the selected frozen policy when supplied; installed paths identify provenance, not replacement content. Read complete applicable sections, including qualifications and examples, using semantic section ranges rather than clipped lines. An available-resource index does not establish that selected rules were read.
18
23
 
19
24
  ### Stage 1 — Language (iterate all rules)
20
25
 
@@ -33,44 +38,26 @@ Read `clean-code.md` for the language-agnostic principles, then select language,
33
38
  |---|---|
34
39
  | [frameworks/node-server.md](frameworks/node-server.md) | `package.json` or its dependencies/scripts show server-side Node work (`express`, `fastify`, `nestjs`, server entrypoints, API routes, CLI services); or a touched file is a Node runtime module |
35
40
 
36
- Node.js server work also matches Stage 1's JavaScript/TypeScript rule — load both `languages/javascript-typescript.md` and `frameworks/node-server.md`.
41
+ For Node.js server work, load both JavaScript/TypeScript and Node server resources.
37
42
 
38
43
  ### Stage 3 — Architecture (iterate all rules)
39
44
 
45
+ Declared architecture takes precedence over layout signals. `hexagonal` selects the resource below; `layered` applies its dependency-direction invariant without selecting that resource; explicit `none` selects no architecture overlay. Only an absent or `undeclared` style uses layout detection.
46
+
40
47
  | Resource | Include when any condition matches |
41
48
  |---|---|
42
- | [architectures/hexagonal.md](architectures/hexagonal.md) | ports-and-adapters / hexagonal signals: `domain/` + `ports/` + `adapters/` (or `core/` + `infrastructure/` + `application/`), `*.port.*` files, NestJS hex split, or `abstract class` files at a domain boundary |
43
-
44
- If a layout looks hexagonal but is non-standard, ask one question — *"does this project follow ports-and-adapters? where is the domain?"* — and record the answer. Architecture overlays default to none when no rule matches.
45
-
46
- If no Stage 1 language rule matches (an unlisted language), stop and ask the user for the canonical style guide before writing code — do not invent a default.
49
+ | [architectures/hexagonal.md](architectures/hexagonal.md) | the project explicitly declares hexagonal architecture; or ports-and-adapters / hexagonal signals: `domain/` + `ports/` + `adapters/` (or `core/` + `infrastructure/` + `application/`), `*.port.*` files, NestJS hex split, or `abstract class` files at a domain boundary |
47
50
 
48
- ## Mandatory pre-write checks (every language)
51
+ For an undeclared style with a non-standard layout that looks hexagonal, ask once which architecture and domain boundary apply, and record the answer. Undeclared overlays default to none when no rule matches.
49
52
 
50
- - [ ] Language reference read for this turn.
51
- - [ ] `clean-code.md` principles applied: DRY, KISS, SOLID, YAGNI, meaningful naming (truthful + standalone + one identifier one meaning per file), single-purpose functions, plain-English summary test, 50-line cap, no magic numbers, shallow nesting, comments-explain-why.
52
- - [ ] **Mutation and state boundaries** (`clean-code.md`): decide on the direct identifier, not a status/flag proxy; capture before-state in one snapshot ahead of the mutating boundary; update only this work's owned fields on an existing row; re-read state before calling a zero-affected-rows write success or failure; put priority-between-inputs in a named domain function; keep error messages to what was observed.
53
- - [ ] **Untrusted input and security** (`clean-code.md`), for every file that reads input from outside the process or acts on its behalf: a size/count bound rejects oversized input before any check or step that grows faster than the input; input reaches SQL, shell, paths, server-side fetches, templates and regexes only through parameters, allowlists or escaping; new entry points enforce the project's operation-specific access policy, including shared, administrative, and explicitly public access where applicable; protect secrets and limit personal-data disclosure as specified in `clean-code.md`, including authorized data responses and credential issuance; no eval or unsafe deserialization of input.
54
- - [ ] Tests planned: which test(s) cover this change. New behaviour without a test is **incomplete** unless the user has explicitly opted out for this change and project rules permit it. Record the exact waived behavior or check and its unverified coverage. That waiver applies to the corresponding branch-test, branch-deletion, and resource-bound checks in this pack; it does not waive unrelated checks, weaken existing tests, or establish verified coverage.
55
- - [ ] **Function changes reuse tests first:** before changing a function, search its behavior and callers and read candidate tests. If a behavior test exists, strengthen it in place; if it already verifies the changed contract, run and retain it. Add a test only when that behavior has no existing test, preferring an existing file. Record the function, reused test location, or uncovered outcome that justifies a new test. Do not generate one test per function, helper, or branch, or expand model/provider/task-type combinations without distinct outcomes. This is checked in the completion self-check and code review, not by a test-count target.
56
- - [ ] **Existing tests surveyed (run this before planning any new test):** for every surface this change touches, `grep -rln` the candidate test files, list their test names, then READ the bodies of the ones that could overlap. A list of names does not tell you what a test asserts, and behavioural overlap does not collide on names — treat a clean name search as unfinished, not as a clear result. Record per surface: `extend <path:line>` / `new (nothing covers <behaviour>)` / `retire <path:line> (behaviour moved to <where>)`. A new test or test file with no survey line is unfinished work. The survey may change the design — moving the seam so existing tests keep passing beats adding parallel ones. Carry out a `retire` verdict in the same commit, on behavioural grounds only: the behaviour it asserted is gone, or a new test asserts it more strongly through the same seam. "Looks similar" / "touches the same file" is not grounds; without grounds the test stays, because a silent coverage loss costs more than one extra test.
57
- - [ ] **Testing discipline:** apply the recorded testing waiver only to its stated scope. For tests written or edited, the test does not stub/spy methods on the SUT itself (collaborators are fine), and assertions are on outcomes (return values, state, events, boundary calls) — not on which internal helper was called. Each unwaived branch this change adds (`catch`, guard, early return, `else`) has a test that fails when the branch body is deleted; assertions land on the last write to a record, not an intermediate one; each test title names its unit and the single condition it isolates; no effect is claimed under its own mock; shared fixtures keep their ordinary defaults; the scenarios' setup values actually differ; every new test helper/mock is used by a test in this same change; no positional mock-argument access (`rg 'mock\.calls'`).
58
- - [ ] **Third-party wrapper (when this change wraps a library call):** the wrapper adds behaviour the library does not already provide — read the installed library source before keeping a recovery branch — no comment names a condition the call site does not establish, and a rethrow keeps the original error as `cause`.
59
- - [ ] **Hexagonal overlay (if loaded):** no business logic inside any port body, adapter methods are I/O only (no post-fetch JS filtering on domain state, no `findValid*`/`findActive*` adapter names hiding rules), all domain objects declared under `domain/`, no changed domain file importing outward (ORM / framework / adapters / services), and a service dependency you add or modify goes through a port rather than a concrete adapter (advisory — record it with the port sketch; blocking when the project declares `architecture.style = hexagonal` in `.okstra/project.json` — fix before write, never record-and-pass).
60
- - [ ] **Existing code searched — by capability, not by name:** `grep` the identifier you are about to add AND the behaviour it performs (call sites, domain literals, error strings, the shape of the data it returns). A capability that already exists under a different name is the duplication this check exists to catch, and an identifier grep alone never finds it — name-level uniqueness is not evidence of absence. Record per new unit: the search terms used, the nearest existing implementation found, and the verdict `extend <path:line>` / `new (nothing covers <behaviour>)`. No survey line, no new unit.
61
- - [ ] Project conventions checked: `.editorconfig`, `CONTRIBUTING.md`, formatter config (`.prettierrc`, `rustfmt.toml`, `ktlint`, `google-java-format`, etc.). **Project rules override this resource pack on conflict.**
53
+ If no Stage 1 language rule matches (an unlisted language), stop and ask the user for the canonical style guide before writing code.
62
54
 
63
- ## Completion sweep (before declaring a multi-file change done)
55
+ ## Applying criteria within the assignment
64
56
 
65
- Per-file checks miss cross-cutting issues; each commit can be individually clean while the sum violates DRY. Before saying "done":
57
+ Read-only reviewers evaluate these standards against source and authorized execution evidence. Report violations and unavailable checks to the lead; do not repair source, run a writing formatter or perform authoring procedures. Execute only checks the assignment authorizes.
66
58
 
67
- - [ ] **Domain-literal sweep:** `grep -rn` every domain enum value / predicate you added or touched in WHERE clauses, filters, or branches. The same literal at 2+ I/O sites is a *candidate* scattered decision — ask: would these sites change together when the business rule changes? Same decision → consolidate into one named constant or query builder in the domain layer and make every site reference it. Different decisions that merely share a value → leave them separate; coupling incidental duplication is worse than the repetition. (The identifier grep above does NOT catch this — sweep *values*, not just names.)
68
- - [ ] **Stand-alone name test for exports:** for each exported identifier, look at its siblings — can a caller pick the right one from the names alone? If a comment must explain which to use, the name fails; encode the distinguishing fact in it (e.g., the input shape: `parseRows` vs `parseRowsFromFlatItems`).
69
- - [ ] **Self-mock sweep:** for every test file you added or edited, `grep` it for the SUT-stubbing patterns of this language (full list in `languages/*.md` → "Self-mock signals to refuse") — e.g. `spyOn(sut`, `sut.<method> = jest.fn`, `spyk(sut`, `Mockito.spy(`, `@Spy` paired with `@InjectMocks`, `patch(`-ing the class under test, `mockall::mock!` of the unit itself, plus private-reach hacks (`(sut as any).`, `ReflectionTestUtils.invokeMethod(sut`). Any hit where the stubbed/replaced target **is the unit under test** — not an injected collaborator — is a refused self-mock: delete the stub and exercise the real method, or the test only proves its own wiring and survives even if the real implementation is deleted. Mocking injected collaborators at the boundary stays fine; this sweep targets only stubs on the SUT itself. If a method on the SUT feels too painful to leave real, that's a design signal (extract it to a collaborator), not a license to stub it. Enforced by `validators/detect_self_mock.py` (static) — **run by the implementation verifier, never by the author of the diff.** This sweep is the manual half and ends at your own reading; the detector run and its `qa/self-mock-*.json` sidecar are the verifier's duty (`prompts/profiles/_implementation-verifier.md` §"Self-mock detection"), and it is that sidecar's absence that BLOCKS at `validate-run.py` — on the verifier's report, not on your diff. Running the detector yourself does not pre-satisfy the gate: the sidecar is outside an executor attempt's `writePolicy.artifactPolicy.allowedPaths`, so writing it makes okstra's write audit close the attempt as `error` (`artifact-root change exceeds batch policy union`), and the verifier writes the same file again under its own duty.
70
- - [ ] **No documented forks:** two deliberate variants of one capability must not survive as parallel implementations with a comment explaining the delta. Re-read both bodies and check the deltas are genuinely parametric: if they reduce to a few orthogonal options, collapse into one implementation taking explicit option parameters that encode them. If encoding the delta would take more than ~3 options, or add more branching than the duplication it removes, they are two capabilities — keep two implementations with distinct honest names and delete the "variant of" framing. Either way the comment-documented fork dies. "The divergence is documented" stays a refused rationalization, and a two-capabilities verdict must come from reading the bodies, not from reluctance to refactor.
59
+ Workers authorized to change source also read [authoring-checks.md](authoring-checks.md) before editing. For a frozen policy, select that resource from its archive with `--resource authoring-checks.md`. Older captures may retain those procedures in this overview; use their captured text without substituting installed files.
71
60
 
72
- ## Boundaries
61
+ ## Verification commands
73
62
 
74
- - This preflight does **not** auto-format. Run the project's formatter yourself.
75
- - This preflight does **not** replace repo-local rules. Repo rules win on conflict.
76
- - This preflight does **not** cover every language. If the target language is missing, stop and ask.
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).
@@ -0,0 +1,30 @@
1
+ {
2
+ "schemaVersion": "1.0",
3
+ "blockingSeverities": ["must-fix", "should-fix"],
4
+ "blockingTiming": "now",
5
+ "gradingReference": "clean-code.md#Finding evidence and grading",
6
+ "rules": {
7
+ "S1": ["structural", "clean-code.md#DRY — Don't Repeat Yourself"],
8
+ "S2": ["structural", "clean-code.md#KISS — Keep It Simple"],
9
+ "S3": ["structural", "clean-code.md#SOLID"],
10
+ "S4": ["structural", "clean-code.md#YAGNI — You Aren't Gonna Need It"],
11
+ "S5": ["structural", "architectures/hexagonal.md#Rule H1"],
12
+ "S6": ["structural", "architectures/hexagonal.md#Rule H2"],
13
+ "S7": ["structural", "architectures/hexagonal.md#Rule H3"],
14
+ "S8": ["structural", "architectures/hexagonal.md#Rule H4"],
15
+ "S9": ["structural", "architectures/hexagonal.md#Rule H5"],
16
+ "S10": ["structural", "architectures/hexagonal.md#Rule H6"],
17
+ "M1": ["semantic", "clean-code.md#Meaningful naming"],
18
+ "M2": ["semantic", "clean-code.md#Functions do one thing"],
19
+ "M3": ["semantic", "clean-code.md#Comments explain *why*, not *what*"],
20
+ "T1": ["state-and-tests", "clean-code.md#Mutation and state boundaries"],
21
+ "T2": ["state-and-tests", "clean-code.md#No self-mocking"],
22
+ "T3": ["state-and-tests", "clean-code.md#Behavioral, not implementation tests"],
23
+ "T4": ["state-and-tests", "clean-code.md#Test data must actually separate the paths"],
24
+ "G1": ["general", "clean-code.md#Trace what this change can do wrong"],
25
+ "G2": ["general", "clean-code.md#Wrapping a third-party call"],
26
+ "G3": ["general", "clean-code.md#Untrusted input and security"],
27
+ "G4": ["general", "clean-code.md#Resource bounds need their own regression test"],
28
+ "G5": ["general", "overview.md#Routed resource selection"]
29
+ }
30
+ }
@@ -3,39 +3,36 @@
3
3
  "id": "code-reviewer",
4
4
  "roleId": "verifier",
5
5
  "responsibilities": [
6
- "Return an evidence-backed verdict for every assigned review census cell, acting as a correctness, maintainability and documented-convention gate, and without changing the census or the code under review."
6
+ "Judge every assigned census cell against the frozen policy, acceptance conditions and five quality outcomes."
7
7
  ],
8
8
  "requiredConduct": [
9
- "On follow-up reviews, inspect the correction delta and its impact closure. Treat carry candidates as proposals: independently search affected callers, callees, contracts and tests before attesting inheritance from this slot's verified prior verdicts. Reopen candidates for newly discovered effects or evidence of a real defect; fall back to full inspection when the boundary is uncertain. Account for this slot's full assigned census and distinguish inspected from inherited cells.",
10
- "Inspect every assigned cell's actual diff and full context: whole target files, enclosing definitions, affected callers and callees, contracts, outcome consumers and related tests at the frozen head. Follow transitive effects as needed. An assigned specialty limits verdict ownership, not context reads. Route suspected issues outside the assignment to the lead without changing the census. Preserve the cell identifier and return concrete findings or an evidence-backed clean verdict.",
11
- "Use the lead's shared test execution evidence, checking its head and inputs. Review test assertions, failure and boundary cases and self-mocking where assigned. Distinguish inspected tests from executed tests, report missing or failed verification, and ask the lead for any additional necessary execution rather than launching duplicate suites or editing code.",
12
- "Return one compact Coverage Verdicts table row per assigned target/group cell. Explicitly account for every shared-catalog rule ID under Checked, N/A with an inline applicability reason, or Findings with finding IDs. Share one literal inspected target-source path:line per row. Do not expand pack bullets into separate verdict rows, use all-checked claims, or mark unread rules checked.",
13
- "Inspect before accounting: evaluate changed constructs against every applicable canonical clause, follow result mappings and the work done by existing callees, and identify findings before compressing the coverage table. Passing tests and linters do not establish conformance to every assigned rule."
9
+ "Read the frozen diff, whole target files and affected callers, callees, contracts and tests before producing verdicts. Specialty limits verdict ownership, not context reads. Read complete applicable rule clauses; do not clip their text or replace frozen policy with installed files.",
10
+ "Use shared execution evidence only when its head and inputs match. Inspect assertions, failure and boundary cases and self-mocking where assigned. Ask the lead for necessary additional execution; do not launch duplicate suites.",
11
+ "On follow-ups, inspect the selected correction range and its impact before accepting this slot's carry candidates under a matching comparison base and policy. Supporting context outside the supplied census creates no independent targets; full inspection means that census. Reopen contradicted conclusions, distinguish inspected from inherited cells, retain earlier finding dispositions separately, and use full inspection when the boundary is uncertain."
14
12
  ],
15
13
  "decisionPrinciples": [
16
- "Report only actionable defects with a demonstrated consequence. Calibrate priority from impact and likelihood, distinguish correctness from preference, avoid duplicate findings across cells, and recommend the smallest fix that addresses the established problem.",
17
- "Distinguish personal preference from an explicit repository or routed-pack convention. A concrete violation of a documented convention can be a nit even when runtime behavior is correct. Trace shared decision functions before claiming that repeated orchestration duplicates a business rule."
14
+ "Use demonstrated impact and likelihood to grade actionable findings. Follow documented policy rather than preference, trace shared decisions before claiming duplication, and recommend the smallest correction.",
15
+ "Passing tests, valid output accounting and correct current outputs do not establish all five quality outcomes or excuse an applicable design violation."
18
16
  ],
19
17
  "authorityAndBoundaries": [
20
- "Review only the provided census and fixed comparison range. Do not add, merge, split, omit, or reinterpret cells; do not edit source, broaden the diff, or redesign unrelated code."
18
+ "Keep census membership, rule ownership and the frozen comparison range unchanged. Do not broaden the diff or redesign unrelated code."
21
19
  ],
22
20
  "evidenceStandards": [
23
- "Each finding must identify its cell, exact code evidence, violated behavior or project standard, consequence, and feasible correction. A clean verdict must name what was inspected and why no actionable issue was found.",
24
- "Classify each finding as execution-error or design-violation. An execution error establishes a reachable failure and wrong result. A design violation identifies the applicable assigned rule, code evidence, and concrete design or maintenance impact; it does not require a runtime failure. Both kinds include a feasible fix; preference alone is insufficient.",
25
- "For checked G2, G3 and G5 rules in general cells, the Evidence field includes source-cited clean observations after ::, keyed by rule ID. G2 traces dependency outcome meanings through diagnostic values; G3 identifies workload dimensions, downstream work and limits before that work; G5 names the applicable canonical clauses and observed conformance. Missing or unsupported inspection stays unaccounted instead of clean."
21
+ "Each finding identifies its cell, source evidence, assigned rule or behavior, consequence and feasible correction. An execution-error establishes a reachable state, expected outcome and wrong result. A design-violation establishes an applicable rule and concrete design impact without requiring a runtime failure.",
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."
26
23
  ],
27
24
  "collaborationContract": [
28
- "The spawning coordinator divides the received full census and delivers each subset to its responsible child. Each child investigates that assignment and returns explicit coverage and findings. The coordinator compares all responses with both the child assignments and the full census, sends omissions back to the same logical child with its prior results, and repeats until nothing remains unaccounted for. Only then return the consolidated model report; blocked or incomplete coverage is never a completed review.",
29
- "Honor the assigned coordinator or specialty role without recursive delegation. A model-team coordinator owns the full census, itself spawns the six same-provider/model specialty subagents, collects and verifies their completions, requests their gap-fills, and consolidates their rule statuses and findings with child provenance before returning its model report. Do not transfer child spawning or consolidation to the orchestrator. Correct any aggregation discrepancy in the spawning coordinator's report. A specialty subagent inspects only its assigned rule subset and does not spawn further reviewers. Preserve independence between model teams; never borrow another team's verdict to fill a gap.",
30
- "Keep verdicts independent from other reviewers and the author. Do not echo a finding without verifying it, suppress a unique defect for consistency, or resolve cross-cell overlap by changing identifiers; return overlap information to the lead."
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
+ "Return out-of-assignment evidence and aggregation conflicts to their owner without changing cell identities or borrowing another team's verdicts."
31
27
  ],
32
28
  "completionCriteria": [
33
- "Every grouped cell accounts for all expected shared-catalog rule IDs exactly once, all findings are prioritized and evidenced, and blocked or unaccounted rules identify what prevents evaluation. Preserve the census IDs; do not silently infer clean verdicts from missing rule IDs."
29
+ "Return one grouped Coverage Verdicts row per assigned cell. Account for each expected rule exactly once under Checked, reasoned N/A or Findings, with the required target-source anchor and finding links. Preserve identifiers; no omitted rule is implicitly clean.",
30
+ "Report incomplete or blocked quality checks explicitly. Complete accounting authenticates the response shape, not the truth of its conclusions."
34
31
  ],
35
32
  "prohibitions": [
36
- "Do not reinterpret, merge, omit, or add census cells; report speculative concerns as defects; use style preference as a blocking standard; edit the reviewed code; or claim a cell clean without inspecting its assigned evidence."
33
+ "Do not mark unread criteria checked or classify unsupported candidates as findings."
37
34
  ],
38
35
  "blockedStateReporting": [
39
- "Identify each unevaluable cell, the missing source, diff, runtime evidence, or governing standard, the inspection attempted, and the review conclusion that remains unavailable."
36
+ "Name each unevaluable cell, the missing source, policy, bound or execution evidence, the inspection attempted and the conclusion that remains unavailable."
40
37
  ]
41
38
  }
@@ -21,6 +21,7 @@
21
21
  "Maintain a fresh context from the execution session, and weigh the diff rather than the confidence of the narrative describing it. Do not ask the executor to supply the verdict, silently repair its work, or coordinate a passing conclusion; return actionable findings to the lead with enough evidence for a bounded correction."
22
22
  ],
23
23
  "completionCriteria": [
24
+ "When Frozen Design Review is supplied, independently return every cell/rule verdict and structured finding against its exact base, head, policy and census fingerprints; missing accounting prevents acceptance. This is checked by design-review evidence validation, not by another worker's response.",
24
25
  "Every assigned criterion and required check has an explicit pass, fail, or blocked disposition; material regressions and test-quality risks have been examined; and the overall verdict follows from the recorded evidence."
25
26
  ],
26
27
  "prohibitions": [
@@ -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