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.
- package/README.md +1 -0
- package/dist/commands/execute/wizard.mjs +12 -15
- package/dist/commands/execute/wizard.mjs.map +1 -1
- package/docs/cli.md +29 -5
- package/docs/project-structure-overview.md +1 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/code-review.json +1 -1
- package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
- package/runtime/prompts/wizard/prompts.ko.json +44 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
- package/runtime/python/okstra_ctl/code_review_coverage.py +70 -18
- package/runtime/python/okstra_ctl/code_review_target.py +77 -53
- package/runtime/python/okstra_ctl/correction_cli.py +6 -5
- package/runtime/python/okstra_ctl/correction_round.py +1 -1
- package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
- package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
- package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
- package/runtime/python/okstra_ctl/run.py +15 -1
- package/runtime/python/okstra_ctl/stage_done.py +5 -4
- package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
- package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
- package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
- package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
- package/runtime/python/okstra_ctl/wizard/render.py +2 -2
- package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
- package/runtime/python/okstra_ctl/wizard/state.py +55 -14
- package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
- package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
- package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
- package/runtime/python/okstra_ctl/write_policy.py +33 -18
- package/runtime/skills/okstra-code-review/SKILL.md +25 -23
- package/runtime/skills/okstra-code-review/references/review-calibration.md +2 -2
- 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
|
|
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.
|
|
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>
|
|
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
|
-
**
|
|
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
|
|
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
|
|
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**
|
|
159
|
+
it. **Every reviewer receives the same brief** and reviews every cell independently. Every brief carries:
|
|
158
160
|
|
|
159
|
-
- the diff
|
|
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.**
|
|
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** —
|
|
219
|
-
- **Graded differently** —
|
|
220
|
-
- **One-sided** —
|
|
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
|
|
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
|
|
235
|
-
3. **Severity is the reviewers'; truth is yours.** The merge never re-grades or re-times a finding except by choosing
|
|
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
|
|
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
|
|
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
|
|
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,
|