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
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: okstra-explain-flow
3
- description: Explain a product business flow across related projects, including inbound and outbound dependencies, business rules, states, errors, before/after changes, risks and side effects. Query or retry shared business explanations independently of okstra-run.
3
+ description: Use when the user asks how a product business flow works across related projects, or wants to query or retry a stored business explanation; no okstra task is required. Explains a product business flow across related projects, including inbound and outbound dependencies, business rules, states, errors, before/after changes, risks and side effects. Query or retry shared business explanations independently of okstra-run.
4
4
  ---
5
5
 
6
6
  # Explain a Business Flow
@@ -13,7 +13,11 @@ Run the shared runtime from the project:
13
13
  okstra explain-flow --question "<the user's business question>" --report-language <reader language> --host-runtime <current host runtime>
14
14
  ```
15
15
 
16
- Use `claude-code`, `codex`, or the configured external host identifier. The runtime owns operation/model resolution, auditable invocation preparation, provider execution, source snapshots, validated result publication, shared knowledge and reports. Do not dispatch an unaudited replacement investigator or rerun an entire task when only an explanation failed.
16
+ <!-- BEGIN FRAGMENT: host-runtime-selection -->
17
+ Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present; otherwise use the registered host ID declared by the current harness. Do not infer the host from worker models, installed executables, or `PATH`. If neither source identifies the host, report that it is unknown instead of substituting another host. Keep the same resolved host when retrying against another project directory.
18
+ <!-- END FRAGMENT: host-runtime-selection -->
19
+
20
+ The runtime owns operation/model resolution, auditable invocation preparation, provider execution, source snapshots, validated result publication, shared knowledge and reports. Do not dispatch an unaudited replacement investigator or rerun an entire task when only an explanation failed.
17
21
 
18
22
  For relevant stored knowledge:
19
23
 
@@ -45,13 +45,37 @@ okstra manager remove project --manager-id <manager-id> --project-id <project-id
45
45
  okstra manager remove task --manager-id <manager-id> --task-group <task-group> --task-id <task-id> [--confirm]
46
46
  okstra manager remove task-group --manager-id <manager-id> --task-group <task-group> [--confirm]
47
47
  okstra manager view --manager-id <manager-id>
48
+ okstra manager journal add --manager-id <manager-id> --kind <decision|finding|followup|session-summary> --body-file <path> [--task-group <task-group> --task-id <task-id>] [--resolves <entry-id>]
49
+ okstra manager resume --manager-id <manager-id> [--recent <n>]
50
+ okstra manager log --manager-id <manager-id> [--task-group <task-group> --task-id <task-id>] [--kind <name>] [--since <ISO>] [--grep <text>] [--open-followups] [--limit <n>]
48
51
  ```
49
52
 
53
+ `log` is read-only. It shows the CLI-recorded manager and task events, the `task note` directives and the journal entries, newest first, as numbered entries with their origin and kind, and lists damaged log lines under `damaged`. `--open-followups` keeps only followups that no entry has resolved. `resume` is read-only and prints the last session summary, the number of entries after it (`Unsummarized activity`), open followups, recent decisions, the most recent entries and each task's sync state; a task whose files cannot be read shows its error and the rest is still printed.
54
+
50
55
  - Public child task identity is `project-id:task-group:task-id`.
51
56
  - `--task` on `new task` is optional and repeatable; without it the task is created with no children.
52
57
  - `okstra manager new task --task ...` should prefer the full child key form above. The CLI also accepts shorthand under the command's `--task-group`, but the full key is the public form to show users.
53
58
  - When a manager task id differs from the actual child task id for a specific project, pass `--child-task-id <child-task-id>` to `task assign` and `task run`.
54
59
 
60
+ ## Session Start
61
+
62
+ When the user names the manager id, run `okstra manager resume --manager-id <manager-id>` before any other manager command. Tell the user the last session summary (or that there is none), the `Unsummarized activity` line when it is not `none`, and the open followups with their entry ids.
63
+
64
+ ## Recording Decisions
65
+
66
+ `task note` reaches the child task: `task run` copies its directives into the child context. `journal add` is manager-only: no child task reads it. Choose by audience.
67
+
68
+ - A direction, scope or priority the user decided: `--kind decision`.
69
+ - A fact confirmed by investigation: `--kind finding`.
70
+ - Work deferred to later: `--kind followup`. When a later entry settles it, pass that followup's id with `--resolves <entry-id>`.
71
+ - Pass `--task-group` and `--task-id` when the entry is about one manager task.
72
+
73
+ Show the user the body before writing it. Write the body with the Write tool to a scratch path outside the project roots and pass that path as `--body-file <path>`; do not put conversation or ticket text on the command line. `--body <text>` is only for a short literal you typed yourself with no quotes, backticks or `$`. Do not repeat in the journal what a state-changing command already recorded (assignments, splits, syncs, removals): `log` shows those. A refused entry (empty, over 4,000 characters, a likely secret, an unknown task, or an invalid `--resolves`) writes nothing; fix the input instead of retrying the same text.
74
+
75
+ ## Session End
76
+
77
+ When the user ends the session or a batch of work is finished, write one `--kind session-summary` entry with what was done, what was decided and what is left. The next `resume` counts activity from this entry.
78
+
55
79
  ## Removal Rule
56
80
 
57
81
  Successful native state changes also register that manager's saved sources in
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: okstra-memory
3
- description: Use when the user wants to preserve, remember, store, recall, search, or archive AI/human conversation notes in okstra's global Memory Book. Trigger words include "organize and store this in okstra", "memory-book", "remember this for me", "save the conversation", "summarize and save", "remember this", "store this conversation", "save this decision", "search the memory-book", "find the note I saved", "recall a saved decision".
3
+ description: Use when the user asks, in any language, to save, remember, recall, search, list or archive conversation notes, decisions or preferences in okstra's global Memory Book (memory-book). Not for project task artifacts.
4
4
  ---
5
5
 
6
6
  # okstra-memory
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: okstra-pr-gen
3
- description: Use when the user wants to register a PR body template or generate a PR description from a branch diff using a stored (or default) template. Manages templates under ~/.okstra/template/pr and drives okstra pr {template,branches,gen}. Trigger words include "okstra pr", "register PR template", "generate PR body", "generate PR message", "generate PR", "pr gen", and "register template".
3
+ description: Use when the user wants to register a PR body template or generate a PR description from a branch diff using a stored (or default) template. Manages templates under ~/.okstra/template/pr and drives okstra pr {template,branches,gen}.
4
4
  ---
5
5
 
6
6
  # okstra-pr-gen
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: okstra-run
3
- description: Use when the user wants to start or continue an okstra cross-verification task in this session, or configure its saved worker roles, models, and counts. Includes "okstra run", "run the next phase", and "okstra-run worker settings".
3
+ description: Use when the user wants to start or continue an okstra cross-verification task in this session, or configure its saved worker roles, models, and counts. Also routes single-agent implementation records and read-only task history, search and related-work requests. Includes "okstra run", "run the next phase", and "okstra-run worker settings".
4
4
  ---
5
5
 
6
6
  # OKSTRA Run (in-session)
@@ -19,6 +19,32 @@ Launch an okstra task — gather inputs interactively via the **wizard state mac
19
19
  - Continue an existing task (next phase) without leaving the current agent session.
20
20
  - Configure global worker defaults or project overrides without starting a task.
21
21
 
22
+ ## Implementation records and task discovery
23
+
24
+ Before initializing the wizard, route an explicit single-agent implementation
25
+ request to the installed `okstra-tdd` skill with the project root and any
26
+ known task key. That skill owns its ten-step implementation record; the wizard
27
+ continues to own cross-verification execution.
28
+
29
+ For history or search requests, use `okstra task-list --query "<terms>" --json`
30
+ in the target project. For related work, use
31
+ `okstra task-list --related-to <full-task-key> --json`; combine `--query` when
32
+ requested. Completed tasks are included. Inspect a selected result with
33
+ `okstra task-show <full-task-key>`. Present snippets and source paths;
34
+ distinguish explicit links from shared tags, files or references. Follow
35
+ `nextCursor` with `--after <cursor>` until the requested result limit or the end.
36
+ Report `unavailable` sources and `truncated` results as incomplete coverage.
37
+ Reading history does not resume a trace or start a new attempt.
38
+
39
+ When a known task is requested for continuation, inspect `task-show` before
40
+ wizard initialization. During the task picker, inspect an existing selected key
41
+ before submitting that answer to `wizard step`. If the task has
42
+ `executionKind: "implementation-trace"` and the user has not explicitly asked
43
+ for cross-verification, delegate to `okstra-tdd` with its
44
+ `implementationTracePath` and full key, then stop this wizard flow. Explicit
45
+ cross-verification requests continue through the ordinary wizard. This routing
46
+ is an agent instruction; the wizard does not enforce it.
47
+
22
48
  ## Worker settings mode
23
49
 
24
50
  When the user asks to configure saved worker roles, models, or counts, enter settings mode before the task-launch preflight. The wizard owns the scope, role editor, review, save, and cancel flow. Use `okstra wizard` rather than editing the configuration files directly.
@@ -40,8 +66,7 @@ For settings, `kind: done` means the settings transaction finished: show `next.l
40
66
  ## When NOT to Use
41
67
 
42
68
  - User explicitly asks to spawn a new terminal / new agent session — instruct them to run `okstra` in another terminal.
43
- - User wants status only — use `okstra task-show <task-key>`.
44
- - User wants past runs — use the task timeline.
69
+ - User wants status or history only — use the task discovery commands above; do not start the wizard.
45
70
 
46
71
  <!-- BEGIN FRAGMENT: wizard-relay-protocol -->
47
72
  ## How the wizard talks to you
@@ -81,7 +106,7 @@ Submit the answer shape required by `interaction.answerProtocol`; do not add nor
81
106
 
82
107
  The final `confirm` step is a normal `pick` step with three options — `Proceed` / `Edit` / `Abort`(abort) — and is rendered the same way (no special handling). `Edit` rewinds to any earlier step (including `base-ref`); `Abort` terminally cancels the wizard. The branch/worktree decision the run will actually use (for `implementation`, the **stage worktree** — not the task-key directory) is folded into the Step 4 confirmation summary block as a `worktree` line, so there is no separate branch-confirm prompt.
83
108
 
84
- Never invent additional questions. **Never drop, hide, merge, reorder, or truncate** a `pick` / `pick_group` option — relay every `options[]` entry, including the flagged recommendation. Do not collapse a multi-option pick into a "recommended + Enter directly / Other" shortlist. The wizard's arrays are the complete authoritative choice sets, regardless of the current host UI's usual option limit. The run-prompt recommendation rule (1–2 recommendations + Enter directly) shapes the **option set** only for prompts this skill authors itself, never for wizard-provided options — you may not add, drop, or reorder a wizard option to produce a shortlist. It does not excuse you from recommending: before relaying a wizard step whose answer turns on something readable (the carried report, the sidecar the user already wrote, the prior Stage Map), read it, put what you found in the question body, and name which of the wizard's own options you recommend and why. Relaying a step with no context and no recommendation hands the whole question back to the user — see the lifecycle core contract "Asking the user (BLOCKING)".
109
+ Never invent additional questions. Relay every `pick` / `pick_group` option the wizard sends, in order, including the flagged recommendation: the wizard's arrays are the complete choice set whatever the host UI's usual option limit, and the run-prompt recommendation rule (1–2 recommendations + Enter directly) applies only to prompts this skill authors itself. It does not excuse you from recommending: before relaying a wizard step whose answer turns on something readable (the carried report, the sidecar the user already wrote, the prior Stage Map), read it, put what you found in the question body, and name which of the wizard's own options you recommend and why. Relaying a step with no context and no recommendation hands the whole question back to the user — see the lifecycle core contract "Asking the user (BLOCKING)".
85
110
 
86
111
  **One recommendation, shown in one place, and it is option 1.** Wizard labels carry no recommendation marker of their own. The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — except on model-selection steps (`role-models:*`, `role-model:*`), which keep provider display order, so the flagged model may sit anywhere in the list. Append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option, whose recommendation is not placed first on a single-select step or is not the leading run on a checkbox step (both position checks are skipped on `role-models:*` / `role-model:*` steps), or that marks the free-input / abort escape as a recommendation.
87
112
  <!-- END FRAGMENT: wizard-relay-protocol -->
@@ -101,7 +126,7 @@ Run one shell-command tool call (Shell invocation rule from the top of this file
101
126
  okstra preflight --runtime <host-runtime>
102
127
  ```
103
128
 
104
- Read the fixed text lines. If the first line is `Okstra preflight: failed`, show `Runtime readiness` and every repeated `Readiness check`, `Readiness check status`, and `Readiness check action`, then stop before Step 2. Show `Reason` and `Recovery` for every failure. Do not relabel a host login, license, daemon, trust, or other readiness failure as missing Okstra setup. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary). Do **not** try to invoke `npx -y okstra@latest ...` as a fallback — `npx` is not on the literal-token allow-list and will force a confirmation prompt on every wizard call afterward. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so never `export PYTHONPATH=...`.
129
+ Read the fixed text lines. If the first line is `Okstra preflight: failed`, show `Runtime readiness` and every repeated `Readiness check`, `Readiness check status`, and `Readiness check action`, then stop before Step 2. Show `Reason` and `Recovery` for every failure. Do not relabel a host login, license, daemon, trust, or other readiness failure as missing Okstra setup. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary). Do **not** try to invoke `npx -y okstra@latest ...` as a fallback — every later wizard call still invokes the stale `okstra` on PATH, so an `npx` call does not recover the run. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so never `export PYTHONPATH=...`.
105
130
 
106
131
  On `Okstra preflight: ready`, require `Runtime readiness: ready` before Step 2. These checks come from the selected host adapter and are independent of worker-provider choices. Any other readiness value is unrecognized runtime output: show it and stop before Step 2 instead of guessing that the host is ready.
107
132
 
@@ -176,7 +201,7 @@ This prints one absolute path on stdout (e.g. `/var/folders/.../okstra-wizard.Ab
176
201
 
177
202
  Then initialize the wizard with the literal `projectRoot` / `projectId` you parsed from Step 1 and the literal state-file path from above.
178
203
 
179
- For task continuity, pass `--preferred-task-key <project-id:task-group:task-id>` on every initialization when this conversation has a known task. Use the task explicitly requested in the current message first; otherwise use the last task the user selected in this conversation's wizard. Resolve abbreviated task IDs against the project catalog before passing the full key. If the ID is ambiguous, ask which matching task the user means. Never infer this conversation's selection from project-wide `latest-task.json`, catalog recency, or another session. With neither an explicit task nor a prior selection in this conversation, omit the flag. The runtime puts the preferred task first, including a completed task when explicitly carried in, and rejects a key absent from the catalog instead of substituting another task; ordering is covered by the former Python suite; that regression check is now retired. The task picker still lets the user change tasks.
204
+ For task continuity, pass `--preferred-task-key <project-id:task-group:task-id>` on every initialization when this conversation has a known task. Use the task explicitly requested in the current message first; otherwise use the last task the user selected in this conversation's wizard. Resolve abbreviated task IDs against the project catalog before passing the full key. If the ID is ambiguous, ask which matching task the user means. Never infer this conversation's selection from project-wide `latest-task.json`, catalog recency, or another session. With neither an explicit task nor a prior selection in this conversation, omit the flag. The runtime puts the preferred task first, including a completed task when explicitly carried in, and rejects a key absent from the catalog instead of substituting another task. **Not enforced:** no test covers this ordering. The task picker still lets the user change tasks.
180
205
 
181
206
  After a successful task selection, retain the returned full task key in this conversation as its task context, including in continuation summaries, and carry it into the next initialization. A different selection replaces it. Selecting a brand-new task clears the previous selection; retain the new full key once its project, group, and task ID are resolved. This conversation carry-forward is a lead instruction, not automatic host-session discovery by the runtime.
182
207
 
@@ -210,15 +235,13 @@ Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How
210
235
  ```
211
236
  If the answer contains spaces or shell metacharacters, wrap it in double quotes around the literal string only — never inside `"$VAR"`.
212
237
 
213
- **MANDATORY: empty answers must pass `--answer ""` explicitly.** If the user's reply is the empty string, the call MUST still include the flag with an empty literal value:
238
+ Pass `--answer` even when the user's reply is empty:
214
239
  ```bash
215
240
  okstra wizard step --state-file /var/folders/.../okstra-wizard.AbCd.json --answer ""
216
241
  ```
217
- Omitting `--answer` entirely is forbidden. The wizard does not read a missing `--answer` flag as "submit empty": without `--answer` or `--no-submit`, `wizard step` returns `ok: false` naming `--answer` and exits 2, and the step is not submitted. Submitting `--answer ""` is the only way to advance past an intentionally-blank step (e.g. "use phase default").
218
-
219
- **Escaping rule**: if the literal answer contains `"`, escape each occurrence as `\"` inside the double-quoted argument. Empty values must still be `--answer ""` — the flag itself is mandatory, even when the value is empty.
242
+ Without `--answer` or `--no-submit`, `wizard step` returns `ok: false` naming `--answer`, exits 2 and submits nothing, so `--answer ""` is the only way past an intentionally blank step (e.g. "use phase default"). If the literal answer contains `"`, escape each occurrence as `\"` inside the double-quoted argument.
220
243
 
221
- **Enforced:** `tests-js/wizard.test.mjs` pins `parseFlags` on the empty literal (`--answer=` parses to the empty string, a value beginning with `--` is kept) and on the `--no-submit` peek that is the only sanctioned way to see the current prompt without submitting; the Node wrapper (`src/commands/execute/wizard.mts`) is what forwards them to Python.
244
+ **Not enforced:** no test pins the empty-literal parsing or the `--no-submit` peek; the Node wrapper (`src/commands/execute/wizard.mts`) forwards both flags to Python.
222
245
  3. **Handle result**:
223
246
  - `ok: true` → echo `result.echo` to the user on one short line, then loop with `result.next`.
224
247
  - `ok: false` → show `result.error` to the user verbatim, then loop with `result.current` (re-prompt the same step). If `result.current` is `null`, do not loop — the current step cannot render (e.g. corrupt Stage Map); surface the error and stop so the user fixes the plan.
@@ -257,7 +280,7 @@ Do not second-guess the wizard. If the next prompt seems out of place, the bug i
257
280
  <!-- BEGIN FRAGMENT: wizard-confirm-step -->
258
281
  ## Step 4: The confirm step's question text is the selection summary
259
282
 
260
- When `next.step == "confirm"`, the prompt's `label` already carries the full selection summary (`선택 확인:` followed by one line per resolved input — task-type, task-key, brief, base-ref, worktree, every role slot, directive, related-tasks, clarification, stage, …) and ends with the question. Render that `label` **verbatim, every line, as the question text** of the `confirm` picker (Proceed / Edit / Abort) — the same way you render any other pick step's label. Do not re-author it as a table, do not summarise it into prose, do not drop a line because its value is `(none)`: the user confirms what is on screen, and a line you left out is a setting they never saw (observed: a lead's own table omitted `directive`, `base-ref` and `brief`). Render the picker **as the final output of that turn** — emit nothing after the picker call.
283
+ When `next.step == "confirm"`, the prompt's `label` already carries the full selection summary (`선택 확인:` followed by one line per resolved input — task-type, task-key, brief, base-ref, worktree, every role slot, directive, related-tasks, clarification, stage, …) and ends with the question. Render that `label` **verbatim, every line, as the question text** of the `confirm` picker (Proceed / Edit / Abort) — the same way you render any other pick step's label. Do not re-author it as a table, do not summarise it into prose, do not drop a line because its value is `(none)`: the user confirms what is on screen, and a line you left out is a setting they never saw. Render the picker **as the final output of that turn** — emit nothing after the picker call.
261
284
 
262
285
  `okstra wizard confirmation --state-file <path>` returns the same block as `{ok: true, text: ...}` for a text-only host or when the user asks to see the summary again; it is not a substitute for the label.
263
286
 
@@ -273,51 +296,35 @@ When `next.kind == "done"`, fetch the public wizard outcome:
273
296
  okstra wizard outcome --state-file /var/folders/.../okstra-wizard.AbCd.json
274
297
  ```
275
298
 
276
- Output: `{ok: true, outcome: {renderArgv: ["--lead-runtime", "...", ...], renderArgs: {...}, orchestration: {chainStages: "..."}, persistActions: [...], confirmationText: "..."}}`.
299
+ Output: `{ok: true, outcome: {renderArgv: ["--lead-runtime", "...", ...], renderArgs: {...}, orchestration: {chainStages: "...", hostRulesPath: "..."}, persistActions: [...], confirmationText: "..."}}`.
277
300
 
278
- `renderArgv` is the canonical ordered `okstra render-bundle` argument list. Pass its tokens verbatim and in order. Repeated `--role-count` and `--role-model` flags are intentional. `renderArgs` is a compatibility and inspection view only; do not reconstruct an invocation from it. `orchestration` holds signals this skill acts on itself — never pass its entries to `render-bundle`.
301
+ Use the outcome to inspect the confirmed scope and `orchestration.chainStages`. `renderArgv` and `renderArgs` remain compatibility and inspection views; do not copy their tokens into a command. Bundle preparation reads the confirmed state file directly and preserves empty values and repeated role/model flags in code. `orchestration` holds signals this skill acts on itself — never pass its entries to `render-bundle`.
279
302
 
280
- `userAuthorization`, when present, preserves the confirmation prompt actually emitted by this wizard and the relayed `proceed` response. Its `--user-authorization-json` token carries that record into the run manifest; preserve it unchanged. Do not synthesize a receipt for older confirmed states. The record documents task scope; it does not grant host execution privileges.
303
+ Before the first `render-bundle` invocation, read `outcome.orchestration.hostRulesPath` verbatim when it is non-empty. The wizard selects and checks this absolute runtime path; it contains the selected task's waiver, recovery, and chaining rules needed even when preparation fails. An empty string means this task declares no host rules. Use the emitted path rather than constructing one from the task type.
281
304
 
282
- Before retrying a worker in an existing run, inspect its last invocation attempt: await running work; append an attempt only after `failed-no-mutation` within the retry budget. Preserve every other terminal attempt. `okstra team dispatch` routes the legacy declaration-only implementer failure to a separate same-model evidence-recovery invocation; collect its result before independent verification. Other terminal failures need `okstra agent-prompt materialize` with a new `--invocation-id`, distinct `--prompt`/`--result` paths, and unchanged assignment/model for a bounded correction. Do not restart completed implementation or request renewed approval for unchanged scope. Enforcement: `dispatch_core._next_attempt` and `execution_manifest._validate_next_attempt`.
305
+ After successful preparation, use the frozen `instruction-set/host-orchestration-rules.md` identified by the rendered launch prompt for resumed work and stage chaining. Read that frozen copy within the run as the launch prompt requires: reading the canonical file before preparation does not satisfy the implementation session read gate. An already prepared legacy run without the new outcome field keeps its existing skill and prepared-instruction contract. If a fresh outcome omits `hostRulesPath` or its non-empty path cannot be read, stop and report a runtime/skill version mismatch; do not infer waiver or recovery rules.
283
306
 
284
- Run every `outcome.persistActions[]` entry BEFORE `render-bundle`. The only supported action is:
307
+ `userAuthorization`, when present, preserves the confirmation prompt actually emitted by this wizard and the relayed `proceed` response. Preparation carries that record into the run manifest unchanged. Do not synthesize a receipt for older confirmed states. The record documents task scope; it does not grant host execution privileges.
285
308
 
286
- ```json
287
- {"command":"config.set","key":"pr-template-path","scope":"project|global","value":"<path>"}
288
- ```
289
-
290
- Execute the matching command for `scope`:
291
-
292
- ```bash
293
- okstra config set pr-template-path "<value>" --scope project
294
- okstra config set pr-template-path "<value>" --scope global
295
- ```
309
+ Before retrying a worker in an existing run, inspect its last invocation attempt: await running work; append an attempt only after `failed-no-mutation` within the retry budget. Preserve every other terminal attempt. `okstra team dispatch` routes the legacy declaration-only implementer failure to a separate same-model evidence-recovery invocation; collect its result before independent verification. Other terminal failures need `okstra agent-prompt materialize` with a new `--invocation-id`, distinct `--prompt`/`--result` paths, and unchanged assignment/model for a bounded correction. Do not restart completed implementation or request renewed approval for unchanged scope. Enforcement: `dispatch_core._next_attempt` and `execution_manifest._validate_next_attempt`.
296
310
 
297
- If an action has an unknown `command`, `key`, or `scope`, stop and report the wizard output instead of inventing a command.
311
+ `render-bundle --wizard-state-file` applies the confirmed PR-template save action before preparing the bundle. Do not execute `outcome.persistActions[]` separately. An unknown action, missing save authorization, or changed save scope stops preparation before settings are written. If an older confirmation did not record the save scope, reopen that confirmation rather than inventing a receipt. A settings write failure stops preparation; a later preparation failure reports that the successful settings write remains saved.
298
312
 
299
313
  Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — close the panes of the dispatches that finished in the prior round so they do not accumulate: `okstra team reclaim --project-root <projectRoot> --run-manifest <RUN_MANIFEST_PATH>` closes them, records `phase-batch-cleanup panes=<n>` with the number it closed, and prints that `PROGRESS:` line last — emit it as printed and do not call `okstra lead-progress append` for it. The command reads each dispatch's recorded status, so an in-progress worker keeps its pane whichever moment you call it. It closes only the panes okstra opened and recorded — a pane the harness opened for its own teammate carries no recorded id and is not okstra's to close. After collecting results and token usage, apply the selected adapter's `shutdown_workers` operation only to confirmed-complete workers; preserve in-flight workers and the lead. A `cli-wrapper` run holds no pane at all and `team reclaim` refuses it, so record the checkpoint there with `okstra lead-progress append … --phase phase-batch-cleanup --field panes=0`.
300
314
 
301
315
  Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run `okstra team reclaim … --gate` first: it closes the finished panes and prints `PROGRESS: phase-gate-cleanup panes=<n>` for you to emit, without recording a batch cleanup. Then apply the selected adapter's `shutdown_workers` operation to confirmed-complete workers after collecting their results and token usage; preserve in-flight workers and the lead. This keeps a user gate from being shown while finished worker panes remain; in-progress dispatches keep their panes. Then follow `prompts/lead/okstra-lead-contract.md` "User confirmation before an approval blocker": read cited plan items, worker findings, and files before asking, and ask in the user's language with each option's outcome.
302
316
 
303
- Build the `okstra render-bundle` invocation from `outcome.renderArgv`, passing every token verbatim and in order (including empty strings — they are intentional `use phase default` markers).
317
+ Prepare the bundle with the same literal absolute state-file path used by the wizard. Do not append scope inputs such as task type, role/model, directive, or lead runtime; the command rejects mixing those inputs with `--wizard-state-file`.
304
318
 
305
319
  Before invoking it, follow the active host relay's execution-permission guidance. For Codex, read "Permission before bundle preparation" in the relay already selected at preflight: bundle preparation can write protected Git metadata while creating a branch and worktree, even with `--render-only`. Apply this guidance to the first invocation and each subsequent phase or stage preparation.
306
320
 
307
- Analysis sidetracks therefore forward wizard-owned tokens such as `--analysis-target "<value>"` and `--evidence-inputs "<value>"` when they are present. These are examples of the verbatim token rule, not a separate hard-coded argument list.
308
-
309
- Step 3's empty-answer and escaping rules apply verbatim: every flag in `renderArgv` whose following value is the empty string MUST still be passed explicitly (e.g. `--related-tasks ""`, `--directive ""`) — the wizard's intent is always "flag present with empty value", even where prepare's default happens to be the same empty value.
310
-
311
- `renderArgv` already contains exactly one `--lead-runtime <host-runtime>` pair. Do not add or replace it. Do not enumerate a fixed provider list in this skill because the wizard and role model pool own the ordered tokens.
321
+ The only preparation additions are `--summary-only`, a stage in the confirmed implementation chain, and the existing separately user-confirmed `--tdd-bypass` / `--qa-waiver` exceptions under their host orchestration rules. Never infer an exception grant from the original wizard confirmation.
312
322
 
313
323
  ```bash
314
- okstra render-bundle --summary-only \
315
- <outcome.renderArgv token 1> \
316
- <outcome.renderArgv token 2> \
317
- <each remaining outcome.renderArgv token in order>
324
+ okstra render-bundle --wizard-state-file /var/folders/.../okstra-wizard.AbCd.json --summary-only
318
325
  ```
319
326
 
320
- `render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, `okstra run manifest:`, and other preparation status. `--summary-only` omits the lead prompt body from stdout; Step 6 reads the verified saved prompt from the manifest path. Parse the labelled lines for `TASK_ROOT`, `INSTRUCTION_SET_PATH`, and `RUN_MANIFEST_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "Concurrent-run detection branch" below).
327
+ `render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, `okstra run manifest:`, and other preparation status. `--summary-only` omits the lead prompt body from stdout; Step 6 reads the verified saved prompt from the manifest path. Parse the labelled lines for `TASK_ROOT`, `INSTRUCTION_SET_PATH`, and `RUN_MANIFEST_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "Concurrent-run detection branch" in the selected host rules).
321
328
 
322
329
  Before acting as the lead, read `resources.leadPromptMetadataPath` from the run
323
330
  manifest and execute the host-native specification-link gate:
@@ -336,147 +343,12 @@ it does not claim that the host exposed or attested the delivered prompt bytes.
336
343
 
337
344
  The python function underneath allocates the run sequence number and writes `run-context-*.json` under the per-task lock (`~/.okstra/.locks/<task-key>.lock`), then writes `run-inputs-*.json` + all manifests + discovery files outside that lock, and registers the run in `~/.okstra/recent.jsonl` with status `prepared` under the central `~/.okstra/.lock` (a registration failure is reported on stderr and does not fail prepare).
338
345
 
339
- **Not enforced:** `tests-js/wizard.test.mjs` pins the argv the wizard produces (`orderedRenderArgv` preserves the Python role selection bytes and repeated role order), not the argv you pass. Prepare's parser defaults most flags to `""` (e.g. `--directive`), so a dropped empty value is indistinguishable from its default and nothing rejects it — passing every token verbatim is on you.
340
-
341
- You can delete the literal state-file path after this point — its job is done. Invoke `command rm` with the literal path (e.g. `command rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable. `command` is what keeps a `rm='rm -i'` alias from turning this into a confirmation prompt nobody is there to answer.
342
- <!-- END FRAGMENT: wizard-render-bundle -->
346
+ Enforcement: `wizard.launch.load_confirmed_launch` validates the confirmed snapshot and save receipt; `render-bundle.prepareRenderBundle` preserves ordered inputs and rejects scope overrides before writes. `tests/wizard/test_launch.py` and `tests-js/render-bundle.test.mjs` cover these contracts. Host execution permission remains a separate host decision.
343
347
 
344
- <!-- BEGIN FRAGMENT: host-orchestration-implementation-planning -->
345
- ## Host orchestration rules — implementation-planning
346
-
347
- These are the rules the **host orchestrator** follows around an
348
- `implementation-planning` run: when a stage genuinely cannot write a RED step,
349
- and what only the user can grant. They are not lead phase rules — the lead's
350
- rules live in `prompts/profiles/`.
351
-
352
- ### Step 5.1 (implementation-planning only): user-confirmed TDD bypass offer
353
-
354
- Every plan stage must open with a `RED:` step whose outcome is FAIL and reach a
355
- later `GREEN:` step (validator S10c). `tddExemption` waives that, and until
356
- 2026-09-10 only for `doc-only`, `config-only`, or `pure-rename` work — so a
357
- stage that is truthfully none of the three had no passable value, and the plan
358
- got through by filing the nearest category. That is the failure this flag
359
- exists to remove: **a closed reason list with no escape makes the plan
360
- misdescribe itself.**
361
-
362
- `render-bundle` accepts an optional `--tdd-bypass "<stage>:<reason>"` flag
363
- (implementation-planning only). It records a **user-acknowledged** bypass into
364
- `<task-root>/qa/tdd-bypass.json`, and S10e then accepts that stage declaring
365
- `tddExemption: user-bypass`. The reason is stored **verbatim**.
366
-
367
- Offer it only when the run's own output says the stage cannot reach RED — a
368
- planning report blocked at S10e on a `user-bypass` stage, or a plan-body
369
- verification round whose disagreements say the expected FAIL is unreachable
370
- (e.g. the stage worktree HEAD is already the accepted commit). Never offer it
371
- to save a stage that simply has no test written yet; that stage's answer is the
372
- RED step.
373
-
374
- This is **never** a lead/worker self-exemption — only the user may grant it,
375
- and the lead has no command that writes this record. Surface it as a 3-option
376
- recommendation picker (per the run-prompt recommendation rule):
377
-
378
- 1. (recommended) Keep the RED/GREEN requirement — re-plan the stage so its
379
- first step writes the failing test.
380
- 2. Bypass this stage — ask the user for the stage number and reason, then pass
381
- `--tdd-bypass "<stage>:<reason>"` to `render-bundle` (reason = the user's
382
- words, unedited).
383
- 3. Enter directly — the user types the full `<stage>:<reason>` value.
384
-
385
- When the user picks a bypass, append `--tdd-bypass "<stage>:<reason>"` to the
386
- `render-bundle` invocation. Omit the flag entirely otherwise (do **not** pass
387
- `--tdd-bypass ""`). A malformed value aborts `render-bundle` with a
388
- `PrepareError`. The grant is per stage number and per task, and it persists
389
- across runs of that task — the next plan of the same stage may still declare
390
- `user-bypass` until the user's grant is removed from the ledger.
391
-
392
- **A stage whose work already landed is usually not a bypass case.** When the
393
- product change is committed and its conformance result is PASS but the stage
394
- never registered as done, the honest fix is to close that stage rather than to
395
- re-plan it without a RED step. Check `okstra stage-map <task-key>` first: when
396
- `doneStages` omits a stage whose commit is on the stage branch, close it with
397
- `okstra stage-close <task-key> --stage <N> --from-commit <sha>` and re-plan only
398
- what is left. That command refuses unless the commit exists and the stage's
399
- conformance gate permits progress, so it cannot close a stage the run validator
400
- would have blocked. A stage whose last row is `failed` only because its checks
401
- ran in the wrong environment, and whose commit needs no further product edit,
402
- closes the same way with `--supersede-failed "<reason>"`; the reason and the
403
- plan path are recorded on the `done` row.
404
-
405
- If `okstra stage-map` cannot read the prior plan during this planning run,
406
- follow the analysis packet's Stage Ledger recovery guidance. A notation error
407
- in an existing `dependsOn` cell is work for the new plan, not a reason to ask
408
- the user to edit JSON. Preserve the prior report, existing stage numbers and
409
- completed work; do not close or execute a stage from an unreadable map.
410
- An ambiguous dependency or stage identity remains a blocker.
411
- <!-- END FRAGMENT: host-orchestration-implementation-planning -->
412
-
413
- <!-- BEGIN FRAGMENT: host-orchestration-implementation -->
414
- ## Host orchestration rules — implementation
415
-
416
- These are the rules the **host orchestrator** follows around an `implementation`
417
- run: when to offer a conformance waiver, what a concurrent-run marker means, how
418
- to recover a stale stage SHA, and what the chaining queue does when the next
419
- stage is not ready. They are not lead phase rules — the lead's rules live in
420
- `prompts/profiles/`.
421
-
422
- This file is the single source. Two surfaces are generated from it: the
423
- `okstra-run` skill body (marker block, synced by `tools/sync-skill-fragments.mjs`)
424
- and each run's `instruction-set/host-orchestration-rules.md`. Edit here.
425
-
426
- ### Step 5.1 (implementation only): blocking local conformance waiver offer
427
-
428
- `render-bundle` accepts an optional `--qa-waiver "<stageKey>:<reason>"` flag (implementation only). It records a **user-acknowledged** waiver into the task-level conformance manifest entry (`entry.waiver`), letting the run proceed when an `io`-only Tier 3 conformance script genuinely cannot run. The waiver records the user's reason **verbatim**.
429
-
430
- Inspect the selected manifest entry's `requires`. If it contains `db`, `http`,
431
- or `external`, it is external-advisory: Do not offer a waiver and continue so
432
- the verifier can attempt automatic startup/execution. A non-PASS outcome will
433
- become a user-owned follow-up. If `requires=[]`, fail closed as declaration or
434
- contract trouble: Do not offer a waiver for `requires=[]`. Offer the existing
435
- waiver picker only when `requires=[io]` and that local command genuinely cannot run.
436
-
437
- This is **never** a lead/worker self-exemption — only the user may waive. After classification confirms `requires=[io]`, surface it as a 3-option recommendation picker (per the run-prompt recommendation rule):
438
-
439
- 1. (recommended) Run the conformance script — no waiver.
440
- 2. Waive this stage — ask the user for the exact `<stageKey>` and reason, then pass `--qa-waiver "<stageKey>:<reason>"` to `render-bundle` (reason = the user's words, unedited).
441
- 3. Enter directly — the user types the full `<stageKey>:<reason>` value.
442
-
443
- When the user picks a waiver, append `--qa-waiver "<stageKey>:<reason>"` to the `render-bundle` invocation above. Omit the flag entirely otherwise (do **not** pass `--qa-waiver ""`). A malformed value or unknown `<stageKey>` aborts `render-bundle` with a `PrepareError`.
444
-
445
- ### Concurrent-run detection branch (concurrent-run)
446
-
447
- If `render-bundle` stdout carries an `okstra concurrent-run stages: <stages>` label line (another implementation run on the same task-key is occupying `<stages>`), the launch prompt has already been rendered with the "Concurrent-run marker" gate. If this line is absent it is not a concurrent run, so skip this branch. If present, before dispatch present a 3-option recommendation picker to the user (run-prompt recommendation rule: 1–2 recommendations + Enter directly; this picker is authored by the skill, so it is unconstrained by the wizard `options[]` rule):
448
-
449
- 1. (recommended) Proceed as-is — use the already-rendered bundle. Each session uses its own implicit team, so concurrent runs have no team conflict and split-pane works fine.
450
- 2. Wait — hold the dispatch for now. The stage worktree·run-context are preserved, so after the other occupying run finishes, resuming the same stage takes the normal team path. Tell the user to resume the same stage with `okstra-run` after the other run finishes.
451
- 3. Enter directly.
452
-
453
- ### Stale git SHA recovery (git-reconcile gate)
454
-
455
- If `render-bundle` fails with a `PrepareError` containing `Recorded stage SHAs no longer match the git history`, the git history changed outside okstra (rebase / squash / review-feedback amend / branch deletion). Never fix the registry/consumers by hand; recover in this order:
456
-
457
- 1. Run the `okstra git-reconcile … --check --text` command printed in the error message verbatim to get the stale report. (Items whose content-identity is proven by patch-id were already auto-reconciled by prepare, so only confirm items remain here.)
458
- 2. For each confirm item, present a 3-option picker to the user:
459
- - **Re-record to the `stage-<N>` branch's current tip (recommended)** — when an intended change such as review feedback lives on that branch.
460
- - **Enter a different ref directly** — the user names a commit/branch/tag.
461
- - **Abort** — stop the run without recovering.
462
- 3. Run `okstra git-reconcile … --apply --stage <N> --use-ref <ref>` with the chosen ref, then retry the failed `render-bundle` with the same arguments.
463
- If that output carries a `Warning` naming the implementation anchor, the chosen head no longer contains the anchor: show the warning to the user and run its printed `--reset-anchor` command only after they confirm the new base, before the retry.
464
-
465
- If the anchor (`implementation_base_commit`) is reported unresolvable, run the same command's `--reset-anchor <ref>` after user confirmation. Correcting a confirm item without the picker is forbidden — the runtime also rejects a confirm correction without `--use-ref`.
348
+ After successful preparation of a single run, delete the literal state-file path. For an implementation chain with multiple stages, keep it until preparation of the last confirmed stage succeeds. Do not delete it after a failed preparation. Invoke `command rm` with the literal path (e.g. `command rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable. `command` keeps an interactive `rm` alias from blocking cleanup. The preparation code never deletes this file.
466
349
 
467
- ### Predecessor merge conflict (merge-base gate)
468
-
469
- A stage that depends on two or more stages starts from a merge-base branch that okstra builds from the implementation anchor by merging each predecessor's completion commit with `--no-ff`, in stage order. If two predecessors conflict, `render-bundle` fails with a `PrepareError` containing `merge conflict while merging stage <N>`. okstra never resolves the conflict itself. When it was creating the branch, it deletes the half-built branch and the steps start from the anchor. When it was advancing an existing branch to a newer predecessor commit, the branch stays at its previous tip and the steps check it out and merge only the commits it lacks. Do not edit the registry or consumers, and do not merge a predecessor into a stage branch. Stop and show the user the conflicting paths and the steps from the error verbatim: the branch name, the `git worktree add` command, and one `git merge --no-ff --no-edit <commit>` per predecessor in the listed order. Those commands disable repository hooks the way okstra's own merges do. The user, or you on the user's instruction, runs those steps, resolves the conflict, runs the project's checks, commits the merge and removes that worktree. Then retry the failed `render-bundle` with the same arguments. It reuses the branch only when the branch contains the anchor and every predecessor commit and carries no other non-merge commit; otherwise it fails and names the problem.
470
-
471
- ### Next stage not yet ready — normal termination (not an exception gate)
472
- Because of the dependency closure, the chain queue **may include a stage that another implementation run has occupied as started/reserved.** That stage's `render-bundle` is rejected with `--stage N already in progress or reserved by another run` (StageTargetError). This is **not** an exception gate needing human judgment but a "next stage not yet ready" situation. On this rejection, **terminate the chain normally** and report the remaining queue to the user (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`). This is a different branch from the exception gate below (data corruption·concurrent-occupancy conflict confirmation).
473
-
474
- ### Stage ended FAIL — stop the queue and report (not an exception gate)
475
- A verifier FAIL that a passing lead minor fix answered does not make the verdict `FAIL` (`_implementation-deliverable.md` "Lead minor fix"); that stage settles `done` and the queue continues. When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
476
-
477
- ### Exception gate during chaining
478
- If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch), git stale-SHA reconciliation (git-reconcile branch) or a predecessor merge conflict (merge-base gate), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these branches do not discard the queue; they wait for user resolution.)
479
- <!-- END FRAGMENT: host-orchestration-implementation -->
350
+ If the file disappears before a remaining stage is prepared, stop that chain and report the completed and remaining stages. Reopen the wizard for the remaining scope; do not rebuild its inputs or approval receipt from a previous run. Already prepared runs resume from their run manifest without this file. After an interrupted or uncertain preparation, inspect the task's existing runs before retrying: this command does not promise exactly-once preparation.
351
+ <!-- END FRAGMENT: wizard-render-bundle -->
480
352
 
481
353
  <!-- BEGIN FRAGMENT: wizard-lead-takeover -->
482
354
  ## Step 6: Take over as Okstra lead
@@ -493,20 +365,20 @@ Inform the user with one short line:
493
365
 
494
366
  When `task-type == implementation` and Step 5 outcome's `orchestration.chainStages` CSV has 2+ elements, the current session acts as the orchestrator and runs the stages in dependency order as an unattended chain (a single element ends this queue after same-run recovery is complete; a separately authorized continuous task follows the continuation rule below).
495
367
 
496
- Queue = the topologically-sorted stage list from splitting `orchestration.chainStages` on `,` (the order Task 5 emitted by topologically sorting the dependency closure). For each stage `N` in the queue, in order:
368
+ Queue = the topologically-sorted stage list from splitting `orchestration.chainStages` on `,` (the wizard emits it topologically sorted over the dependency closure). For each stage `N` in the queue, in order:
497
369
 
498
- 1. Call Step 5's `render-bundle` with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit`, so do not pass it by hand). Step 5's blocking local conformance waiver offer·concurrent-run detection·git-reconcile gates apply identically to each stage's `render-bundle`.
370
+ 1. Call Step 5's `render-bundle --wizard-state-file <same absolute path> --summary-only --stage N`. Keep the state file until preparation of the last confirmed stage succeeds; if it is missing, stop and report the completed and remaining stages, then reopen the wizard for the remaining scope. Do not reconstruct approval from prior run inputs. The base commit is auto-computed by prepare from the predecessor's done `head_commit`, so do not pass it by hand. Apply the blocking local conformance waiver, concurrent-run detection, git-reconcile, and merge-base gates from the frozen host rules read for the prepared run to each stage's `render-bundle`.
499
371
  2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead post-stage persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` (per the implementation profile directive).
500
- 3. After confirming that `done` row was written, close the panes of the stage you just finished: run `okstra team teardown --project-root <projectRoot> --run-manifest <that stage's RUN_MANIFEST_PATH>`. That stage's run is over, so this is the run-end command rather than the round-boundary one. Then move to the next stage. A `status:"failed"` row instead of `done` means the stage ended `FAIL` — close the panes the same way, then stop the queue per "Stage ended FAIL" above.
372
+ 3. After confirming that `done` row was written, close the panes of the stage you just finished: run `okstra team teardown --project-root <projectRoot> --run-manifest <that stage's RUN_MANIFEST_PATH>`. That stage's run is over, so this is the run-end command rather than the round-boundary one. Then move to the next stage. A `status:"failed"` row instead of `done` means the stage ended `FAIL` — close the panes the same way, then stop the queue per "Stage ended FAIL" in the frozen host rules.
501
373
  4. One-line report at each stage start/finish: `stage N start` / `stage N done → next K`.
502
374
 
503
375
  Once the whole queue is consumed, end the chain and report completion to the user.
504
376
 
505
- The three branches that end or pause the queue — "Next stage not yet ready", "Stage ended FAIL", and "Exception gate during chaining" — are in the host orchestration rules block above.
377
+ The three branches that end or pause the queue — "Next stage not yet ready", "Stage ended FAIL", and "Exception gate during chaining" — are in the frozen host rules read for the prepared run.
506
378
 
507
379
  ## Persisting the PR template scope (release-handoff)
508
380
 
509
- Do not read the wizard state file directly. `okstra wizard outcome` exposes any release-handoff PR template write as `outcome.persistActions[]`; execute those actions before `render-bundle`.
381
+ Do not read the wizard state file directly or execute `outcome.persistActions[]` yourself. `render-bundle --wizard-state-file <absolute-path>` validates the displayed save scope and applies its PR-template setting before preparation.
510
382
 
511
383
  ## Comparison material for a direction choice
512
384
 
@@ -42,9 +42,8 @@ If the call fails with `unknown command: preflight`, the `okstra` binary on PATH
42
42
 
43
43
  ## What the finished document looks like
44
44
 
45
- The rules below are long because each one was learned from a published schedule
46
- that failed a reader. This is the shape they add up to — read it once before
47
- Step 4, and again at Step 7.
45
+ This is the shape the rules below add up to — read it once before Step 4, and
46
+ again at Step 7.
48
47
 
49
48
  | Section | Holds | Never holds |
50
49
  |---|---|---|
@@ -54,8 +53,6 @@ Step 4, and again at Step 7.
54
53
  | `## Gantt Chart` | one bar per selected stage, label and bar only | `days=`, per-row `! crit`/`est` |
55
54
  | `## Task Details` | per task: Item/Detail, Problem, Solution, Work Breakdown, one block per stage (`Steps` + `Exit criteria`), Verification Commands, Rollback | `Value`, `Acceptance`, a risk section, a cross-task section, a next-actions list |
56
55
 
57
- Every one of those "never holds" entries was in a shipped schedule. Four
58
- restated a table that sat directly above or below them.
59
56
 
60
57
  ## Audience & authority (READ FIRST — drives everything below)
61
58
 
@@ -66,7 +63,7 @@ restated a table that sat directly above or below them.
66
63
  **Assume the user and their team hold full authority and every permission required.** External approvals, access grants, sign-off, and vendor coordination are treated as already satisfied unless a report names a concrete external dependency outside the user's control. Concretely:
67
64
 
68
65
  - **Effort sizing & day totals** count engineering work only — strip approval-waiting / coordination buffers from source sizings (note the adjustment in `## Executive Summary` if material).
69
- - **Gantt bars** represent engineering duration only; no dead-time gaps for approval cycles. `(after <TASK-ID>)` marks genuine engineering dependencies only.
66
+ - **Gantt bars** represent engineering duration only; no dead-time gaps for approval cycles.
70
67
  - **Steps and Exit criteria** are concrete engineering work; items like "permission check", "approval request", "stakeholder alignment" MUST NOT be emitted.
71
68
 
72
69
  **The schedule must be self-contained.** Opaque codes pulled from internal reports (`FC-5`, `UC-12`, `M1`, decision-item letters, …) must not appear unresolved. Choose one per identifier: **Form A** (≤3 codes) — replace the code inline with a 5–20 character one-line description of the item; **Form B** (≥4 recurring codes) — keep the codes and emit a `## Glossary` table as the last section resolving every one. Decision-item letters (`A1`, `B2`, …) are approval items and may not appear at all. TASK-IDs listed in `## At a Glance` need neither.
@@ -103,7 +100,7 @@ One computation rule the template scaffold cannot carry inline:
103
100
 
104
101
  ### Step 2: Filter by workStatus
105
102
 
106
- When `workStatus` is missing or empty, infer `done` if `currentStatus` is `completed` and `workflow.nextRecommendedPhase.status` is `terminal`; infer `phase-done` if `currentStatus` is `completed` and `workflow.currentPhaseState` is `completed`; infer `blocked` if `currentStatus` is `contract-violated` or `workflow.currentPhaseState` is `blocked`; otherwise infer `in-progress`. Do not write inferred values back. Then filter: resolved `done` → exclude; everything else (`todo` / `in-progress` / `blocked` / `phase-done` / inferred non-done) → include.
103
+ Filter on the fixed view's `Work status`: `done` → exclude; everything else (`todo` / `in-progress` / `blocked` / `phase-done`, or a missing or empty value) → include.
107
104
 
108
105
  If 0 tasks remain, output `All tasks in this task-group are done. There is no schedule to generate.` and stop **without creating a file**.
109
106
 
@@ -166,11 +163,11 @@ Selecting which source rows belong in a schedule is not summarising. Dropping a
166
163
 
167
164
  **`## Executive Summary` opens with `**목적**` and `**달라지는 것**`; the validator requires both.** A reader who opens only that section must learn why the work happens and what is true when it ends — scope and day arithmetic alone say neither. The material is in the report's `humanSummary` (`headline`, `outcome`, `whyItMatters`), which `okstra stage-map` carries as `planning.reportSummary`. Rewrite it: that field addresses an approver ("your two questions", "the option you approved"), and that framing must not survive. `decisions`, `actions` and `blockers` are not carried at all — they ask for sign-off.
168
165
 
169
- **State the limits in the outcome list.** When the work stops short of what its name suggests, the summary says so. Here the migration ships with three ports still vendor-shaped, so the schedule says "디렉터리 구조 완료, 격리 미완" rather than letting the reader assume the isolation is finished. A summary that only lists wins is the kind a reader stops trusting on the first surprise.
166
+ **State the limits in the outcome list.** When the work stops short of what its name suggests, the summary says so. For example, a migration that leaves some ports vendor-shaped says "디렉터리 구조 완료, 격리 미완" rather than letting the reader assume the isolation is finished. A summary that only lists wins is the kind a reader stops trusting on the first surprise.
170
167
 
171
168
  **A stage block is `Steps` plus `Exit criteria`, and nothing else.** The `Steps` table comes from `stepwiseExecution` — one row per step with what it does (keep the leading `RED:` / `GREEN:` marker), the files it touches, and what the executor should see when it succeeds, from that step's `expected`. In the 대상 column separate entries with `<br>`, not a comma: a comma-joined path list stretches that column and squeezes the two text columns into a gutter. `Exit criteria` is one line from `exitContract` saying when the stage is finished.
172
169
 
173
- Do not render `sliceValue` — it argues why the plan sliced the work this way, which is a reviewer's question, not an implementer's. Do not render `acceptance` alongside `exitContract`: they restate each other. Measured on one real plan, `acceptance`'s four claims all reappeared in `exitContract`, which then added two more. Sort `Verification Commands` `pre` → `mid` → `post` and introduce those three values above the table — source order interleaves them, and a reader working down the table would run a precondition after the checks it gates.
170
+ Do not render `sliceValue` — it argues why the plan sliced the work this way, which is a reviewer's question, not an implementer's. Do not render `acceptance` alongside `exitContract`: they restate each other, and `exitContract` is the superset. Sort `Verification Commands` `pre` → `mid` → `post` and introduce those three values above the table — source order interleaves them, and a reader working down the table would run a precondition after the checks it gates.
174
171
 
175
172
  **The schedule has no risk section, no cross-task section and no next-actions list.** Every row those carried restated a stage: a risk's mitigation *is* the stage that answers it, an upstream dependency *is* the step that gates on it, and the next action *is* Stage 1's first step. Carry `dependencyMigrationRisk` and `crossProjectDependencies` by making sure the stage they point at says what they demand — and put anything genuinely not a stage (a freeze agreed with another team, a coupling the stages only imply) in that task's **Solution** or **Repo** cell.
176
173
 
@@ -178,7 +175,7 @@ Do not render `sliceValue` — it argues why the plan sliced the work this way,
178
175
 
179
176
  ### Step 5: Gantt decision (render by default)
180
177
 
181
- `## Gantt Chart` is **rendered by default** — skip ONLY when literally no day signal exists (every in-scope task lacks both effort sizing and stage decomposition). An XXL task is not a skip reason: it is sized by its stages. Render whenever any of these hold: 2+ tasks with effort sizing; 1 task whose effort yields a range (mid-point bar, or `lo`/`hi` two-bar form); 1 task with Part/Phase/Step decomposition in the source (bars at decomposition-unit level); total estimated effort ≥ 3 days. When per-unit day allocations aren't itemized, split the parent range across the visible units yourself and append the `est` annotation (or add `> Per-day allocation is an estimate; refresh recommended after blocking items are resolved.`). "Range is wide", "single task", "user decisions pending" are NOT skip reasons — render an estimate-tagged chart instead.
178
+ `## Gantt Chart` is **rendered by default** — skip ONLY when literally no day signal exists (every in-scope task lacks both effort sizing and stage decomposition). An XXL task is not a skip reason: it is sized by its stages. "Range is wide", "single task" and "user decisions pending" are not skip reasons.
182
179
 
183
180
  When the source is a Stage Map, the Gantt bars are selected stages. A row is labelled `Stage <n>` when exactly one task is scheduled, and `<TASK-ID> Stage <n>` when more than one is. Spell the stage out — `S1` costs the reader a lookup and saves five characters. A row is a label and a bar and nothing else: no `days=` annotation (the Work Breakdown owns those numbers, and the validator compares the bar against that column), and no per-row `! crit` / `est` markers, which distinguish nothing when every row carries them. One line above the fence states the column unit and what `█` and `░` mean — that is the whole legend, because those two glyphs are the only notation left. Split the task effort range proportionally by `step_count`; round every stage except the last to 0.5 day and let the last stage absorb the remainder. Cross-stage dependency annotations follow `depends_on`. Already-done and non-selected stages never get a bar. A task tagged `[NEEDS-PLANNING]` contributes no bars.
184
181
 
@@ -190,7 +187,7 @@ When the source is a Stage Map, the Gantt bars are selected stages. A row is lab
190
187
 
191
188
  An unrepresentable half-day allocation is a validation error. Do not switch to a fallback allocation algorithm or publish that draft.
192
189
 
193
- When you do skip, insert in the section's position exactly: `> _Gantt Chart skipped: <concrete reason referencing the actual data>._`
190
+ When you do skip, insert in the section's position exactly: `> _Gantt Chart omitted: <concrete reason referencing the actual data>_`
194
191
 
195
192
  **Directive override (highest priority).** Before applying the heuristic, check for a `## Directive` section, first hit wins: (1) the `--directive-file <abs-path>` argument; (2) `<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md`; (3) none → apply the default heuristic silently. A found directive overrides the render/skip heuristic for the affected section — note it inline as `> _Per Directive directive: <verbatim short excerpt>._` — and its pre-supplied day allocations / phase weights are used verbatim as bar lengths. A directive file without a `## Directive` heading counts as "no directive".
196
193
 
@@ -282,7 +279,7 @@ Reached only after both Step 5.5 gates return `pass`. Promote the verified same
282
279
  2. Run `python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>` as a final format check; use the repository validator only when the installed validator is absent.
283
280
  3. Delete the temporary `.selection.json` only after that final check passes. Do not print the Step 8 message while the selection contract still exists or validation is failing.
284
281
 
285
- **Then read the document once as its reader.** The validator settles structure, arithmetic, controlled vocabulary and run-internal leakage; it cannot judge any of the following, and each has shipped in a published schedule before:
282
+ **Then read the document once as its reader.** The validator settles structure, arithmetic, controlled vocabulary and run-internal leakage; it cannot judge any of the following:
286
283
 
287
284
  - Does the summary say **why** the work happens and what is **true when it ends** — including what stays unfinished? A list of wins that omits a known limit is the kind a reader stops trusting at the first surprise.
288
285
  - Does every step say what to **do**, or does some row only explain why the plan chose this shape? The second is the report's voice, not the schedule's.
@@ -312,7 +309,6 @@ Reached only after both Step 5.5 gates return `pass`. Promote the verified same
312
309
  | ≤2 remaining stages | Emit only as many cumulative bundles as arise (1–2); a single chain skips the picker and proceeds with all |
313
310
  | either validation gate still fails after two revisions | Final file not written; report residual findings to the user |
314
311
  | `task-group` matches no tasks | "That task-group could not be found." and stop |
315
- | Catalog and manifest disagree on `workStatus` | Manifest wins (catalog may be stale) |
316
312
  | task-group casing / punctuation variants | `schedule-input` matches them: it lowercases the argument and the group part of each catalog task key and drops every non-alphanumeric character (Unicode letters and digits stay); use the Step 6 segment verbatim for path output |
317
313
 
318
314
  ## Output Rules