okstra 0.226.0 → 0.227.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 (44) hide show
  1. package/README.md +1 -0
  2. package/dist/commands/execute/wizard.mjs +12 -15
  3. package/dist/commands/execute/wizard.mjs.map +1 -1
  4. package/docs/cli.md +29 -5
  5. package/docs/project-structure-overview.md +1 -1
  6. package/package.json +1 -1
  7. package/runtime/BUILD.json +2 -2
  8. package/runtime/agents/operations/code-review.json +1 -1
  9. package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
  10. package/runtime/prompts/wizard/prompts.ko.json +44 -0
  11. package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
  12. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
  13. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
  14. package/runtime/python/okstra_ctl/code_review_coverage.py +70 -18
  15. package/runtime/python/okstra_ctl/code_review_target.py +77 -53
  16. package/runtime/python/okstra_ctl/correction_cli.py +6 -5
  17. package/runtime/python/okstra_ctl/correction_round.py +1 -1
  18. package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
  19. package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
  20. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  21. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  22. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  23. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +2 -2
  24. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
  25. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  26. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  27. package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
  28. package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
  29. package/runtime/python/okstra_ctl/run.py +15 -1
  30. package/runtime/python/okstra_ctl/stage_done.py +5 -4
  31. package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
  32. package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
  33. package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
  34. package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
  35. package/runtime/python/okstra_ctl/wizard/render.py +2 -2
  36. package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
  37. package/runtime/python/okstra_ctl/wizard/state.py +55 -14
  38. package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
  39. package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
  40. package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
  41. package/runtime/python/okstra_ctl/write_policy.py +33 -18
  42. package/runtime/skills/okstra-code-review/SKILL.md +25 -23
  43. package/runtime/skills/okstra-code-review/references/review-calibration.md +2 -2
  44. package/runtime/skills/okstra-run/SKILL.md +21 -1
@@ -6,7 +6,7 @@ description: >-
6
6
  unrelated to an okstra run. The tell is a review request over a diff:
7
7
  "review this stage", "review my branch", "code review", "leave the review
8
8
  in a file". The orchestrator censuses the diff into an explicit worklist,
9
- one or two reviewers (the user picks) each return a verdict for every cell
9
+ one to three reviewers (the user picks) each return a verdict for every cell
10
10
  against this project's coding-preflight rules, a coverage audit
11
11
  re-dispatches any gap, and the orchestrator settles what the reviewers
12
12
  disagree on. NOT for writing a PR body (okstra-pr-gen), starting a run
@@ -75,13 +75,14 @@ Pick the mode from what the user actually gave you:
75
75
  **Branch mode.**
76
76
 
77
77
  1. If the user named no branch, list `git -C <projectRoot> branch --format='%(refname:short)'` and offer a 3-option picker with the current branch as the first recommendation.
78
- 2. Detached HEAD — `git -C <projectRoot> symbolic-ref --quiet HEAD` prints nothing — is refused: ask the user to name a branch. Do not review a bare commit.
78
+ 2. Ask for the comparison base branch, tag or commit unless the user already named one. Do not infer a parent branch or substitute the repository default. Pass it as `--base <ref>`; branch mode rejects an omitted or invalid base and freezes the selected ref as a commit.
79
+ 3. Detached HEAD — `git -C <projectRoot> symbolic-ref --quiet HEAD` prints nothing — is refused: ask the user to name a branch. Do not review a bare commit.
79
80
 
80
81
  **Then call the target CLI.** One call resolves everything the rest of this skill needs; the only reason to call it again is a base the user overrides in the confirmation step below.
81
82
 
82
83
  ```bash
83
84
  okstra code-review target --task-key <taskKey> --stage <N> --project-root <projectRoot> --text
84
- okstra code-review target --branch <name> [--base <ref>] --project-root <projectRoot> --text
85
+ okstra code-review target --branch <name> --base <ref> --project-root <projectRoot> --text
85
86
  ```
86
87
 
87
88
  `Status: ready` carries `Project root`, `Mode`, `Worktree path`, `Branch`, `Base commit`, `Head commit`, `Review path`, `Round`, and `Report language`; stage mode adds `Task key`, `Task root`, and `Stage`. Carry every field verbatim into the later steps — none of them is recomputed anywhere below.
@@ -98,10 +99,9 @@ okstra model-io code-review-input --project-root <projectRoot> --base <baseCommi
98
99
  Carry this fixed Markdown view into the census and reviewer prompts. Do not
99
100
  pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
100
101
 
101
- **You never derive the base.** Pass `--base <ref>` only when the user named one; otherwise the CLI resolves it. `baseCommit` is a **ref, not necessarily a commit id** — a caller-supplied `--base` passes through verbatim — so use it as given in `git diff <baseCommit>..<headCommit>` and never present it as "commit `<sha>`".
102
-
103
- **Where to run git.** Use `worktreePath` when it is non-empty; otherwise run git in `projectRoot` and read the stage's `branch` ref. An empty `worktreePath` does **not** mean the stage is gone: a completed stage's registry row is `released`, so the field is empty even when the directory is still on disk. Either way the commits are on the branch. With no worktree there is no checked-out tree to read whole files from, so every brief tells the reviewer to read a file at the reviewed commit with `git -C <projectRoot> show <headCommit>:<path>` — never from the project root's working tree, which holds a different commit.
102
+ **The user owns the comparison base.** Branch mode requires their selected base branch or commit and resolves it to a fixed `baseCommit`. Stage mode keeps the recorded stage base unless the user explicitly overrides it; a recorded or overridden stage value may still be a ref, so carry it verbatim. Do not substitute the default branch or an inferred parent.
104
103
 
104
+ **Read the frozen head in both modes.** Run git in `worktreePath` when it is non-empty, otherwise in `projectRoot`; call that location `<gitRoot>`. Read every whole source file, caller and test with `git -C <gitRoot> show <headCommit>:<path>`, including clean observations. A checkout on the selected branch may contain uncommitted edits or move during review. `worktreePath` identifies a Git repository, not authority to read its working files. Branch targets leave it empty; a released stage can also have an empty path.
105
105
  **Then show the base and confirm it — branch mode and stage mode alike.** The CLI's answer is a recommendation the user has not seen yet, and a base nobody looked at is how unrelated commits slip into a review unnoticed. Print `baseCommit` verbatim next to `git -C <workdir> log -1 --oneline <baseCommit>` so the commit it names is legible, then ask with a 3-option picker:
106
106
 
107
107
  1. `Use <baseCommit>` — **the recommendation**, the value the CLI returned.
@@ -124,16 +124,18 @@ A large census is never truncated. Report the cell count and confirm before disp
124
124
 
125
125
  ## Step 3 — Materialize and dispatch the reviewers in parallel
126
126
 
127
- **Ask how many reviewers** with a 3-option picker:
127
+ **Ask how many reviewers** with these choices:
128
+
129
+ 1. `2 reviewers` — **the recommendation**: two different models each review the whole census.
130
+ 2. `3 reviewers` — three different models each review the whole census; higher execution cost.
131
+ 3. `1 reviewer` — cheaper; you adjudicate every finding it returns.
128
132
 
129
- 1. `2 reviewers` — **the recommendation**: two different models each review the whole census, and you settle only where they disagree.
130
- 2. `1 reviewer` — cheaper; you adjudicate every finding it returns.
131
- 3. `Enter directly` — always last; accept only `1` or `2`.
133
+ Accept only `1`, `2` or `3`; a host may also allow direct text input.
132
134
 
133
135
  Then ask the runtime what those reviewers run — do not choose the role or the providers here:
134
136
 
135
137
  ```
136
- okstra agent-prompt resolve-operation --operation code-review --count <1|2>
138
+ okstra agent-prompt resolve-operation --operation code-review --count <1|2|3>
137
139
  ```
138
140
 
139
141
  It prints the duty, the role, the reviewer count, and one `slot` line per reviewer carrying that slot's
@@ -154,9 +156,9 @@ process, run the provider wrapper `~/.okstra/bin/okstra-<provider>-exec.sh <proj
154
156
  with the verified prompt path (`okstra worker-dispatch` dispatches only a run manifest's assignments, not a
155
157
  standalone prompt). The wrapper records the provider's output in the prompt path with `.md` replaced by
156
158
  `.log`. Never substitute one model value for the other. Dispatch the verified calls in parallel when the host supports
157
- it. **Every reviewer receives the same brief** — two reviewers are worth their cost only when both look at every cell. Every brief carries:
159
+ it. **Every reviewer receives the same brief** and reviews every cell independently. Every brief carries:
158
160
 
159
- - the diff, plus how to read whole files at the reviewed commit: the `worktreePath` when it is non-empty, otherwise `git -C <projectRoot> show <headCommit>:<path>`
161
+ - the diff and the fixed-head read command `git -C <gitRoot> show <headCommit>:<path>`, where Step 1 resolved `<gitRoot>`
160
162
  - the project layout in one or two lines (where source, tests, and — if the routing found one — domain / ports / adapters live)
161
163
  - **the whole census** — the shared rule catalog once and every grouped cell of all four axes, verbatim
162
164
  - the absolute paths of every applied pack (from step 2's routing)
@@ -188,10 +190,10 @@ Keep normal output to one compact Coverage Verdicts row per cell, with explicit
188
190
  For each reviewer separately, audit its grouped rows and explicit rule-ID accounting using its verified completion marker:
189
191
 
190
192
  ```bash
191
- okstra code-review check-coverage --project-root <projectRoot> --census <grouped-census-path> --completion <completion-path> [--completion <gap-fill-completion-path> ...]
193
+ okstra code-review check-coverage --project-root <projectRoot> --head <headCommit> --census <grouped-census-path> --completion <completion-path> [--completion <gap-fill-completion-path> ...]
192
194
  ```
193
195
 
194
- The command reuses the existing completion verification boundary and refuses mixed model assignments. Exit 0 means every cell accounts for all rules in its group with valid source evidence and no unknown cell ID; exit 1 lists missing cells, missing rule IDs or invalid grouped verdicts; exit 2 reports invalid input or completion evidence. It validates the shared catalog and source anchors, but does not establish whether the selected references are exhaustive or a verdict is true.
196
+ Pass the `headCommit` that `okstra code-review target` returned. The command reads each evidence file as `<headCommit>` holds it (`git show <headCommit>:<path>`), never the project root's working tree, so a review run from a checkout on another commit audits the reviewed lines. The command reuses the existing completion verification boundary and refuses mixed model assignments. Exit 0 means every cell accounts for all rules in its group with valid source evidence and no unknown cell ID; exit 1 lists missing cells, missing rule IDs or invalid grouped verdicts; exit 2 reports invalid input or completion evidence. It validates the shared catalog and source anchors, but does not establish whether the selected references are exhaustive or a verdict is true.
195
197
 
196
198
  For missing checks, dispatch one gap-fill invocation per reviewer on that reviewer's original slot, carrying only its incomplete grouped cells, their shared catalog entries, the same range and rule paths. Ask for one complete row for each such cell, not separate replies per missing rule. Use a new invocation ID and repeat the full materialize → verify → dispatch → materialize-result → complete → verify-completion boundary. Re-run the audit with that reviewer's initial and gap-fill markers. Earlier usable verdicts remain unchanged. An invocation with unknown IDs is invalid; record its rejection and request a corrected new invocation before auditing the retained valid completions. Do not silently relabel IDs.
197
199
 
@@ -207,17 +209,17 @@ Reviewers miscount lines. Pass every finding's `path:line` to one call:
207
209
  okstra code-review check-lines --project-root <projectRoot> --base <baseCommit> --head <headCommit> --cite <path:line> [--cite <path:line> ...]
208
210
  ```
209
211
 
210
- `ok` keeps the citation. For `not-changed` or `not-in-diff`, find the finding's `snippet` in `git -C <projectRoot> show <headCommit>:<path>`; if it sits on one of the changed lines the output lists, replace the line number with that line and say so in the finding. A finding whose snippet is on no changed line goes to `Rejected` as "cites no changed line". Re-run `check-lines` until every kept citation is `ok`.
212
+ `ok` keeps the citation. A fully deleted file has no head-side citation; a deletion within a surviving file retains its anchor before the cut. For `not-changed` or `not-in-diff`, find the finding's `snippet` in `git -C <projectRoot> show <headCommit>:<path>`; if it sits on one of the changed lines the output lists, replace the line number with that line and say so in the finding. A finding whose snippet is on no changed line goes to `Rejected` as "cites no changed line". Re-run `check-lines` until every kept citation is `ok`.
211
213
 
212
214
  ## Step 3.7 — Settle the findings
213
215
 
214
216
  Reviewers are wrong in a way a census cannot catch: a claim about code they did not open. What you settle depends on the reviewer count. Before pairing findings, check every finding, including agreed ones, against its `kind`: an `execution-error` needs an evidenced reachable `failure`; a `design-violation` needs an applicable named rule, code evidence, and concrete `impact`. Both need a fix. Missing or unsupported required evidence goes to `Rejected` with the specific reason; do not demand a runtime failure for a design violation.
215
217
 
216
- **Two reviewers.** Pair the findings first: two findings are the same finding when they cite the same `path:line` and describe the same defect. Then:
218
+ **Two or three reviewers.** Group findings by the same `path:line` and defect. Inspect every reported finding, including one supported by only one of three reviewers; silence or a clean verdict is not a vote against it. Then:
217
219
 
218
- - **Agreed** — both reviewers report it with the same severity and timing. It keeps its severity and timing after the evidence and kind checks above; agreement does not replace those checks.
219
- - **Graded differently** — both report it, with a different severity or timing. Pick one of the two values after reading the code, and record both values and your reason in the finding. Never pick a third value.
220
- - **One-sided** — one reviewer reports it and the other returned `clean` for that cell or reported something else. Adjudicate it as below.
220
+ - **Agreed** — every reviewer reports it with the same severity and timing. It keeps its severity and timing after the evidence and kind checks above; agreement does not replace those checks.
221
+ - **Graded differently** — at least two report it with different severity or timing. Choose one reporting reviewer's severity/timing pair for that finding after reading the code, and record all reported values and your reason. Never choose an unreported value or use majority vote in place of evidence.
222
+ - **One-sided** — fewer than all reviewers report it with no grading disagreement; the others returned `clean` for that cell or reported something else. Adjudicate it as below.
221
223
 
222
224
  **One reviewer.** Adjudicate every finding it returns.
223
225
 
@@ -226,13 +228,13 @@ Reviewers are wrong in a way a census cannot catch: a claim about code they did
226
228
  - **Confirmed** — the code supports the execution failure or the applicable design violation and its impact. The finding keeps its severity and timing.
227
229
  - **Rejected** — the code contradicts the claim (the called function never reads `this`, the value cannot be null there, the branch is unreachable). Move it to `Rejected` with the contradicting `path:line` and one sentence on what it shows.
228
230
 
229
- Rejecting is a statement about the code, so it always carries a `path:line`. Never reject for being unconvinced. Apart from choosing between two reviewers' values, never promote, demote, or re-time a finding. Confirmed and agreed `park` findings go to `Parked`, unscored.
231
+ Rejecting is a statement about the code, so it always carries a `path:line`. Never reject for being unconvinced. Apart from choosing among the reporting reviewers' values, never promote, demote, or re-time a finding. Confirmed and agreed `park` findings go to `Parked`, unscored.
230
232
 
231
233
  ## Step 4 — Merge and write
232
234
 
233
235
  1. **Read `references/review-calibration.md`** (next to this file) and follow its report section — you are the one writing the file, and it fixes the Coverage sentence, the per-finding line format, the Score table columns, and the total row. The reviewers were given it for their verdicts; the report obeys it too.
234
- 2. **Dedupe across axes and reviewers.** The same defect surfaced by two axes or two reviewers stays once, under the rule that explains it best, and each finding says how it was settled: `agreed`, `graded by orchestrator`, or `confirmed by orchestrator`.
235
- 3. **Severity is the reviewers'; truth is yours.** The merge never re-grades or re-times a finding except by choosing between two reviewers' values in Step 3.7.
236
+ 2. **Dedupe across axes and reviewers.** The same defect surfaced by multiple axes or reviewers stays once, under the rule that explains it best, and each finding says how it was settled: `agreed`, `graded by orchestrator`, or `confirmed by orchestrator`.
237
+ 3. **Severity is the reviewers'; truth is yours.** The merge never re-grades or re-times a finding except by choosing among reporting reviewers' values in Step 3.7.
236
238
  4. **Write the report to `reviewPath`** with the Write tool (it creates the parent directories). Frontmatter fields, in this order:
237
239
 
238
240
  ```yaml
@@ -122,8 +122,8 @@ Merged and adjudicated by the orchestrator, written to `reviewPath`. Sections, i
122
122
  - **Parked** — `park` findings, with their severity, not scored.
123
123
  - **Rejected** — findings the orchestrator's adjudication disproved or that cite no changed line: the reviewer's claim in one line, then the contradicting `path:line` and what it shows. Not scored.
124
124
 
125
- - **Coverage** — two or three lines: the reviewers (`provider/model`, one or two); N changed files → S `structural` / F `semantic` / T `state-and-tests` / G `general` cells, all verdicted by every reviewer; M files excluded with reasons; the applied packs, and any pack that was unavailable; and how the findings were settled — agreed, graded by the orchestrator, confirmed by the orchestrator, rejected. The four cell counts are at the census's granularity — one cell per target per axis. Also show grouped cells expected and covered per reviewer, list any missing rule IDs and count reasoned applicability exclusions. Never present the number of rule flags as the number of independent review targets.
126
- - **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + `kind` + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix, the execution `failure` or design `impact`, and supporting `evidence`. Its note then says how it was settled: `agreed`, `graded by orchestrator` (with both reviewers' values), or `confirmed by orchestrator`.
125
+ - **Coverage** — two or three lines: the reviewers (`provider/model`, one to three); N changed files → S `structural` / F `semantic` / T `state-and-tests` / G `general` cells, all verdicted by every reviewer; M files excluded with reasons; the applied packs, and any pack that was unavailable; and how the findings were settled — agreed, graded by the orchestrator, confirmed by the orchestrator, rejected. The four cell counts are at the census's granularity — one cell per target per axis. Also show grouped cells expected and covered per reviewer, list any missing rule IDs and count reasoned applicability exclusions. Never present the number of rule flags as the number of independent review targets.
126
+ - **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + `kind` + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix, the execution `failure` or design `impact`, and supporting `evidence`. Its note then says how it was settled: `agreed`, `graded by orchestrator` (with every reporting reviewer's values), or `confirmed by orchestrator`.
127
127
  - **Score** — every confirmed `now` finding gets a row, and the table is emitted even when there are none, with a single total row reading 0:
128
128
 
129
129
  ```
@@ -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 directly from the current agent session. Trigger words include "okstra run", "okstra start", "start okstra", "begin okstra task", "run okstra in this session", "okstra here", "continue on", and "run the next phase".
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".
4
4
  ---
5
5
 
6
6
  # OKSTRA Run (in-session)
@@ -17,6 +17,25 @@ Launch an okstra task — gather inputs interactively via the **wizard state mac
17
17
 
18
18
  - The user is inside a supported agent host and asks to start an okstra task ("run okstra here", "start an error-analysis on this branch", "okstra implementation-planning for INV-1234").
19
19
  - Continue an existing task (next phase) without leaving the current agent session.
20
+ - Configure global worker defaults or project overrides without starting a task.
21
+
22
+ ## Worker settings mode
23
+
24
+ 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.
25
+
26
+ Use the host identity and live semantic-function declaration from Step 1. Settings do not start a lead or require a configured project. To discover the current project's registration, use `okstra config show --scope project --cwd <absolute-current-directory>`; when its project entry is unavailable, omit both project flags below. Do not start `/okstra-setup` for a global settings request.
27
+
28
+ Get a state path with `okstra wizard new-state-file`, then initialize with literal values:
29
+
30
+ ```bash
31
+ okstra wizard init --worker-settings --state-file /absolute/state.json --host-runtime <host-runtime> --available-function plain_text_input
32
+ ```
33
+
34
+ For a registered project, also pass its `--project-root` and `--project-id`. The response includes the absolute `relayContract` path and `runtime`. Read that contract and compute the allowed live-function intersection using Step 1's relay rules. If the intersection includes additional functions, initialize the same still-unanswered settings state once more with those `--available-function` flags. Settings initialization does not write configuration.
35
+
36
+ Relay `next` through the existing prompt loop and submit with `okstra wizard step --state-file <literal-path> --answer <literal-answer>`. The wizard shows all role summaries together and lets the user edit only the roles they choose. Project inheritance, explicit zero workers, and save validation belong to the wizard. Changes remain drafts until the user chooses Save on its review screen.
37
+
38
+ For settings, `kind: done` means the settings transaction finished: show `next.label` and stop. `kind: aborted` means no settings were saved. Do not continue to launch Step 5, `outcome`, `render-args`, or `render-bundle` in either case. Resume ordinary task launching only on a separate user request.
20
39
 
21
40
  ## When NOT to Use
22
41
 
@@ -208,6 +227,7 @@ Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How
208
227
  That is the entire interactive flow. The wizard handles:
209
228
 
210
229
  - project report language before task selection: when `.okstra/project.json` has no `reportLanguage` value, ask for a language tag and save the answer to that file. An existing value skips this question. Prompt rendering and progress estimation do not save a language,
230
+ - saved worker rosters: `workerDefaults` in the project configuration replaces that role's global array in `~/.okstra/config.json`. The array fixes both models and count; an empty array explicitly disables an optional role. Valid configured roles skip their selection screens without a separate defaults question. Missing or unavailable roles alone are asked. The confirmation shows the count, models, source, and disabled roles; Edit changes only this run. Explicit inputs and an explicitly reused previous roster take precedence. `modelDefaults` remains a candidate-order preference and does not skip screens. Dynamic verifiers retain their source assignments,
211
231
  - new-vs-existing task split (remaining work — `workStatus != done` — top-3 newest recommendations + Enter directly), task-group / task-id slug validation (task-group offers the top-3 newest candidates combining recent task use + recent `.okstra/briefs/<group>/` creation activity + Enter directly; task-id offers the top-3 recent candidates from the same group + Enter directly),
212
232
  - task-type pick (3 options + Enter directly; Enter directly is validated against the full task-type whitelist in a follow-up `text` step). **For a brand-new task the brief is asked first** and the three options are entry phases only (`requirements-discovery` / `improvement-discovery` / `project-analysis` / `feature-analysis` / `change-impact-analysis` / `error-analysis`) — a new task-key has no approved plan, no implementation and no commits, so `implementation`, `final-verification` and `release-handoff` cannot be entered there; the recommended slot comes from the selected brief's `Recommended next phase:` line and falls back to `requirements-discovery` when the brief carries none. For an existing task-key what fills those three depends on `workflow.nextRecommendedPhase` — an object `{phase, status, rationale}`, not a phase-name string. `status: ready` gives the classic trio: its `phase` marked recommended, re-run the current phase, the lifecycle's next step. Any other status contributes nothing at all, since both the recommended slot and the next-step slot derive from that phase — re-run the current phase becomes the first option and the remaining slots fill unlabelled from recently used task-types and then the whitelist. Never recover a phase name from a non-`ready` pointer and propose it yourself: prepare deliberately lowers the pointer to `pending` while its run is unfinished, and the missing recommendation is that signal,
213
233
  - brief path — **for a new task it is asked right after task-group, before the task-type** (it is the only input that says what the task is, and the task-type recommendation reads it); for an existing task it is **asked only for entry task-types (requirements-discovery / error-analysis / improvement-discovery / project-analysis / feature-analysis / change-impact-analysis)** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, sorted by the newer of file-created/modified time and latest task-catalog use; direct input last; `Keep / Change` for existing entry tasks). `project-analysis`, `feature-analysis`, and `change-impact-analysis` are brief entry task types. On an existing task a downstream lifecycle task-type auto carries in the manifest's brief, and when no registered brief exists a `brief_carry` 3-option prompt appears (recommend switching to entry / Enter directly / Abort). `release-handoff` has no brief step of its own — a new-task run answers the brief before the type is known, and the brief is dropped at render time, so prepare always generates the input document that cites the verification report,