okstra 0.229.0 → 0.231.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 -5
- package/dist/cli-registry.mjs +0 -18
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/lifecycle/doctor.mjs +0 -15
- package/dist/commands/lifecycle/doctor.mjs.map +1 -1
- package/dist/lib/skill-catalog.mjs +4 -4
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/docs/architecture/storage-model.md +168 -18
- package/docs/architecture.md +15 -14
- package/docs/coding-rules.md +15 -0
- package/docs/contributor-change-matrix.md +5 -5
- package/docs/project-structure-overview.md +13 -19
- package/package.json +2 -3
- package/runtime/BUILD.json +2 -2
- package/runtime/bin/lib/okstra/interactive.sh +2 -1
- package/runtime/prompts/coding-preflight/clean-code.md +8 -0
- package/runtime/prompts/coding-preflight/overview.md +1 -0
- package/runtime/prompts/launch.template.md +7 -5
- package/runtime/prompts/lead/convergence.md +4 -4
- package/runtime/prompts/lead/okstra-lead-contract.md +19 -18
- package/runtime/prompts/lead/phase-routing.md +1 -1
- package/runtime/prompts/lead/report-writer.md +3 -3
- package/runtime/prompts/lead/team-contract.md +3 -3
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
- package/runtime/python/okstra_ctl/agent/invocation.py +190 -9
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
- package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
- package/runtime/python/okstra_ctl/cmux.py +4 -2
- package/runtime/python/okstra_ctl/code_review_census.py +194 -0
- package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
- package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
- package/runtime/python/okstra_ctl/code_review_target.py +38 -2
- package/runtime/python/okstra_ctl/conformance.py +30 -0
- package/runtime/python/okstra_ctl/conformance_evidence.py +316 -0
- package/runtime/python/okstra_ctl/correction_round.py +19 -13
- package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
- package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
- package/runtime/python/okstra_ctl/generated_input.py +21 -0
- package/runtime/python/okstra_ctl/ids.py +1 -41
- package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
- package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
- package/runtime/python/okstra_ctl/locks.py +28 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
- package/runtime/python/okstra_ctl/paths.py +90 -33
- package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
- package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
- package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
- package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +5 -4
- package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +5 -4
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +6 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +4 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +23 -7
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +6 -4
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +152 -30
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -12
- package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
- package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
- package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
- package/runtime/python/okstra_ctl/plan_items.py +28 -0
- package/runtime/python/okstra_ctl/process_group.py +26 -3
- package/runtime/python/okstra_ctl/qa_commands.py +5 -1
- package/runtime/python/okstra_ctl/recap.py +1 -2
- package/runtime/python/okstra_ctl/render.py +25 -2
- package/runtime/python/okstra_ctl/report_assembly.py +102 -1
- package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
- package/runtime/python/okstra_ctl/report_finalize.py +3 -3
- package/runtime/python/okstra_ctl/report_inputs.py +28 -0
- package/runtime/python/okstra_ctl/report_narrative.py +12 -3
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
- package/runtime/python/okstra_ctl/run.py +40 -20
- package/runtime/python/okstra_ctl/stage_close.py +52 -6
- package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
- package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
- package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
- package/runtime/python/okstra_ctl/verification_capture.py +291 -0
- package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
- package/runtime/python/okstra_ctl/verification_dispatch.py +136 -0
- package/runtime/python/okstra_ctl/verification_evidence.py +671 -0
- package/runtime/python/okstra_ctl/verification_generation.py +34 -16
- package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
- package/runtime/python/okstra_ctl/verification_inputs.py +83 -2
- package/runtime/python/okstra_ctl/verification_invocation.py +140 -0
- package/runtime/python/okstra_ctl/verification_target.py +10 -3
- package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
- package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
- package/runtime/python/okstra_ctl/wizard/render.py +2 -1
- package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
- package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
- package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
- package/runtime/python/okstra_ctl/worker_runner.py +1 -1
- package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
- package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
- package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
- package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
- package/runtime/schemas/final-report-v3.0.schema.json +184 -1
- package/runtime/skills/okstra-code-review/SKILL.md +7 -5
- package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
- package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +11 -7
- package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
- package/runtime/skills/okstra-setup/SKILL.md +2 -3
- package/runtime/templates/reports/html/i18n/en.json +7 -0
- package/runtime/templates/reports/html/i18n/ko.json +7 -0
- package/runtime/validators/validate-run.py +130 -20
- package/runtime/validators/validate-workflow.sh +1 -1
- package/docs/cli.md +0 -1060
- package/docs/container.md +0 -100
- package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
- package/docs/performance-improvement-plan-v2.md +0 -369
- package/runtime/python/okstra_ctl/container.py +0 -702
- package/runtime/python/okstra_ctl/rollup.py +0 -241
- package/runtime/python/okstra_ctl/usage_report.py +0 -362
- package/runtime/skills/okstra-container-build/SKILL.md +0 -139
- package/runtime/skills/okstra-inspect/SKILL.md +0 -100
- package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
- package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
- package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
- package/runtime/skills/okstra-inspect/facets/history.md +0 -86
- package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
- package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
- package/runtime/skills/okstra-inspect/facets/report.md +0 -57
- package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
- package/runtime/skills/okstra-inspect/facets/status.md +0 -163
- package/runtime/skills/okstra-inspect/facets/time.md +0 -57
- package/runtime/skills/okstra-rollup/SKILL.md +0 -75
- package/runtime/skills/okstra-usage/SKILL.md +0 -71
package/docs/cli.md
DELETED
|
@@ -1,1060 +0,0 @@
|
|
|
1
|
-
# okstra — CLI Argument and Option Manual
|
|
2
|
-
|
|
3
|
-
> This document supplements [README.md](../README.md). For internal architecture and storage/workflow contracts, see [architecture.md](architecture.md).
|
|
4
|
-
>
|
|
5
|
-
> This manual covers the phase-execution flags of `okstra.sh`. For the subcommand reference of the separate `okstra container` entry point, see [container.md](container.md).
|
|
6
|
-
|
|
7
|
-
The Node CLI requires Node.js 22 or newer. Its TypeScript sources are compiled from `src/**/*.mts` to `dist/**/*.mjs`; `bin/okstra` executes the compiled files.
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## Index
|
|
12
|
-
|
|
13
|
-
- [Command forms](#command-forms)
|
|
14
|
-
- [Required arguments](#required-arguments)
|
|
15
|
-
- [`--project-id`](#--project-id)
|
|
16
|
-
- [`--task-group`](#--task-group)
|
|
17
|
-
- [`--task-id`](#--task-id)
|
|
18
|
-
- [`--task-type`](#--task-type)
|
|
19
|
-
- [`--task-brief`](#--task-brief)
|
|
20
|
-
- [`--discussion-start`](#--discussion-start)
|
|
21
|
-
- [`--yes`](#--yes)
|
|
22
|
-
- [Optional arguments and options](#optional-arguments-and-options)
|
|
23
|
-
- [`--task-key`](#--task-key)
|
|
24
|
-
- [`--clarification-response`](#--clarification-response)
|
|
25
|
-
- [`--selected-direction`](#--selected-direction)
|
|
26
|
-
- [`--preselected-direction`](#--preselected-direction)
|
|
27
|
-
- [`--reverify-scope`](#--reverify-scope)
|
|
28
|
-
- [`--resume-clarification`](#--resume-clarification)
|
|
29
|
-
- [`--project-root`](#--project-root)
|
|
30
|
-
- [`--analysis-target`](#--analysis-target)
|
|
31
|
-
- [`--evidence-inputs`](#--evidence-inputs)
|
|
32
|
-
- [`--directive`](#--directive)
|
|
33
|
-
- [`--fix-cycle`](#--fix-cycle)
|
|
34
|
-
- [`--reasoning-effort`](#--reasoning-effort)
|
|
35
|
-
- [`--role-count`](#--role-count)
|
|
36
|
-
- [`--role-model`](#--role-model)
|
|
37
|
-
- [`--lead-runtime`](#--lead-runtime)
|
|
38
|
-
- [`--claude-model`](#--claude-model)
|
|
39
|
-
- [`--lead-model`](#--lead-model)
|
|
40
|
-
- [`--codex-model`](#--codex-model)
|
|
41
|
-
- [`--antigravity-model`](#--antigravity-model)
|
|
42
|
-
- [`--report-writer-model`](#--report-writer-model)
|
|
43
|
-
- [`--executor`](#--executor)
|
|
44
|
-
- [`--critic`](#--critic)
|
|
45
|
-
- [`--approved-plan`](#--approved-plan)
|
|
46
|
-
- [`--approve`](#--approve)
|
|
47
|
-
- [`--work-category`](#--work-category)
|
|
48
|
-
- [`--base-ref`](#--base-ref)
|
|
49
|
-
- [`--related-tasks`](#--related-tasks)
|
|
50
|
-
- [`--render-only`](#--render-only)
|
|
51
|
-
- [`--no-plan-verification`](#--no-plan-verification)
|
|
52
|
-
- [`--terminal-backend`](#--terminal-backend)
|
|
53
|
-
- [Interactive input flow](#interactive-input-flow)
|
|
54
|
-
- [Confirmation flow](#confirmation-flow)
|
|
55
|
-
- [`okstra` Node CLI — introspection subcommands](#okstra-node-cli--introspection-subcommands)
|
|
56
|
-
- [`okstra design-prep`](#okstra-design-prep)
|
|
57
|
-
- [Live-log sidecar](#live-log-sidecar)
|
|
58
|
-
|
|
59
|
-
---
|
|
60
|
-
|
|
61
|
-
## Command forms
|
|
62
|
-
|
|
63
|
-
Base command for initial entry with full arguments:
|
|
64
|
-
|
|
65
|
-
```bash
|
|
66
|
-
scripts/okstra.sh [--render-only] [--yes] [--no-plan-verification] [--terminal-backend cmux-pane|cli-wrapper] --task-type <task-type> [--role-count <role>=<N>] [--role-model <role>=<modelRef>] [--lead-runtime <host-id-or-alias>] [--lead-provider <provider>] [--lead-model <model>] [--worker-model provider=model,...] [--report-writer-provider <provider>] [--report-writer-model <model>] [--executor claude|codex|antigravity|grok|kimi] [--critic claude|codex|antigravity|grok|kimi] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--base-ref <branch|tag|sha>] [--clarification-response <previous-final-report>] [--selected-direction <selection-final-report.md>] [--preselected-direction <direction and citation>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> (--task-brief <brief-path> | --discussion-start <start-input>) [--directive <directive>] [--fix-cycle <yes|no>] [--reasoning-effort low|medium|high|xhigh]
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
Analysis input ownership is narrower than the base shell command. The `/okstra-run` wizard collects `--analysis-target` and `--evidence-inputs` values and passes them internally to `node bin/okstra render-bundle`. `scripts/okstra.sh` does not accept either flag. Because `feature-analysis` requires a target, start that task type with the in-host skill; the two option sections below document the internal Node render inputs, not standalone shell options.
|
|
70
|
-
|
|
71
|
-
Short form for a later phase when an existing task-manifest.json is available:
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> [--task-type <task-type>]
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
Immediately resume after answering clarification items:
|
|
78
|
-
|
|
79
|
-
```bash
|
|
80
|
-
scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
The following additional rules apply in an interactive terminal:
|
|
84
|
-
|
|
85
|
-
- Missing required arguments are read directly from stdin.
|
|
86
|
-
- Once all inputs are available, a summary is shown before execution.
|
|
87
|
-
- Creation or execution proceeds only when you enter `y` or `yes`.
|
|
88
|
-
- Non-interactive runs do not prompt for missing arguments and exit with an error instead.
|
|
89
|
-
- `--yes` skips both prompts and confirmation, but all required arguments must already be present.
|
|
90
|
-
- Precedence is `explicit CLI argument > interactive prompt or non-interactive error`.
|
|
91
|
-
|
|
92
|
-
## Required arguments
|
|
93
|
-
|
|
94
|
-
### `--project-id`
|
|
95
|
-
|
|
96
|
-
A globally unique project ID. On the first run, it self-registers in `<PROJECT_ROOT>/.okstra/project.json`. On later runs from the same PROJECT_ROOT, okstra exits immediately if the argument differs from the stored `projectId`.
|
|
97
|
-
|
|
98
|
-
Examples:
|
|
99
|
-
|
|
100
|
-
- `sample-project-v2-api`
|
|
101
|
-
- `jobs`
|
|
102
|
-
|
|
103
|
-
### `--task-group`
|
|
104
|
-
|
|
105
|
-
A logical group for related tasks.
|
|
106
|
-
|
|
107
|
-
Examples:
|
|
108
|
-
|
|
109
|
-
- `feature-8858`
|
|
110
|
-
- `bugfix-auth`
|
|
111
|
-
- `tasks`
|
|
112
|
-
|
|
113
|
-
### `--task-id`
|
|
114
|
-
|
|
115
|
-
A stable task identifier that can be reused within the same group.
|
|
116
|
-
|
|
117
|
-
Examples:
|
|
118
|
-
|
|
119
|
-
- `email-recipient-loss`
|
|
120
|
-
- `8852`
|
|
121
|
-
|
|
122
|
-
### `--task-type`
|
|
123
|
-
|
|
124
|
-
The single input that determines the purpose of this run, profile selection, run-directory segment, and lifecycle phase routing.
|
|
125
|
-
For standard values and phase-specific responsibilities, see [Task type](#--task-type) above.
|
|
126
|
-
|
|
127
|
-
The lifecycle task types run in this order:
|
|
128
|
-
|
|
129
|
-
| task type | Responsibility | Normal handoff |
|
|
130
|
-
|---|---|---|
|
|
131
|
-
| `requirements-discovery` | Fix the requirement ledger and decide whether cause analysis is needed. | `error-analysis` or `implementation-option-selection` |
|
|
132
|
-
| `error-analysis` | Establish a credible cause and counter-evidence. | `implementation-option-selection` or continued `error-analysis` |
|
|
133
|
-
| `implementation-option-selection` | Compare or validate read-only directions and expose only exact-coverage candidates. | `implementation-planning` after direction confirmation |
|
|
134
|
-
| `implementation-planning` | Realize one selected direction as files, stages, validation, and rollback. | `implementation` after separate plan approval |
|
|
135
|
-
| `implementation` | Execute one approved stage. | `final-verification` |
|
|
136
|
-
| `final-verification` | Verify acceptance and classify any cause, direction, or plan defect. | `release-handoff`, `error-analysis`, `implementation-option-selection`, or `implementation-planning` |
|
|
137
|
-
| `release-handoff` | Perform only the user-selected delivery action. | done or follow-up |
|
|
138
|
-
|
|
139
|
-
#### `--task-type technical-verification`
|
|
140
|
-
|
|
141
|
-
`technical-verification` is an optional experiment phase outside the normal phase sequence. It tests explicitly classified unresolved technical facts from the same task's implementation-option-selection report. Supply that report's `.data.json` through `--clarification-response`; no selected direction is needed. Unresolved user decisions still block entry, and candidates with safety blockers are excluded.
|
|
142
|
-
|
|
143
|
-
The run freezes source identity and fact IDs under `state/technical-verification-input-<seq>.json`. Workers write plans, source copies, dependency changes and command logs only under `runs/technical-verification/experiments/<seq>/<worker-id>/`. Results distinguish supported, refuted, inconclusive and not-run facts. Report assembly checks the frozen identities and retained command evidence before publication.
|
|
144
|
-
|
|
145
|
-
The only next phase is `implementation-option-selection`. Carry the verification report into that comparison with `--clarification-response`; the wizard recommends it when it refers to the current comparison report. Fresh independent feasibility votes decide candidate validity. Experimental evidence does not approve adoption or expand a pilot into production rollout.
|
|
146
|
-
|
|
147
|
-
#### `--task-type improvement-discovery`
|
|
148
|
-
|
|
149
|
-
`improvement-discovery` is a sidetrack entry point outside `PHASE_SEQUENCE`. It uses multi-worker consensus to find improvement candidates within the codebase scope and lens allowlist.
|
|
150
|
-
|
|
151
|
-
- Input: a brief with the frontmatter marker `scope: codebase`.
|
|
152
|
-
- `priority-lenses`: one to four values. The lens allowlist is the `LENSES` constant in `scripts/okstra_ctl/phases/improvement_discovery/lenses.py`.
|
|
153
|
-
- `scan-scope`: one or more paths.
|
|
154
|
-
- `out-of-scope`: optional.
|
|
155
|
-
- `candidate-cap`: 1–12; default 8.
|
|
156
|
-
- Output: the `## 5.9 Improvement Candidates` table with 11 columns: Cand ID / Lens / Title / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Expected behavior after / Evidence.
|
|
157
|
-
- Verdict Token: `analysis-complete` / `analysis-partial` / `blocked` — the shared analysis enum, which is what `schemas/final-report-v2.0.schema.json` admits. Finding no candidates is not a verdict: the run stays `analysis-complete` and records an empty candidate set with a `no-candidate` row per lens. (`candidates-ready` / `no-candidates` appear only in a schema-v1 legacy report's `## 7. Final Verdict`.)
|
|
158
|
-
- Routing: there is no automatic spin-off. The user selects candidates and starts each under a new task ID with `requirements-discovery`, `implementation-option-selection`, or `error-analysis`.
|
|
159
|
-
- Workers: the user selects one to five analysers (three recommended) plus the report writer. Fewer analysers means fewer lenses challenged by a second model.
|
|
160
|
-
- Primary-pass assignment: selected analyser instances are enumerated in `workerRoles` order, then the lead rotates the primary pass across the resolved priority lenses. Provider/model names do not affect the order, and every analyser still covers every resolved lens after its primary pass.
|
|
161
|
-
- Two bidirectional grilling points: an enhanced Step 4 in `okstra-brief-gen` with a budget of 8, and the lead's Phase 1.5 reflect-back with a budget of 12.
|
|
162
|
-
- Validator: `scripts/okstra_ctl/phases/improvement_discovery/validation.py` enforces the 11-part contract for an `improvement-discovery` final report.
|
|
163
|
-
- Because an `improvement-discovery` run is not in `PHASE_SEQUENCE`, its report has no routing field to project from, so the run leaves `workflow.nextRecommendedPhase` `pending` with no phase. The `--task-key` short form therefore cannot fill `--task-type` after one.
|
|
164
|
-
|
|
165
|
-
#### Analysis sidetrack task types
|
|
166
|
-
|
|
167
|
-
The three read-only analysis types are independent sidetracks outside `PHASE_SEQUENCE`:
|
|
168
|
-
|
|
169
|
-
| task type | Purpose |
|
|
170
|
-
|---|---|
|
|
171
|
-
| `project-analysis` | Map the current project's components, dependencies, entry points, data stores, external systems, and feature index. |
|
|
172
|
-
| `feature-analysis` | Trace one existing feature through flows, domain rules, state changes, external interactions, and test coverage. |
|
|
173
|
-
| `change-impact-analysis` | Map the blast radius of a proposed change across preserved behavior, dependencies, tests, and operations. |
|
|
174
|
-
|
|
175
|
-
Each one starts from a brief and produces a report only. The target project is strictly read-only: no edits, tests, builds, migrations, or deployments. A run ends with `workflow.nextRecommendedPhase` `pending` and carrying no phase; it does not advance the normal phase sequence.
|
|
176
|
-
|
|
177
|
-
### `--analysis-target`
|
|
178
|
-
|
|
179
|
-
At the `node bin/okstra render-bundle` boundary, `--analysis-target` is required only for `feature-analysis`. It accepts either a free-text feature boundary or a `PF-NNN` ID from a selected `project-analysis` feature index. A `PF-NNN` value must match exactly one feature in the selected project-context evidence. `project-analysis`, `change-impact-analysis`, and non-analysis task types reject this render input.
|
|
180
|
-
|
|
181
|
-
### `--evidence-inputs`
|
|
182
|
-
|
|
183
|
-
At the `node bin/okstra render-bundle` boundary, `--evidence-inputs` accepts a comma-separated list of prior analysis final-report paths. Relative paths resolve from the target project root, selection order is preserved, and duplicate paths are rejected. The allowed relationships are:
|
|
184
|
-
|
|
185
|
-
| Consumer and source | Stored relation |
|
|
186
|
-
|---|---|
|
|
187
|
-
| `feature-analysis` ← `project-analysis` | `project-context` |
|
|
188
|
-
| `change-impact-analysis` ← `project-analysis` | `project-context` |
|
|
189
|
-
| `change-impact-analysis` ← `feature-analysis` | `feature-baseline` |
|
|
190
|
-
|
|
191
|
-
`project-analysis` accepts no evidence inputs. `feature-analysis` and `change-impact-analysis` may omit evidence, but every supplied report must match one of the relationships above.
|
|
192
|
-
|
|
193
|
-
Only `accepted` reports appear in automatic evidence choices. An explicitly selected, otherwise valid unreviewed report is recorded as `user-unverified`; `revision-requested` and `rejected` reports are rejected as evidence. A revision request instead makes the wizard prioritize a same-task, same-type full rerun. The selection is snapshotted in `run-manifest.evidenceInputs` with source task/run identity, relation, review status, source commit, and freshness.
|
|
194
|
-
|
|
195
|
-
Analysis reports expose four independent meanings. The report verdict is `analysis-complete`, `analysis-partial`, or `blocked`. The `Analysis Review` sidecar status is `accepted`, `revision-requested`, or `rejected`. Evidence freshness is current (`exact` in the stored snapshot) or `stale`. Direct user verification of an explicitly selected unreviewed report is `user-unverified`. These are separate axes: for example, a complete report can still be rejected by its reviewer, and accepted evidence can become stale after the source commit changes.
|
|
196
|
-
|
|
197
|
-
### `--task-brief`
|
|
198
|
-
|
|
199
|
-
The path to the task brief that serves as the basis for analysis.
|
|
200
|
-
Relative paths are resolved from the target project root.
|
|
201
|
-
|
|
202
|
-
This argument does not apply to `release-handoff`: a brief is input to an entry phase
|
|
203
|
-
(requirements-discovery / error-analysis / improvement-discovery / project-analysis /
|
|
204
|
-
feature-analysis / change-impact-analysis), while
|
|
205
|
-
release-handoff preparation automatically creates an input document that cites the verification report
|
|
206
|
-
at `<task_root>/release-handoff-input.md` and uses it in place of a brief.
|
|
207
|
-
A non-empty `--task-brief` is rejected immediately for release-handoff.
|
|
208
|
-
It does not apply to `discussion` either; `--discussion-start` takes its place.
|
|
209
|
-
|
|
210
|
-
Examples:
|
|
211
|
-
|
|
212
|
-
- `.project-docs/linear/feature/8858/okstra-task-brief.md`
|
|
213
|
-
- `.project-docs/tasks/8852/BUG_REPORT.md`
|
|
214
|
-
|
|
215
|
-
When the task-group directory beside the brief holds `group-context.md` (`.okstra/briefs/<task-group>/group-context.md`, skeleton from `okstra group-context init`), preparation validates it, copies it to `instruction-set/task-group-context.md`, and the analysis packet carries its human sections as `## Task-Group Context` ahead of `## Task-Specific Brief Extract` and its okstra-written region — the group's start order and each sibling task's latest conclusion, recorded by `report-finalize` — as `## Task-Group Memory` after the brief extract, without this task's own entry. A file that still carries a template placeholder line fails preparation; delete it if the group needs no context. A file okstra created with only the memory region (no human section) passes as it is.
|
|
216
|
-
|
|
217
|
-
### `--discussion-start`
|
|
218
|
-
|
|
219
|
-
The start input of a `discussion` run, in place of `--task-brief`: a ticket or project link, a short
|
|
220
|
-
description, or the task's own key to continue its discussion. One research cycle runs per run, so the
|
|
221
|
-
next cycle, and a replacement roster, open in a continuation run prepared with
|
|
222
|
-
`--discussion-start <project-id:task-group:task-id>`. Without `--yes`, a missing value is asked for
|
|
223
|
-
instead of the brief path. `okstra.sh` forwards the value to prepare and passes no `--task-brief` for a
|
|
224
|
-
discussion, and does not fill the brief from the task manifest, whose brief is the input document
|
|
225
|
-
prepare wrote.
|
|
226
|
-
|
|
227
|
-
```bash
|
|
228
|
-
scripts/okstra.sh --task-type discussion --project-id jobs --task-group tasks --task-id 8852 --discussion-start jobs:tasks:8852
|
|
229
|
-
```
|
|
230
|
-
|
|
231
|
-
### `--yes`
|
|
232
|
-
|
|
233
|
-
Skips interactive prompts and confirmation.
|
|
234
|
-
|
|
235
|
-
The following values are required instead:
|
|
236
|
-
|
|
237
|
-
- `project-id`
|
|
238
|
-
- `task-group`
|
|
239
|
-
- `task-id`
|
|
240
|
-
- `task-type`
|
|
241
|
-
- `brief-path` (`discussion-start` for a discussion)
|
|
242
|
-
|
|
243
|
-
If any required argument is missing, the command exits immediately without prompting.
|
|
244
|
-
|
|
245
|
-
Example:
|
|
246
|
-
|
|
247
|
-
```bash
|
|
248
|
-
scripts/okstra.sh --yes --render-only --task-type error-analysis --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
## Optional arguments and options
|
|
252
|
-
|
|
253
|
-
### `--task-key`
|
|
254
|
-
|
|
255
|
-
A short form that supplies `--project-id`, `--task-group`, and `--task-id` together when starting a later phase for an existing task.
|
|
256
|
-
|
|
257
|
-
- Input format: `<project-id>:<task-group>:<task-id>`
|
|
258
|
-
- Behavior:
|
|
259
|
-
- Splits the value into the three IDs and populates `PROJECT_ID`, `TASK_GROUP`, and `TASK_ID`.
|
|
260
|
-
- If the same values are also provided explicitly, they are accepted only when they match; a conflict exits immediately with an error.
|
|
261
|
-
- If the task has a `task-manifest.json`, a missing `--task-brief` is filled from the manifest's `taskBriefPath`, and a missing `--task-type` is filled from `workflow.nextRecommendedPhase.phase` — but only while that pointer's `status` is `ready`.
|
|
262
|
-
- Without a manifest, as on initial entry, the normal missing-argument validation remains in effect and full arguments are required.
|
|
263
|
-
- Explicit arguments always take precedence over manifest values.
|
|
264
|
-
- Under any other `status` — `pending`, `blocked`, or `terminal` — the pointer names no runnable phase and `--task-type` is not filled automatically. Supply `--task-type` explicitly or supplement the brief, then rerun the command.
|
|
265
|
-
|
|
266
|
-
Examples:
|
|
267
|
-
|
|
268
|
-
```bash
|
|
269
|
-
scripts/okstra.sh --task-key jobs:tasks:8852
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
```bash
|
|
273
|
-
scripts/okstra.sh --task-key jobs:tasks:8852 --task-type final-verification
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
### `--clarification-response`
|
|
277
|
-
|
|
278
|
-
Carries a previous run's final report—with user answers filled inline in `## 1. Clarification Items`—into the next run.
|
|
279
|
-
|
|
280
|
-
- Input: a path matching `<previous-run>/reports/final-report-<task-type>-<seq>.md`.
|
|
281
|
-
- Behavior: copies the file to the current run's `instruction-set/clarification-response.md`. In Section 0, the lead updates the `Status` of previous `Q*` rows to `resolved` or `obsolete`, then continues.
|
|
282
|
-
- Use it after a phase such as `requirements-discovery`, `error-analysis`, or `implementation-planning` leaves unresolved questions or approval-blocking clarification. Fill in the answers, then carry the report into the next phase or a resume of the same phase.
|
|
283
|
-
|
|
284
|
-
Example:
|
|
285
|
-
|
|
286
|
-
```bash
|
|
287
|
-
scripts/okstra.sh \
|
|
288
|
-
--task-type implementation-planning \
|
|
289
|
-
--project-id jobs --task-group tasks --task-id 8852 \
|
|
290
|
-
--task-brief .project-docs/tasks/8852/BUG_REPORT.md \
|
|
291
|
-
--clarification-response .okstra/tasks/tasks/8852/runs/2026-04-29/error-analysis/reports/final-report-2026-04-29_10-15-30.md
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
### `--selected-direction`
|
|
295
|
-
|
|
296
|
-
Starts a new `implementation-planning` run from a validated `implementation-option-selection` final report. The option-selection report may contain at most three displayed directions. Every displayed direction has exact requirement coverage and exact scope precision: both percentages are 100, with no unmapped commitment or contradicted requirement.
|
|
297
|
-
|
|
298
|
-
In `candidate-comparison` mode, the user first confirms one displayed direction in the report's `DIRECTION SELECTION` response. Prepare validates the report, its sibling data JSON, the response sidecar, the selected option ID, and the source-data digest before writing `instruction-set/selected-direction.json`. In `preselected-validation` mode, the validated upstream direction is used without generating or selecting an alternative.
|
|
299
|
-
|
|
300
|
-
The direction decision does not approve the detailed plan. Planning produces a separate `approved: false` report, and implementation still requires explicit plan approval. A new planning run without `--selected-direction` is rejected. A same-task planning rerun instead uses `--clarification-response` with its prior planning report.
|
|
301
|
-
|
|
302
|
-
Example:
|
|
303
|
-
|
|
304
|
-
```bash
|
|
305
|
-
scripts/okstra.sh --task-type implementation-planning \
|
|
306
|
-
--selected-direction .okstra/tasks/tasks/8852/runs/implementation-option-selection/reports/final-report-implementation-option-selection-001.md \
|
|
307
|
-
--project-id jobs --task-group tasks --task-id 8852
|
|
308
|
-
```
|
|
309
|
-
|
|
310
|
-
### `--preselected-direction`
|
|
311
|
-
|
|
312
|
-
Sets an `implementation-option-selection` run to `preselected-validation`. The value is the one direction the run validates and the citation that fixed it, for example a spec revision or the upstream report's routing rationale. Without the flag the run is `candidate-comparison`. Prepare rejects the flag for any other task type.
|
|
313
|
-
|
|
314
|
-
The analysis packet always carries a `## Direction Selection Mode` section for this phase. It names the mode, quotes the preselected direction, and lists the next-phase instruction of the report passed through `--clarification-response`, because the clarification carry-in projects only that report's clarification rows. The `/okstra-run` wizard asks for the mode on every option-selection run.
|
|
315
|
-
|
|
316
|
-
Example:
|
|
317
|
-
|
|
318
|
-
```bash
|
|
319
|
-
scripts/okstra.sh --task-type implementation-option-selection \
|
|
320
|
-
--preselected-direction "One synchronous Lambda behind LicensePublishPort (spec rev. 4, task-brief.md Context)" \
|
|
321
|
-
--project-id jobs --task-group tasks --task-id 8852
|
|
322
|
-
```
|
|
323
|
-
|
|
324
|
-
### `--reverify-scope`
|
|
325
|
-
|
|
326
|
-
Pins how much of an `implementation-planning` clarification re-run is verified again. Like `--analysis-target` and `--evidence-inputs`, this is an internal `node bin/okstra render-bundle` input collected by the `/okstra-run` wizard — `scripts/okstra.sh` does not accept it.
|
|
327
|
-
|
|
328
|
-
- Accepted values — exactly three forms; anything else is rejected rather than read as a default:
|
|
329
|
-
- `auto` (or empty, the default) — leave the call to the lead's deterministic `okstra incremental-scope` decision.
|
|
330
|
-
- `full` — re-verify every stage. The lead still records the decision, passing `--full-reason "user requested full re-verification"`.
|
|
331
|
-
- a stage-number list such as `2,3` — the named stages enter the lead's `--impacted` set, unioned with whatever it resolves itself. The CLI's dependency closure and cutoff still apply on top, so a wide enough pin correctly resolves to full.
|
|
332
|
-
- Requires `--clarification-response`, and only `--task-type implementation-planning` accepts a non-empty value. Without a carried report there is no prior Stage Map to narrow against.
|
|
333
|
-
- The wizard asks for this when the re-run is narrowable **or** an answered `C-NNN` traces to no stage. An unlinked id does not freeze the run at full: the picker then offers stage numbers (recommended) or full, and omits `auto`. Direct stage input is validated against the prior report's Stage Map, so a number that plan never had is refused at the prompt. Empty input is auto only when every answered id already traces to a stage.
|
|
334
|
-
- The value reaches the lead as the `REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` tokens the "Clarification Response Carried In" section of the lead prompt reads. It narrows or widens the inputs to `okstra incremental-scope`; it does not bypass that decision.
|
|
335
|
-
|
|
336
|
-
### `--tdd-bypass`
|
|
337
|
-
|
|
338
|
-
Records a **user-acknowledged** TDD bypass for one plan stage: `"<stage>:<reason>"`. Like `--analysis-target` and `--reverify-scope`, this is an internal `node bin/okstra render-bundle` input collected by the `/okstra-run` wizard — `scripts/okstra.sh` does not accept it. Only `--task-type implementation-planning` applies it.
|
|
339
|
-
|
|
340
|
-
Every plan stage must open with a `RED:` step whose outcome is FAIL and reach a later `GREEN:` step (validator check S10c), and `tddExemption` waives that only for `doc-only`, `config-only`, or `pure-rename` work. A stage that is truthfully none of the three had no passable value, so the plan got through by filing the nearest category — the record then says something that is not true. This flag is the fourth reason, and it is the one the run cannot grant itself.
|
|
341
|
-
|
|
342
|
-
- Value form — `<stage>:<reason>` where `<stage>` is the Stage Map number and `<reason>` is the user's own words. The reason is stored **verbatim**; a malformed value or a non-positive stage number aborts `render-bundle` with a `PrepareError`.
|
|
343
|
-
- Effect — prepare writes `{stage, reason, acknowledgedBy: "user", at}` into `<task-root>/qa/tdd-bypass.json` (the same task-level `qa/` home as the conformance manifest and `self-mock-waivers.json`). Re-granting the same stage replaces its row.
|
|
344
|
-
- What it unlocks — that stage may declare `tddExemption: user-bypass — <reason>`. Check S10e accepts the token only while the ledger records the grant for that stage number, so a plan asserting it on its own fails exactly as an arbitrary reason does. The refusal message names this flag.
|
|
345
|
-
- Scope — per stage number, per task, and it persists across runs of that task. Remove the row from the ledger to withdraw the grant.
|
|
346
|
-
- Not a substitute for closing a landed stage. When a stage's product change is already committed and its conformance result is PASS but no `done` row exists, the recovery is `okstra stage-close --from-commit` (see [`docs/architecture.md`](architecture.md)), not a bypass.
|
|
347
|
-
|
|
348
|
-
### `--resume-clarification`
|
|
349
|
-
|
|
350
|
-
Immediately edits the final report from the previous `requirements-discovery` or `error-analysis` run and automatically reruns the same phase. You do not need to manage the `--clarification-response` path manually.
|
|
351
|
-
|
|
352
|
-
- Input: task identity supplied as `--project-id` + `--task-group` + `--task-id`, or as `--task-key <p>:<g>:<i>`.
|
|
353
|
-
- Sequence:
|
|
354
|
-
1. Automatically selects the latest timestamped file under the task's `runs/{requirements-discovery,error-analysis}/reports/final-report-*.md` paths.
|
|
355
|
-
2. Opens the file with `$EDITOR`, or `vi` when unset. Fill answers inline in the Section 5 `Q*` rows, save, and exit.
|
|
356
|
-
3. okstra invokes itself again with `exec` for the same task type and carries the edited file in through `--clarification-response`.
|
|
357
|
-
4. Confirmation, rendering, and Claude handoff then proceed as in a normal run.
|
|
358
|
-
- When an explicit `--task-type` is supplied, only that task type's reports are searched. Otherwise, okstra searches `error-analysis` and then `requirements-discovery` and uses the report with the later timestamp.
|
|
359
|
-
- It cannot be combined with `--render-only`, `--clarification-response`, or `--approved-plan`.
|
|
360
|
-
- Setting `EDITOR` to a non-interactive tool such as `true` skips answer editing and immediately reruns the task. This is recommended only for debugging.
|
|
361
|
-
|
|
362
|
-
Examples:
|
|
363
|
-
|
|
364
|
-
```bash
|
|
365
|
-
scripts/okstra.sh --resume-clarification --task-key jobs:tasks:8852
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
```bash
|
|
369
|
-
EDITOR=code\ -w scripts/okstra.sh --resume-clarification --project-id jobs --task-group tasks --task-id 8852
|
|
370
|
-
```
|
|
371
|
-
|
|
372
|
-
Internally, this is equivalent to:
|
|
373
|
-
|
|
374
|
-
```bash
|
|
375
|
-
$EDITOR <project-root>/.okstra/tasks/<group>/<id>/runs/<task-type>/reports/final-report-<latest>.md
|
|
376
|
-
scripts/okstra.sh --task-type <same-type> \
|
|
377
|
-
--project-id <p> --task-group <g> --task-id <i> \
|
|
378
|
-
--task-brief <from manifest> \
|
|
379
|
-
--clarification-response <edited final-report-<latest>.md>
|
|
380
|
-
```
|
|
381
|
-
|
|
382
|
-
### `--project-root`
|
|
383
|
-
|
|
384
|
-
The absolute path to the target project. When omitted, `okstra.sh` resolves it in this order:
|
|
385
|
-
|
|
386
|
-
1. Find the current directory or nearest ancestor containing `.okstra/project.json` and use it as PROJECT_ROOT.
|
|
387
|
-
2. If that fails, use the result of `git rev-parse --show-toplevel`.
|
|
388
|
-
3. If both fail, exit immediately with an error.
|
|
389
|
-
|
|
390
|
-
On the first run from the resolved PROJECT_ROOT, `<PROJECT_ROOT>/.okstra/project.json` is created automatically with this schema:
|
|
391
|
-
|
|
392
|
-
```json
|
|
393
|
-
{
|
|
394
|
-
"projectId": "<--project-id argument value>",
|
|
395
|
-
"projectRoot": "<resolved absolute path>",
|
|
396
|
-
"createdAt": "<ISO8601 UTC>",
|
|
397
|
-
"updatedAt": "<ISO8601 UTC>"
|
|
398
|
-
}
|
|
399
|
-
```
|
|
400
|
-
|
|
401
|
-
If the file already exists, okstra checks that `projectId` matches and updates only `projectRoot` and `updatedAt`. A mismatched `projectId` exits immediately, preventing two IDs from being used in the same directory.
|
|
402
|
-
|
|
403
|
-
User-added fields are preserved across that upsert, so optional settings can be hand-edited into the file. One of them is `architecture.style` — the project's declared architecture, one of `hexagonal`, `layered`, or `none` (default `none` when the field is absent, unrecognized, or unreadable):
|
|
404
|
-
|
|
405
|
-
```json
|
|
406
|
-
{
|
|
407
|
-
"projectId": "<--project-id argument value>",
|
|
408
|
-
"projectRoot": "<resolved absolute path>",
|
|
409
|
-
"createdAt": "<ISO8601 UTC>",
|
|
410
|
-
"updatedAt": "<ISO8601 UTC>",
|
|
411
|
-
"architecture": { "style": "hexagonal" }
|
|
412
|
-
}
|
|
413
|
-
```
|
|
414
|
-
|
|
415
|
-
Declaring a style promotes that architecture's placement rules from advisory to binding. Under `hexagonal`: a variation point that `implementation-planning` decides to extract has to be extracted behind a port (`interfaceKind: "port"` — validator-enforced; deciding *not* to extract a point stays legal, the style does not force extraction), the implementation executor loads `architectures/hexagonal.md` even when directory-shape detection did not match it, and the verifier grades a placement violation as a blocking `FAIL` rather than a recommendation. `layered` has no preflight pack resource; its binding invariant is dependency direction — an upper layer may import a lower one, never the reverse — and a reverse import is a blocking placement violation found by worker judgement, since no machine check reads layer names. Leaving the field out changes nothing — the style-agnostic planning rules (variation-point analysis and test seams) apply either way. See [`architecture.md`](architecture.md) § Project self-registration for the full two-layer model.
|
|
416
|
-
|
|
417
|
-
A second optional field is `reviewRulePacks` — an array of **absolute** paths to the project's own review rule packs (a team PR-review skill's `SKILL.md`, for instance). A pack otherwise reaches a run only when the task brief cites its exact path, so the team standard applied or not depending on who wrote the brief; declaring it here applies it to every run, and the brief citation keeps working alongside it. `implementation-planning`, the implementation executor's preflight, the implementation verifier, and `final-verification` all read it. A relative entry is dropped (a worker's cwd is a worktree, where it would name a different file), and `okstra doctor --phase <phase>` fails its `review rule packs` check when a declared path is not a readable file:
|
|
418
|
-
|
|
419
|
-
```json
|
|
420
|
-
{
|
|
421
|
-
"reviewRulePacks": ["/Users/me/.claude/skills/team-pr-reviewer/SKILL.md"]
|
|
422
|
-
}
|
|
423
|
-
```
|
|
424
|
-
|
|
425
|
-
Example:
|
|
426
|
-
|
|
427
|
-
```bash
|
|
428
|
-
scripts/okstra.sh --task-type error-analysis --project-id jobs --project-root /Volumes/Workspaces/workspace/projects/jobs ...
|
|
429
|
-
```
|
|
430
|
-
|
|
431
|
-
### Schedule generation skill
|
|
432
|
-
|
|
433
|
-
The public schedule entry point is the host skill `/okstra-schedule-gen [task-group]`; `stage-map` and `validate-schedule.py` are its backend contracts, not an additional schedule-generation shell command. For each candidate task, the skill branches on the `stage-map` `state` and `sourcePlanPath`, records the selected, completed, and full stage sets in a temporary `.selection.json`, and runs deterministic `--selection-json` validation before an independent narrative verifier. Only the same draft that passes both gates is promoted, and the temporary selection contract is removed after final validation.
|
|
434
|
-
|
|
435
|
-
### `--directive`
|
|
436
|
-
|
|
437
|
-
A free-text channel for passing user intent to the lead, workers, and downstream skills. The value is embedded in a `## Directive` section at the end of `instruction-set/analysis-material.md` and in `instruction-set/analysis-packet.md`, the analysis workers' primary input. It is also backed up to `instruction-set/directive.txt`.
|
|
438
|
-
|
|
439
|
-
Use it to:
|
|
440
|
-
|
|
441
|
-
- Override a default heuristic—for example, request a Gantt chart even for one XL task with two phases totaling about 10 days, or request an explicit reason for omitting one. `## Cumulative Timeline` has been removed from the schedule contract and is no longer a toggle.
|
|
442
|
-
- Direct the emphasis of analysis or planning—for example, prioritize rollout risks or report missing test coverage as a separate finding.
|
|
443
|
-
- Suggest Phase/Step divisions or day estimates in advance—for example, Part 1: 4d, measurement: 0.5d, Part 2: 4d, operations: 1d.
|
|
444
|
-
|
|
445
|
-
Interpretation rules:
|
|
446
|
-
|
|
447
|
-
- The lead and analysis workers read the compact intake (`active-run-context`, `analysis-packet.md`) first, so the directive propagates without separate work. `analysis-material.md` is a fallback when the packet is insufficient or source citations must be verified.
|
|
448
|
-
- A skill must give the user prompt **precedence** over its own contract—for example, the "Directive override (highest priority)" section of the `okstra-schedule-gen` skill. When a heuristic is overridden, the result document states that fact in one line.
|
|
449
|
-
|
|
450
|
-
Example:
|
|
451
|
-
|
|
452
|
-
```bash
|
|
453
|
-
scripts/okstra.sh --task-type implementation-planning ... \
|
|
454
|
-
--directive "Use two sequential phases (Part 1 ~4d, Part 2 ~5d) for ~10d total. Include a Gantt chart with the critical path."
|
|
455
|
-
```
|
|
456
|
-
|
|
457
|
-
### `--fix-cycle`
|
|
458
|
-
|
|
459
|
-
- `--fix-cycle <yes|no>` records whether re-entry into an entry phase (`requirements-discovery` / `error-analysis` / `implementation-option-selection` / `implementation-planning`) after completion through release-handoff is a bug-fix cycle. When omitted, no cycle is recorded. The `fix_cycle_confirm` step in the okstra-run wizard accepts the same input.
|
|
460
|
-
- `yes` opens a new cycle only when both conditions hold: the task type is an entry phase, and the manifest's `workflow.lastCompletedPhase` is `release-handoff` with delivery finished — a release-handoff that ended in `skip` or left a stage's PR `skipped` points the next phase back at `release-handoff`, and that task is refused. Preparation rejects the request if either condition is false. Once a cycle is open, later runs for the same task attach to it automatically without this flag.
|
|
461
|
-
|
|
462
|
-
### `--reasoning-effort`
|
|
463
|
-
|
|
464
|
-
- `--reasoning-effort <low|medium|high|xhigh>` sets the reasoning effort of every worker CLI the run starts. The value is stored as `reasoningEffort` in the run manifest, and `okstra-provider-exec.py` passes it on each dispatch: `--effort` to claude, `-c model_reasoning_effort=` to codex, and `--reasoning-effort` to grok. The `reasoning_effort` step in the okstra-run wizard asks for the same value after the role screens.
|
|
465
|
-
- When omitted, each CLI keeps its own configuration, and codex keeps the catalog's `high` for `gpt-6.1-sol`.
|
|
466
|
-
- antigravity, kimi and zai do not receive it. antigravity encodes the effort in the model identity (`gemini-3.8-flash-high`) and rejects `--effort` beside it, and that identity is fixed when roles are assigned. Whether the kimi CLI and z.ai's endpoint accept an effort setting has not been verified.
|
|
467
|
-
|
|
468
|
-
### `--lead-runtime`
|
|
469
|
-
|
|
470
|
-
Selects a lead adapter by registered host ID or alias. The default is `claude-code`. Terminal `okstra run <host-id-or-alias>` requests the same registry entry and verifies its `spawn-process` readiness before launch; an unavailable selected host is never replaced silently.
|
|
471
|
-
|
|
472
|
-
Lead runtime independence boundary:
|
|
473
|
-
|
|
474
|
-
- `claude-code`: the current default execution path. Claude Code v2.1.178 removed `TeamCreate`, and the session owns an implicit team. Workers are dispatched with `Agent(name: ..., run_in_background: true)` without `team_name`. `teamName` is audit/display metadata; Claude session JSONL is used for usage accounting.
|
|
475
|
-
- `codex`: the runtime marker for the Codex lead adapter. `okstra codex-run` owns `--render-only --lead-runtime codex` to prepare a task bundle, and the prepared run manifest can be passed to `okstra codex-dispatch` for CLI-backed worker execution.
|
|
476
|
-
- `antigravity`: the runtime marker for the Antigravity CLI lead adapter. The current Antigravity session owns the native lead, keeps Antigravity assignments native, and routes every other provider through the deterministic provider-process dispatcher.
|
|
477
|
-
- `grok` and `kimi`: registered native lead adapters for their corresponding CLIs. They can lead, analyse, and criticise, but they do not add executor, verifier, or report-writer worker roles.
|
|
478
|
-
- `external`: without Claude Code Teams, `--render-only --lead-runtime external` prepares the task bundle and external lead prompt. The lead manages the worker lifecycle with `okstra team dispatch`, `okstra team await`, and `okstra team teardown`. This path does not use `TeamCreate` / `Agent(...)` and uses artifact-only accounting.
|
|
479
|
-
|
|
480
|
-
Host IDs and providers are separate axes. Bundled and user-installed host adapters resolve from the registry; user adapters must be installed under `~/.okstra/adapters/hosts/<id>/` or `~/.okstra/adapters/providers/<id>/`. Project-local adapter code is not discovered.
|
|
481
|
-
|
|
482
|
-
The current Claude Code independence boundary covers the external lead prompt and `okstra team *` worker dispatch. non-render `okstra_ctl.run --lead-runtime external` remains blocked; a complete external lead driver remains separate future work. `--runtime external` only selects the runtime adapter. `okstra install` creates `~/.agents/skills/` by default and also installs Claude skills and agents when `~/.claude` exists. Selecting the `claude` worker still requires the local Claude CLI wrapper.
|
|
483
|
-
|
|
484
|
-
Host-runtime readiness is independent of worker selection. When `/okstra-setup`
|
|
485
|
-
creates `<PROJECT_ROOT>/.claude/settings.local.json` in an already-open Claude
|
|
486
|
-
Code session, that session may not have accepted workspace trust yet. The next
|
|
487
|
-
`/okstra-run` preflight stops before the wizard when trust is required or cannot
|
|
488
|
-
be verified. The default `okstra preflight` output is a fixed text projection
|
|
489
|
-
whose first line is `Okstra preflight: ready` or `Okstra preflight: failed`.
|
|
490
|
-
Success names the project ID, project root, runtime, readiness state, and relay
|
|
491
|
-
contract. Each adapter check retains its ID, status, and action as three
|
|
492
|
-
repeated lines. Failure names the stage, observed reason, and recovery action. The user runs
|
|
493
|
-
that recovery and repeats the command. This check applies only to a `claude-code` host; `codex`,
|
|
494
|
-
`antigravity`, and `external` hosts do not inspect Claude Code state, regardless of whether the
|
|
495
|
-
worker roster contains Claude, Codex, or Antigravity.
|
|
496
|
-
|
|
497
|
-
External automation uses `okstra preflight --machine`, which returns the
|
|
498
|
-
automation JSON contract with its existing exit codes. `--json` is a deprecated
|
|
499
|
-
one-release alias for `--machine`. Model-facing skills use the default text
|
|
500
|
-
projection and do not parse the machine response.
|
|
501
|
-
|
|
502
|
-
### Runtime auto-detection (`auto`)
|
|
503
|
-
|
|
504
|
-
`okstra run` defaults to `auto`. `src/lib/host-registry-client.mts` asks the Python host registry to resolve explicit IDs and aliases, the `OKSTRA_RUNTIME_HOST` environment declaration, or Claude Code skill handoff. It fails fast when no adapter claims the session. Installed CLI presence alone never selects a host.
|
|
505
|
-
|
|
506
|
-
- Inside a registered host, the installed `okstra-run` skill uses `current-session`, declares the live semantic function list, and reuses the session you are already in.
|
|
507
|
-
- From a terminal, `okstra run <host-id-or-alias>` uses `spawn-process` and starts the selected host CLI. The leading word is an alias for `--lead-runtime`.
|
|
508
|
-
- `okstra run external` does not start a lead — it orchestrates an all-CLI run through `okstra team`.
|
|
509
|
-
- Starting a lead whose CLI sandboxes itself prints what is given up and waits for a `y`; `--yes` answers it. Today only Codex asks, because a sandboxed lead can reach neither cmux nor the worker CLIs' own configuration.
|
|
510
|
-
- With `external` requested, `okstra run` orchestrates `render-bundle --lead-runtime external` -> `okstra team dispatch` -> `okstra team await`.
|
|
511
|
-
|
|
512
|
-
`doctor` and `render-bundle` also default to `auto`, but a plain terminal without a host signal must specify a host. `okstra install` and `ensure-installed` are exceptions. Installation places the shared runtime and skill targets based on agent homes rather than the runtime host, so it records the `auto` request and unresolved state in the manifest and continues even without a host signal. Skill copy targets depend on the presence of agent homes and the default Agent target policy, not runtime resolution. `~/.agents/skills/` is always created, and Claude skills/agents are installed when `~/.claude` exists. The host-aware `okstra-run` skill passes the current harness runtime explicitly; Claude-only maintenance skills continue to pass `--runtime claude-code` where that host is part of their contract.
|
|
513
|
-
|
|
514
|
-
`installed-runtimes.json` uses schemaVersion 2 and separates `installRequest`, `runtimeResolution`, `installedRuntimes`, and `installedAssets`. `installed-skills.json` uses a schemaVersion 2 target list with `provider`, `root`, and `skills` to record Claude and Agent skill targets; uninstall removes files according to this list. `codexAdapter` / `externalAdapter` retain read compatibility with v1 manifests only.
|
|
515
|
-
|
|
516
|
-
For a Codex lead dry run, use `okstra codex-run <args...>`. It adds `--render-only --lead-runtime codex` itself and prints the prepared task bundle and lead prompt without dispatching workers.
|
|
517
|
-
The generated team-state, run manifest, and task manifest point `leadEventsPath` to `runs/<task-type>/state/lead-events-<task-type>-<seq>.jsonl`; rendering records a `bundle-prepared` event.
|
|
518
|
-
Then `okstra worker-dispatch --project-root <dir> --run-manifest <run-manifest> [--workers <csv>]` reads each persisted assignment. `runner=native-session` rows stay with the current host; `runner=cli-wrapper` rows run through the registered provider process only after adjacent invocation metadata verifies. Without `--workers`, only CLI-backed analysis assignments are selected. Report writer is deferred to Phase 6 and must be dispatched explicitly with `--workers report-writer`; mixing it with analysis workers in one invocation is rejected before process creation. `okstra codex-dispatch` is a compatibility alias for this provider-neutral command. The report-writer provider and model still come from the manifest without a Codex-only opt-in flag; on success, postprocessing runs check-source → token-usage substitution → render-views → spawn-followups → validate-run in order.
|
|
519
|
-
|
|
520
|
-
The Codex worker (`--role-model analyser=codex/<model>`, `--codex-model`) and Codex lead runtime are separate. The former creates a worker assignment whose runner depends on the host; the latter selects Codex as the native lead boundary. On Claude Code the Codex worker uses a CLI wrapper, while on Codex it uses the host-native worker/session primitive.
|
|
521
|
-
|
|
522
|
-
> Every `--*-model` flag accepts only aliases registered in the provider mappings in `scripts/okstra_ctl/models.py`. An unregistered value is immediately rejected with `UnknownModelError`, preventing a contract violation where the manifest's `modelExecutionValue` differs from the actual execution value. Allowed values:
|
|
523
|
-
> - Claude (`--lead-model` / `--claude-model` / `--report-writer-model`): `fable`, `fable-5-1`, `claude-fable-5-1`, `fable-5`, `claude-fable-5`, `opus`, `opus-5`, `claude-opus-5`, `sonnet`, `sonnet-5`, `claude-sonnet-5`, `haiku`, `haiku-5-5`, `claude-haiku-5-5`
|
|
524
|
-
> - Codex (`--codex-model`): `gpt-6-astra`, `gpt-6.1-sol`, `gpt-6-luna`. The bundled default is `gpt-6.1-sol`, which okstra runs at `high` reasoning effort (`-c model_reasoning_effort=high`, overriding `~/.codex/config.toml`) for both workers and a launched lead. GPT-6 Sol, GPT-5.6 Sol, Terra, and Luna, `gpt-5.4-mini`, and `codex-auto-review` remain in the catalog for historical records but are not selectable. When the CLI model cache matches the running CLI version, dispatch rejects identifiers absent from that catalog rather than renaming them. A missing or mismatched cache leaves availability enforcement to the provider CLI; model selection does not guarantee account access.
|
|
525
|
-
> - Antigravity (`--antigravity-model`): `gemini-3.1-pro` (default), `gemini-4-argon`, `gemini-3.8-flash`, and their space-separated aliases. The antigravity worker uses the `agy` CLI to run Gemini-family models, so model IDs retain the `gemini-*` form.
|
|
526
|
-
> - Grok (`--worker-model grok=<model>`): `grok-4.7`
|
|
527
|
-
> - Kimi (`--worker-model kimi=<model>`): `kimi-k3`, `k3`, `k3-256k` and their registered display aliases
|
|
528
|
-
>
|
|
529
|
-
> Not every registered alias is offered for selection. A model whose `ModelSpec` sets `selectable=False` stays in the catalog — so served-model attestation and historical pricing still resolve it — but it is hidden from the wizard's role-model picker, from `okstra model list`, and from `--role-model`. `okstra model list` still prints them, marked `selectable: no` with the reason. Currently hidden: `claude/fable-5-1`, `claude/fable-5`, `claude/opus-5`, `claude/sonnet-5`, `claude/haiku-5-5` (each one the pinned twin of a channel entry that already appears; `claude/fable-5` is the previous served id, kept for attestation and pricing), `kimi/k3` (same model as `kimi/kimi-k3`), `codex/gpt-5.4-mini`, `codex/codex-auto-review`, `grok/grok-build-0.1`, `kimi/k3-256k`.
|
|
530
|
-
|
|
531
|
-
### `--role-count`
|
|
532
|
-
|
|
533
|
-
Sets how many slots open for one static role: `--role-count <role>=<N>`. Repeat the flag for each role. `N` must fall in that role's profile range `min..max`. Omit the flag to use the profile **recommended** count (not a separate roster default). Roles with `min == max` are fixed quantity and reject this flag. Dynamic roles and roles absent from the profile also reject it. `lead` is a compatibility alias for `leader`. New records write `leader`.
|
|
534
|
-
|
|
535
|
-
Analysis roles (`analyser`, `designer`, `planner`, `verifier`) accept a count of 1. A run with one analysis worker is not refused: it runs without cross-model verification, convergence is auto-disabled, the final report's cross-check section says no cross-model check ran, and `validate-run` records an advisory.
|
|
536
|
-
|
|
537
|
-
Each confirmed count becomes `RoleInstance` ordinals. `ModelPool` then assigns one model ref per ordinal. A pinned model is kept only when the host can bind it exactly. Roles with `min = 0` do not open slots by default; optional add steps or an explicit count above zero open them.
|
|
538
|
-
|
|
539
|
-
### `--role-model`
|
|
540
|
-
|
|
541
|
-
Pins one model reference onto a role slot, in ordinal order: `--role-model <role>=<modelRef>`. Repeat the flag to fill later ordinals. `modelRef` is `<provider>/<model>`, for example `claude/opus` or `codex/gpt-6.1-sol`.
|
|
542
|
-
|
|
543
|
-
A known selectable model may be assigned to any canonical role. The same role must not receive the same model ref twice; duplicate refs in one role panel fail before any worktree or state file is created. Same provider with different models is allowed. Fewer models than the confirmed count are filled from the model-default chain. Extra models do not raise the count; set `--role-count <role>=<N>` first. Unknown roles and unknown model refs fail before side effects.
|
|
544
|
-
|
|
545
|
-
Legacy `--lead-model`, `--claude-model`, `--codex-model`, `--antigravity-model`, `--worker-model`, `--report-writer-model`, and `--executor` remain compatibility inputs. They convert to role-model selections. A provider model flag fixes one slot of the initial cross-verification role per named provider; the remaining slots take the model defaults. A new flag and a legacy flag that name different models for the same role fail.
|
|
546
|
-
|
|
547
|
-
`okstra model list [--role <role>] [--host <host>] [--json]` prints the catalog without an inference call. `okstra model default set|unset <role> ... --scope project|global` writes `modelDefaults` to `.okstra/project.json` or `~/.okstra/config.json`.
|
|
548
|
-
|
|
549
|
-
### Saved worker rosters
|
|
550
|
-
|
|
551
|
-
Ask `/okstra-run` to configure worker settings, or say `okstra-run worker settings`. This opens a separate settings flow rather than starting a task. Select global defaults or project overrides, edit the roles you need, then review and save the changes together. Cancel leaves configuration unchanged. Global settings also work outside a registered project.
|
|
552
|
-
|
|
553
|
-
The settings flow writes `workerDefaults` into the existing configuration files: `~/.okstra/config.json` for global settings (respecting `OKSTRA_HOME`), or `<PROJECT_ROOT>/.okstra/project.json` for project overrides.
|
|
554
|
-
|
|
555
|
-
```json
|
|
556
|
-
{
|
|
557
|
-
"workerDefaults": {
|
|
558
|
-
"analyser": ["claude/opus", "codex/gpt-6.1-sol"],
|
|
559
|
-
"critic": [],
|
|
560
|
-
"report-writer": ["claude/sonnet"]
|
|
561
|
-
}
|
|
562
|
-
}
|
|
563
|
-
```
|
|
564
|
-
|
|
565
|
-
Each model is one worker. An empty array means zero workers for an optional role. A missing project role inherits the global role; a project array replaces the entire global array. Removing a project override restores inheritance. The editor validates the shared count range across phases where the role is static; for example, verifier defaults allow 1–3 workers, while a particular final-verification run may select up to 5.
|
|
566
|
-
|
|
567
|
-
A valid saved roster skips that role's launch picker. Unconfigured or unavailable roles alone need a selection. The final confirmation shows models, count, and source, and Edit changes only the current run. Explicit role flags and explicitly reused previous-run selections take precedence over saved settings. If either count or model is explicit for a role, saved roster values are not mixed into that role. Existing `modelDefaults` remain candidate preferences.
|
|
568
|
-
|
|
569
|
-
These settings apply to static worker roles. The leader remains host-controlled, and dynamic verifiers keep their source participant's assignment. The runtime uses the same default resolver for the wizard and direct preparation.
|
|
570
|
-
|
|
571
|
-
For host integrations, initialize the settings state with `okstra wizard init --worker-settings --state-file <path> --host-runtime <host>`. Project flags are optional in this mode. Relay the returned prompts using the normal `step` command. Settings initialization returns the host's `relayContract` path; `done` ends settings and never authorizes task launch.
|
|
572
|
-
|
|
573
|
-
### `--lead-provider`
|
|
574
|
-
|
|
575
|
-
Compatibility assertion for previously recorded invocations. The value must match the host-native provider: `claude` on Claude Code, `codex` on Codex, and `antigravity` on Antigravity. It is not an independent lead selector. Other providers belong in the worker roster and run through CLI wrappers; preparation rejects a cross-provider lead rather than recording one model and silently running another.
|
|
576
|
-
|
|
577
|
-
### `--worker-model`
|
|
578
|
-
|
|
579
|
-
Adds generic `provider=model` overrides, separated by commas. It is the model input for registry providers without a legacy dedicated flag, including Grok and Kimi.
|
|
580
|
-
|
|
581
|
-
### `--report-writer-provider`
|
|
582
|
-
|
|
583
|
-
Selects a registry provider that declares the `report-writer` capability. Claude remains the default; Codex is also supported. The provider, model, and resolved runner are persisted in `workerAssignments[]`.
|
|
584
|
-
|
|
585
|
-
### `--claude-model`
|
|
586
|
-
|
|
587
|
-
Selects the model used by the `Claude worker`.
|
|
588
|
-
When omitted, it uses the central default `OKSTRA_DEFAULT_CLAUDE_MODEL`, falling back to `opus`.
|
|
589
|
-
|
|
590
|
-
### `--lead-model`
|
|
591
|
-
|
|
592
|
-
Selects the model used by the host-native Okstra lead. Claude Code resolves it through the Claude catalog; Codex resolves it through the Codex catalog; Antigravity resolves it through the Antigravity catalog. When omitted, the host-native provider's lead default applies.
|
|
593
|
-
|
|
594
|
-
### `--codex-model`
|
|
595
|
-
|
|
596
|
-
Selects the model used by the `Codex worker`.
|
|
597
|
-
When omitted, it uses the central default `OKSTRA_DEFAULT_CODEX_MODEL`, falling back to `gpt-6.1-sol`.
|
|
598
|
-
|
|
599
|
-
### `--antigravity-model`
|
|
600
|
-
|
|
601
|
-
Selects the model used by the `Antigravity worker`.
|
|
602
|
-
When omitted, it uses the central default `OKSTRA_DEFAULT_ANTIGRAVITY_MODEL`, falling back to `gemini-3.1-pro`.
|
|
603
|
-
|
|
604
|
-
### `--report-writer-model`
|
|
605
|
-
|
|
606
|
-
Selects the model used by the `Report writer worker`.
|
|
607
|
-
When omitted, it uses the central default `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`, falling back to `sonnet`. The report writer does not vote in convergence, so its default sits below the lead tier to cut report-generation wall-clock; pass `--report-writer-model opus` to restore the previous behavior.
|
|
608
|
-
|
|
609
|
-
The central-default environment variables are:
|
|
610
|
-
|
|
611
|
-
- `OKSTRA_DEFAULT_LEAD_MODEL`
|
|
612
|
-
- `OKSTRA_DEFAULT_CLAUDE_MODEL`
|
|
613
|
-
- `OKSTRA_DEFAULT_CODEX_MODEL`
|
|
614
|
-
- `OKSTRA_DEFAULT_ANTIGRAVITY_MODEL`
|
|
615
|
-
- `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`
|
|
616
|
-
- `OKSTRA_DEFAULT_EXECUTOR` (`claude` | `codex` | `antigravity`, fallback `claude`)
|
|
617
|
-
|
|
618
|
-
Fallback defaults are:
|
|
619
|
-
|
|
620
|
-
- Claude Code lead: `opus`
|
|
621
|
-
- Codex lead: `gpt-6.1-sol`
|
|
622
|
-
- Antigravity lead: `gemini-3.1-pro`
|
|
623
|
-
- `Report writer worker`: `sonnet`
|
|
624
|
-
- `Claude worker`: `opus`
|
|
625
|
-
- `Codex worker`: `gpt-6.1-sol`
|
|
626
|
-
- `Antigravity worker`: `gemini-3.1-pro`
|
|
627
|
-
- Implementation executor: `claude`, so the default is `Claude executor`.
|
|
628
|
-
|
|
629
|
-
### `--executor`
|
|
630
|
-
|
|
631
|
-
Selects the provider that performs the Executor role for `--task-type implementation`. The value is `claude`, `codex`, `antigravity`, `grok`, or `kimi`; it is ignored for other task types.
|
|
632
|
-
|
|
633
|
-
- Default: `OKSTRA_DEFAULT_EXECUTOR` → fallback `claude`.
|
|
634
|
-
- The Executor is the **only worker allowed to mutate project files** in this run. The other providers are dispatched as strict read-only verifiers in the same run.
|
|
635
|
-
- The Executor reuses the provider's worker model flag. With `--executor codex`, its model comes from `--codex-model`, default `gpt-6.1-sol`; with `--executor antigravity`, it comes from `--antigravity-model`, default `gemini-3.1-pro`. With `--executor grok`, its model comes from `--worker-model grok=`, default `grok-4.7`.
|
|
636
|
-
- All three Claude, Codex, and Antigravity verifiers are always dispatched regardless of the Executor provider. Even the verifier using the same provider runs in a separate CLI session with isolated context, preserving the self-review safeguard.
|
|
637
|
-
- Codex and Antigravity mutate files through each CLI's auto-edit mode, for example `codex exec --sandbox danger-full-access`, without passing through Claude-side Edit/Write tools. Mutations occur in the task worktree described below. Every `okstra-<provider>-exec.sh` entrypoint receives the worktree path as its fourth positional argument and adds it to the worker's write scope, which each provider is told as repeated `--add-dir` (Codex names the project root with `-C` and skips the repeat). No provider CLI enforces a sandbox boundary: the write scope tells a worker where its work belongs, and the run checks afterwards that it stayed there.
|
|
638
|
-
- **Claude Executor cwd handling**: Claude's Bash tool has no per-call cwd argument and inherits the lead session cwd. To run cwd-sensitive toolchains such as `cargo`, `npm`, `pnpm`, `bun`, `pytest`, `make`, or `go` inside the worktree, prefix the invocation with `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>`. Keep `cd` as the leading token in a single Bash call so Claude Code permission auto-allow works; do not wrap it in `bash -lc "..."` or `bash -c "..."`, which hides `cd` and causes a permission prompt on every call. Prefer a tool's working-directory option—such as `git -C <path>`, `cargo --manifest-path`, or `pytest --rootdir`—over a `cd && ` chain. Edit/Write/Read tools already use absolute paths and need no cwd handling. This rule applies only to the Claude Executor; the Codex and Antigravity wrappers inject cwd.
|
|
639
|
-
- **Task worktree (automatic isolation for every task type)**: During the first phase's preparation for any task type, prepare creates a `git worktree` at `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` and branches `<work-category-namespace>/<task-id-segment>` from the resolved commit of the user-selected `--base-ref`, for example `feature/dev-9436` or `fix/dev-7311`. Later phases for the same task key reuse the path and branch and record status `reused`; no new `git worktree add` occurs during run preparation. Special characters such as `/` and `:` in every segment are normalized to `-`, and `~/.okstra/worktrees/registry.json` manages task-key-to-path/branch mappings under flock — paths machine-wide, branch names within one project id. Executor edits, writes, builds, tests, and commits—and verifier reads—run in this worktree. If the caller is already in another worktree or project_root is not a Git repository, provisioning is skipped and records `skipped-in-worktree` or `skipped-not-git`. Path or branch collisions fail immediately with `PrepareError`. Worktrees are not deleted after a run; remove one manually with `git worktree remove`, then `git branch -D`, then delete the registry entry. **The implementation stage isolation below is the exception.**
|
|
640
|
-
- **`implementation` stage isolation (concurrent parallelism)**: The task-key worktree above applies only from `requirements-discovery` through `implementation-planning`. Each `implementation` run executes in a **stage-specific isolated worktree** at `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>--stage-<N>/` (a sibling of the task worktree — a nested layout made the task tree's prettier/tsc read the stage tree as source; whole-task `final-verification` prepare moves any remaining nested stage worktree out with `git worktree move` and updates the registry), on branch `<work-category-namespace>/<task-id-segment>-s<N>`. The registry atomically reserves a stage key, `<task-key>#stage-<N>`, under flock. `_resolve_effective_stages` excludes `started` rows in `consumers.jsonl` and reserved stages. Stage selection, worktree creation, and registry reservation all happen in one critical section protected by the task-key provisioning mutex at `~/.okstra/.locks/worktree-provision/`, so concurrent `implementation` runs safely select different ready stages: **one run = one stage**. A stage worktree's base depends on its dependency shape: independent (`depends-on (none)`) uses the common anchor fixed once at first stage entry; a single dependency (`depends-on X`) uses the predecessor stage's completed `head_commit`; multiple dependencies (`depends-on X,Y…`) use a base holding exactly those predecessors — the predecessor commit that already contains the others, or else a branch merging them (`<work-category-namespace>/<task-id-segment>-g<n1>-<n2>`, built by `stage_integrate.ensure_stage_merge_branch` and reused as that stage's PR base in release-handoff). The branch is advanced when a predecessor's done commit moves, and only a predecessor commit missing from the repository fails the run. Select the stage with `--stage <auto|N>` for `okstra.sh`/`render-bundle`, or with the okstra-run wizard's `stage_pick` step. If `project_root` is not a Git repository or is a nested worktree, stage isolation also degrades to flat operation.
|
|
641
|
-
- **Single-stage `final-verification` artifact isolation**: `--task-type final-verification --stage <N>` reuses the implementation stage worktree read-only from the registry. Run artifacts are isolated per stage under `runs/final-verification/stage-<N>/`, and the team name receives a `-fv-s<N>` suffix. Concurrent final-verification runs for different stages do not collide in state, worker results, or team names. For concurrent verification of the same stage, `teamName` is only an audit label and each session has its own implicit team, so the sessions can coexist without a TeamCreate/name collision. This statement is limited to per-session team identity and does not claim safety for shared mutable state. Whole-task verification with an empty stage keeps the flat `runs/final-verification/` layout.
|
|
642
|
-
|
|
643
|
-
Example:
|
|
644
|
-
|
|
645
|
-
```bash
|
|
646
|
-
scripts/okstra.sh --task-type implementation \
|
|
647
|
-
--executor codex \
|
|
648
|
-
--codex-model gpt-5.6 \
|
|
649
|
-
--approved-plan .project-docs/.../runs/implementation-planning/.../reports/final-report-implementation-planning-001.md \
|
|
650
|
-
--project-id jobs --task-group tasks --task-id 8852 \
|
|
651
|
-
--task-brief .project-docs/tasks/8852/BUG_REPORT.md
|
|
652
|
-
```
|
|
653
|
-
|
|
654
|
-
### `--critic`
|
|
655
|
-
|
|
656
|
-
Selects the provider for the opt-in critic slot on `requirements-discovery`, `error-analysis`, `implementation-planning`, and `final-verification`. The value is `claude`, `codex`, `antigravity`, `grok`, or `kimi`. `--critic off` runs the phase with no critic; an analyser 1-1 tie then stays `needs-reverify` and `okstra plan-items next-dispatch` answers `user-decision` — the split becomes an approval decision for the user instead of another verification round. Prefer `--role-model critic=<provider>/<model>` so the user picks the model. The critic also settles plan-body 1-1 splits in `implementation-planning` (`critic-worker` on `--tie-vote` items) and, in every phase that has it, a Phase 5.5 finding whose vote ties once the origin worker is counted; without a critic that finding is `contested`.
|
|
657
|
-
|
|
658
|
-
- Critic dispatch runs concurrently with the first convergence reverify round in Phase 5.5, with critic input fixed to the integrated Round 0 result. One gap/blocker verification round runs in Phase 5.6 after convergence finishes. It detects coverage gaps in discovery, error-analysis, and implementation-planning, and acts as an acceptance devil's advocate in final-verification. Follow the "Coverage critic pass" and "Acceptance critic pass" sections of `prompts/lead/convergence.md` for the detailed contract.
|
|
659
|
-
- It shares the same value space as the critic-selection step in the in-session `okstra-run` wizard. `_resolve_model_bindings` in `prepare_task_bundle` validates the value; anything else is rejected immediately with `PrepareError`.
|
|
660
|
-
|
|
661
|
-
### `--approved-plan`
|
|
662
|
-
|
|
663
|
-
Accepts the path to a previous `implementation-planning` **report record** (`.data.json`) as input to `--task-type implementation`. The record's `frontmatter.approved` field must be `true`. A full reading copy (`.md`) is rejected. Schema-v1 plans have no record and cannot be passed here.
|
|
664
|
-
|
|
665
|
-
A selected-direction plan also must have `planningContract: selected-direction`, `outcome: plan-ready`, exact plan coverage, and a valid `selectedDirectionRef`. It does not accept `--implementation-option`. An already approved candidate-comparison plan without the discriminator keeps its candidate-selection behavior, including an explicit `--implementation-option` or fallback to the recommended option.
|
|
666
|
-
|
|
667
|
-
Approval format:
|
|
668
|
-
|
|
669
|
-
- The report record (`final-report-*.data.json`) owns `frontmatter.approved` as a boolean.
|
|
670
|
-
- The report writer always publishes `approved: false`. Implementation becomes available after the user approves it.
|
|
671
|
-
|
|
672
|
-
When the record is not `approved: true`, the run is rejected as `contract-violated`. Use `--approve` or the in-session wizard. Editing the full reading copy does not approve the plan.
|
|
673
|
-
|
|
674
|
-
### `--approve`
|
|
675
|
-
|
|
676
|
-
Used with `--approved-plan` and `--task-type implementation`, this flag **treats the CLI invocation itself as plan approval**:
|
|
677
|
-
|
|
678
|
-
- Sets `frontmatter.approved` to `true` on the report record and refreshes the full reading copy from that record.
|
|
679
|
-
- If the record is already `approved: true`, leaves the record unchanged.
|
|
680
|
-
- If the report record has no `frontmatter.approved` field (schema-v1: no markdown `approved:` line), exits immediately with an error because the path may refer to the wrong plan file.
|
|
681
|
-
|
|
682
|
-
Using `--approve` outside `--task-type implementation` is meaningless and exits with an error. Selected-direction semantics are validated before this flag can mutate the plan. Use it in CI or scripts, or when approval and the next phase must happen in a single command. The former `--ack-approved` alias was removed in 0.8.0.
|
|
683
|
-
|
|
684
|
-
Example:
|
|
685
|
-
|
|
686
|
-
```bash
|
|
687
|
-
scripts/okstra.sh --task-type implementation \
|
|
688
|
-
--approve \
|
|
689
|
-
--approved-plan .okstra/tasks/.../runs/implementation-planning/reports/final-report-implementation-planning-001.data.json \
|
|
690
|
-
--project-id jobs --task-group tasks --task-id 8852 \
|
|
691
|
-
--task-brief .project-docs/tasks/8852/BUG_REPORT.md
|
|
692
|
-
```
|
|
693
|
-
|
|
694
|
-
### `--work-category`
|
|
695
|
-
|
|
696
|
-
Classifies the work in this task. Allowed values:
|
|
697
|
-
|
|
698
|
-
- `bugfix`
|
|
699
|
-
- `feature`
|
|
700
|
-
- `refactor`
|
|
701
|
-
- `ops`
|
|
702
|
-
- `improvement`
|
|
703
|
-
|
|
704
|
-
Normally, the `requirements-discovery` phase infers work-category automatically. In a lifecycle that skips that phase—for example, one starting directly at `implementation-planning`—use this flag to classify the work explicitly. The value is preserved in `task-manifest.json` and used for grouping by the schedule and status skills.
|
|
705
|
-
|
|
706
|
-
The effective value for a run is resolved by `scripts/okstra_ctl/work_categories.py` (`resolve_work_category`) in this order: **the explicit flag → the classification already recorded in the task's `task-manifest.json` → `feature`** (`DEFAULT_WORK_CATEGORY`). This is why a later phase run without `--work-category` still lands on the same branch namespace that `requirements-discovery` classified—for example `feature/dev-9436` rather than the `task/` fallback. The `okstra-run` in-session wizard never asks for this flag, so it always takes the resolved path; its worktree preview runs the same resolver, so the preview matches the branch that is actually created. Already-created `task/…` branches are not renamed automatically—the registry key and `consumers.jsonl` history would drift, so they need manual cleanup.
|
|
707
|
-
|
|
708
|
-
Example:
|
|
709
|
-
|
|
710
|
-
```bash
|
|
711
|
-
scripts/okstra.sh --task-type implementation-planning \
|
|
712
|
-
--work-category refactor \
|
|
713
|
-
--project-id jobs --task-group tasks --task-id 8852 \
|
|
714
|
-
--task-brief .project-docs/tasks/8852/PLAN.md
|
|
715
|
-
```
|
|
716
|
-
|
|
717
|
-
### `--base-ref`
|
|
718
|
-
|
|
719
|
-
The Git ref used as the base when the isolated worktree for a task key is first created. It may be a branch name, tag, or commit SHA.
|
|
720
|
-
|
|
721
|
-
- Required during first-phase preparation. The `okstra-run` skill collects it through the same menu as the PR base picker: `main`, `dev`, `staging`, `preprod`, `prod`, or custom input.
|
|
722
|
-
- Later phases for the same task key reuse the worktree path, branch, and base ref stored in the registry, so a new value is ignored.
|
|
723
|
-
- If `project_root` is not a Git repository or is already inside a non-main worktree, provisioning is skipped and this value is unused.
|
|
724
|
-
|
|
725
|
-
Example:
|
|
726
|
-
|
|
727
|
-
```bash
|
|
728
|
-
scripts/okstra.sh --task-type requirements-discovery \
|
|
729
|
-
--base-ref main \
|
|
730
|
-
--project-id jobs --task-group tasks --task-id 8852 \
|
|
731
|
-
--task-brief .project-docs/tasks/8852/BRIEF.md
|
|
732
|
-
```
|
|
733
|
-
|
|
734
|
-
### `--related-tasks`
|
|
735
|
-
|
|
736
|
-
Accepts a comma-separated list of related task identifiers.
|
|
737
|
-
|
|
738
|
-
Example:
|
|
739
|
-
|
|
740
|
-
```bash
|
|
741
|
-
scripts/okstra.sh --task-type error-analysis --related-tasks scanner-regression,reply-ui --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
|
|
742
|
-
```
|
|
743
|
-
|
|
744
|
-
Related tasks are reference metadata and do not replace the current task key.
|
|
745
|
-
|
|
746
|
-
### `--render-only`
|
|
747
|
-
|
|
748
|
-
Creates the prompt and task bundle without executing Claude.
|
|
749
|
-
|
|
750
|
-
This mode does not:
|
|
751
|
-
|
|
752
|
-
- Execute Claude.
|
|
753
|
-
- Create `final-report-<task-type>-<seq>.md`.
|
|
754
|
-
- Create `final-<task-type>-<seq>.status`.
|
|
755
|
-
|
|
756
|
-
It does:
|
|
757
|
-
|
|
758
|
-
- Create or update the stable task root.
|
|
759
|
-
- Create or update `task-manifest.json`.
|
|
760
|
-
- Create or update `task-index.md`.
|
|
761
|
-
- Create or update `instruction-set/`.
|
|
762
|
-
- Create or update `instruction-set/reference-expectations.md`.
|
|
763
|
-
- Create or update `instruction-set/final-report-template.md`.
|
|
764
|
-
- Record the current `manifests/run-manifest-<task-type>-<seq>.json`.
|
|
765
|
-
- Update `history/timeline.json`.
|
|
766
|
-
- Create or update the project-level discovery pointer.
|
|
767
|
-
|
|
768
|
-
### `--no-plan-verification`
|
|
769
|
-
|
|
770
|
-
Disables the Phase 6 plan-body verification round for the `implementation-planning` task type. It is enabled by default and ignored for other task types.
|
|
771
|
-
|
|
772
|
-
### `--terminal-backend`
|
|
773
|
-
|
|
774
|
-
Names the surface this run's workers get: `cmux-pane` (each worker opens its own
|
|
775
|
-
pane beside the lead) or `cli-wrapper` (each worker is a background subprocess
|
|
776
|
-
read through its status sidecar). Leave it unset and preparation probes for a
|
|
777
|
-
usable cmux session instead.
|
|
778
|
-
|
|
779
|
-
The flag exists for one case: preparing a run wrapper-backed on purpose after the
|
|
780
|
-
task's previous run of the same phase used cmux panes. Preparation refuses that
|
|
781
|
-
downgrade on its own, because the probe's last step is a cmux socket connect and
|
|
782
|
-
a sandboxed lead — codex `workspace-write` denies AF_UNIX connect — fails it while
|
|
783
|
-
the very cmux it is running inside is still open. Passing
|
|
784
|
-
`--terminal-backend cli-wrapper` declares the downgrade and skips the probe;
|
|
785
|
-
`--terminal-backend cmux-pane` asserts the surface without probing at all.
|
|
786
|
-
|
|
787
|
-
The value is recorded as `terminalBackend` in the run manifest, and every later
|
|
788
|
-
consumer reads it from there rather than probing again.
|
|
789
|
-
|
|
790
|
-
A `cmux-pane` run also records where the lead sits, as `cmuxLead`
|
|
791
|
-
(`workspaceId`, `surfaceId`), taken from the terminal that ran preparation. Worker
|
|
792
|
-
placement, lead-pane sizing, sidebar messages and pane reclaim read that record
|
|
793
|
-
before the dispatching process's own `CMUX_*` variables, because the lead process
|
|
794
|
-
may not have inherited them from that terminal: Claude Code can start the lead by
|
|
795
|
-
claiming a pre-warmed process created in another workspace. When the recorded
|
|
796
|
-
surface has closed, workers run as cli-wrapper processes instead.
|
|
797
|
-
|
|
798
|
-
- **Enabled (default)**: Immediately after the report-writer worker drafts its narrative in Phase 6, the lead extracts the synthesized plan into `P-*` items and dispatches them for reverification to every analyzer worker: `claude`, `codex`, and opted-in `antigravity`. A selected-direction plan uses `P-Dir-1` plus its step, dependency, validation, rollback, requirement, preparation, and variation items. A legacy candidate plan retains `P-Opt-*`. Worker verdicts (`AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`) are aggregated into one of four gate results: `passed`, `passed-with-dissent`, `blocked-by-disagreement`, or `aborted-non-result`. The approval control is available only for `passed` or `passed-with-dissent`. Items with majority DISAGREE become rows with `Blocks=approval` in `## 1. Clarification Items`. There is no automatic revision; the user answers and resumes the same phase.
|
|
799
|
-
- **Disabled (with `--no-plan-verification`)**: The entire Phase 6 substep is skipped and the Approval marker is always rendered at the top of the final report, matching legacy behavior. This is a fast-iteration opt-out and is not recommended for a handoff-ready plan.
|
|
800
|
-
- **Advisory auto-path (not this flag)**: when `designPreparation.mode` is `no-design-inputs` and the Stage Map has exactly one row, `okstra plan-items prepare` sets `convergence.planBodyVerification.gating=false`. Extraction and one verification round still run; the self-fix loop and a sweep batch do not. Two-or-more stages, a PREP item, or non-empty design-preparation items keep `gating=true`.
|
|
801
|
-
- The flag records `false` in the manifest at `convergence.planBodyVerification.enabled`. The resume command must include the same flag to preserve behavior; `_canonical_argv` guarantees faithful emission on resume.
|
|
802
|
-
- For the detailed round protocol, verdict semantics, and state-file schema, see the "Plan-body verification mode (implementation-planning only)" section of `prompts/lead/convergence.md`.
|
|
803
|
-
|
|
804
|
-
## Interactive input flow
|
|
805
|
-
|
|
806
|
-
When required arguments are omitted in an interactive terminal, `okstra` may ask for these values in order:
|
|
807
|
-
|
|
808
|
-
- `Project ID`
|
|
809
|
-
- `Task Group`
|
|
810
|
-
- `Task ID`
|
|
811
|
-
- `Task Type`
|
|
812
|
-
- `Task Brief Path`
|
|
813
|
-
|
|
814
|
-
For example:
|
|
815
|
-
|
|
816
|
-
```bash
|
|
817
|
-
scripts/okstra.sh --render-only --task-type error-analysis
|
|
818
|
-
```
|
|
819
|
-
|
|
820
|
-
The command reads missing required values from stdin, then proceeds through the final summary and confirmation.
|
|
821
|
-
|
|
822
|
-
## Confirmation flow
|
|
823
|
-
|
|
824
|
-
Before creating files in an interactive run, okstra shows a summary containing:
|
|
825
|
-
|
|
826
|
-
- Whether the run is render-only.
|
|
827
|
-
- Task type.
|
|
828
|
-
- Project ID.
|
|
829
|
-
- Task group.
|
|
830
|
-
- Task ID.
|
|
831
|
-
- Task brief path.
|
|
832
|
-
- Analysis target.
|
|
833
|
-
- Related tasks.
|
|
834
|
-
- Selected workers.
|
|
835
|
-
- Lead model.
|
|
836
|
-
- Configured worker models.
|
|
837
|
-
- Task key.
|
|
838
|
-
- Task root.
|
|
839
|
-
- Current run directory.
|
|
840
|
-
|
|
841
|
-
It then displays `Continue? [y/yes]:`. Any response other than `y` or `yes` exits without executing.
|
|
842
|
-
|
|
843
|
-
`--yes` skips this confirmation flow entirely.
|
|
844
|
-
|
|
845
|
-
---
|
|
846
|
-
|
|
847
|
-
## Z.ai GLM workers
|
|
848
|
-
|
|
849
|
-
Z.ai is a worker provider (`zai`) that uses the existing `claude` executable. Install Claude Code, provide `ZAI_API_KEY` once in `~/.env` or in the environment inherited by Okstra, and select `zai/glm-5.3` or `zai/glm-5.3-flash` in a role-model step. For explicit launch arguments, use `--role-model analyser=zai/glm-5.3`. These models support worker roles; this integration does not provide a Z.ai lead host.
|
|
850
|
-
|
|
851
|
-
A nonempty process `ZAI_API_KEY` takes precedence. Otherwise each GLM worker reads `ZAI_API_KEY` from the current user's `~/.env`, independently of its project or working directory. This also applies to workers opened in separate terminal panes. Only that key is selected; other file entries are not imported into the environment. Supported entries are single-line `ZAI_API_KEY=value` assignments with optional `export`, single or double quotes, and trailing comments. Shell commands and variable substitutions are never evaluated. If the key appears more than once, the last assignment wins. An unreadable file or malformed matching assignment fails with an error that omits its contents. No project `.env` is read.
|
|
852
|
-
|
|
853
|
-
Each GLM child process uses `https://api.z.ai/api/anthropic` and its own model/authentication environment. Okstra does not edit `~/.claude/settings.json`. GLM runs with `--setting-sources ""` so user, project, and local settings cannot override those connection values; settings-based hooks and integrations are consequently not inherited for GLM workers. The regular Claude provider keeps its existing settings behavior.
|
|
854
|
-
|
|
855
|
-
The runtime rejects a missing `ZAI_API_KEY` before starting the worker. Catalog visibility does not verify the account's model entitlement or remaining quota. The installed Claude Code version and Z.ai account must support the selected model. See [Z.ai's Claude Code setup](https://docs.z.ai/devpack/tool/claude) and [Coding Plan usage policy](https://docs.z.ai/devpack/usage-policy) for provider requirements.
|
|
856
|
-
|
|
857
|
-
GLM response model identities are recorded as `zai/<model>`; a startup model label alone is not treated as proof of the served model. The final Claude Code usage event supplies input, output, cache-creation, and cache-read counters. Repeated dispatches are summed by their status files. Costs use Z.ai's public API token prices regardless of whether the account uses a subscription or metered API billing. Missing usage or an unknown model price stays unavailable.
|
|
858
|
-
|
|
859
|
-
The [official API prices](https://docs.z.ai/guides/overview/pricing), checked on 2026-09-14, are USD per million tokens:
|
|
860
|
-
|
|
861
|
-
| Model | Input | Cached input | Output |
|
|
862
|
-
|---|---:|---:|---:|
|
|
863
|
-
| `glm-5.3` | $1.40 | $0.26 | $4.40 |
|
|
864
|
-
| `glm-5.3-flash` | $0.15 | $0.03 | $0.50 |
|
|
865
|
-
|
|
866
|
-
Cache-creation tokens use the input rate; cache-read tokens use the cached-input rate. Z.ai currently lists cached-input storage as free for a limited time. The reported cost is the API-equivalent token cost, not the subscription invoice. Regression coverage is in `tests/adapters/accounting/test_cli_provider_transcripts.py` and `tests/adapters/providers/test_provider_registry.py`.
|
|
867
|
-
|
|
868
|
-
## `okstra` Node CLI — introspection subcommands
|
|
869
|
-
|
|
870
|
-
The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and introspection commands used by skills and agents. It goes through the Node wrapper instead of invoking the Python runtime directly, so `src/lib/python-helper.mts` wires `PYTHONPATH`.
|
|
871
|
-
|
|
872
|
-
| Command | Purpose |
|
|
873
|
-
|---|---|
|
|
874
|
-
| `okstra explain-flow --question <question>` | Explain a business flow across related projects; `knowledge`, `rerun` and `status` inspect shared knowledge or explanation history |
|
|
875
|
-
| `okstra paths [--field <name>\|--shell]` | Print package, runtime, home, bin, Python path, and version locations |
|
|
876
|
-
| `okstra install [--runtime claude-code\|codex\|antigravity\|external\|all] [--refresh\|--dry-run\|--link <repo>]` | Install or update the runtime, templates, skills, and agents. The default runtime is `auto`; skill targets are not runtimes. `~/.agents/skills/` is always created, and Claude skills and agents are also installed when `~/.claude` exists |
|
|
877
|
-
| `okstra ensure-installed [--runtime claude-code\|codex\|antigravity\|external\|all] [-q]` | Check installation state and reinstall stale assets for the same runtime. Default `auto` continues without a host signal and checks drift in the Agent skill target and any existing Claude target |
|
|
878
|
-
| `okstra uninstall [--purge -y]` | Remove installed assets. By default, removes the installed trees under `~/.okstra` (including `agents/`), the skill targets recorded in `installed-skills.json`, and any host agent files `installed-agents.json` proves a past install owned, while preserving user data |
|
|
879
|
-
| `okstra doctor [--runtime claude-code\|codex\|antigravity\|external\|all] [--phase <phase>] [--json]` | Diagnose the runtime, Python imports, skill/agent installation, and model-pool state. The JSON `modelPool` object reports pool errors, default errors, binding precision, observed model, max write boundary, and invocation downgrade reason. It never sends an inference call. The `codex`, `antigravity`, and `external` runtimes omit Claude skill checks. `--phase` adds readiness checks for `implementation`, `final-verification`, `release-handoff`, or `improvement-discovery` |
|
|
880
|
-
| `okstra model list [--role <role>] [--host <host>] [--json]` | List catalog models for a host and optional role. Unselectable exact bindings report `exact binding unavailable`. No inference call |
|
|
881
|
-
| `okstra model default set\|unset <role> ... --scope project\|global [--cwd <dir>]` | Atomically write or remove `modelDefaults` for one canonical role |
|
|
882
|
-
| `okstra mcp add --name <name> --description <text> --tool <tool>... [--alias <name>...] [--notes <text>] [--cwd <dir>]` | Validate and add, or replace by name, one `.okstra/project.json` `mcpServers` entry. `--alias` names the server as a provider CLI lists it |
|
|
883
|
-
| `okstra mcp list [--json] [--cwd <dir>]` / `okstra mcp remove --name <name> [--cwd <dir>]` | Print the declared servers and any malformed entries (exit 1 when one is malformed) / remove one entry by name |
|
|
884
|
-
| `okstra mcp check [--provider <id>...] [--brief <path>] [--json] [--cwd <dir>]` | Run each provider adapter's MCP listing (`ProviderSpec.mcp_inventory`, no inference call) and report every declared server as `reachable`, `disabled`, `missing`, or `unknown` (the adapter cannot list) per provider. Defaults to every registered provider. `--brief` adds the brief MCP-source check. prepare runs the same check for the run's providers, prints `prepare: mcp: ...` warnings, and renders the result into the launch prompt and the analysis packet; it never refuses a run |
|
|
885
|
-
| `okstra setup --project-id <id>` | Create or update `.okstra/project.json` in the current project. When `<PROJECT_ROOT>/CLAUDE.md` or `AGENTS.md` already exists, it also appends — or refreshes in place — an okstra-managed block between `<!-- okstra:citation-guidance:begin -->` / `end` telling agents not to cite okstra-internal references (report section numbers, `C-NNN` ids, run/stage ids, `.okstra/...` paths) outside an okstra report. Neither file is created, and a failure is a warning, not an error |
|
|
886
|
-
| `okstra check-project [--json]` | Verify that the current project is registered |
|
|
887
|
-
| `okstra preflight [--runtime <name>] [--cwd <dir>] [--machine]` | Single skill-preflight call combining `ensure-installed`, with silent reinstall when stale, `check-project`, and host-specific `runtimeReadiness`. It defaults to a fixed text projection. `--machine` returns the automation JSON contract, and `--json` is a deprecated one-release alias. A `claude-code` host checks project workspace trust. A `codex` current-session host verifies write access to `~/.okstra/worktrees/registry.lock`; a sandbox denial blocks before the wizard with the `switch-codex-to-full-access-and-rerun` action. `antigravity` and `external` hosts return ready without reading Claude Code state. Step 0 of every project-scoped skill converges on this command |
|
|
888
|
-
| `okstra convergence seed --groups <path> --work-state <path> --final-state <path> --migration-dir <dir> [--restart-from-round0]` | Create, resume, reuse, or explicitly recover deterministic convergence state. `--restart-from-round0` is refused unless the working state is invalid. State paths named `…-correction-r<N>-<task-type>-<seq>.json` seed an implementation correction round's re-convergence, checked against that round's verifier results |
|
|
889
|
-
| `okstra convergence plan-round --work-state <path> --plan <path>` | Persist the next roster-aware dispatch plan without mutating working state; refuses to overwrite a different plan at `--plan` whose round its namespace already dispatched |
|
|
890
|
-
| `okstra convergence collect-results --plan <round-plan.json> --result <worker>=<path>… --run-manifest <run-manifest.json> --output <round-results.json> [--correction-round <N>]` | Read one round's worker responses into the `apply-round --results` shape. The reverify prompt answers `REFUTED` / `SURVIVES` / `SURVIVES-WITH-CAVEAT` / `UNVERIFIABLE`, which this maps to `disagree` / `agree` / `supplement` / `unverifiable`, and copies `**Basis**` into `disagreeBasis`. `--dispatch` supplies the terminal status and duration, which live in the dispatch rather than the response; a worker that never returned gets a `--dispatch` and no `--result`. Exits 2 on a dispatched finding with no verdict, a verdict for a finding the plan did not dispatch to that worker, a planned worker with no recorded outcome, or a vote with no explanation |
|
|
891
|
-
| `okstra convergence apply-round --work-state <path> --plan <path> --results <path>` | Validate one complete structured result set and atomically reduce it into working state |
|
|
892
|
-
| `okstra convergence critic-prompt --run-manifest <path>` | Render the critic task instructions to stdout — the acceptance critic's on `final-verification`, the coverage critic's elsewhere; the lead writes the output verbatim into the file the prompt materializer's `--instruction` takes. The body carries the run's Round 0 consolidated findings, one line per Phase 4 analyser (worker id, result path, its finding ids), the two mandates plus the `duplicateOf` declaration rule, and — on an implementation-planning re-run — an already-covered index of the prior report's requirement-coverage row ids, clarification row ids, and stage titles (ids and titles only, never body text). Emits the `**Prompt Delivery Mode:**` header and the `Primary analysis packet` line the critic dispatch contract requires, so no part of the critic body is hand-written. The acceptance body carries the analysis packet, the analyser result lines and the acceptance mandate with the `### [AC-NNN]` candidate format, and omits the Round 0 list to stay inside the final-verification 96-line cap. Exits 2 when the run has published no grouping yet, or when the manifest carries no `analysisPacketPath` |
|
|
893
|
-
| `okstra convergence reverify-prompt --run-manifest <path> --plan <round-plan.json> --worker <worker-id> [--correction-round <N>]` | Render one worker's reverify task instructions to stdout; the lead writes the output verbatim into the file the prompt materializer's `--instruction` takes. The body carries the adversarial mandate, the plan row's findings in plan order — each with its summary, origin worker, cited-evidence line, the origin worker's result file and `### <item-id>` section, and the origin audit sidecar the verifier is told it may open — and the response format the collector parses. Exits 2 when the plan dispatches nothing to that worker, names a finding the grouping lacks, or is not a `dispatch` plan |
|
|
894
|
-
| `okstra convergence critic-verify-prompt --run-manifest <path> --gaps <critic-batch.json> --worker <worker-id>` | Render one Phase 4 analyser's coverage-critic gap verification instructions to stdout; the lead writes the output verbatim into the file the prompt materializer's `--instruction` takes and materializes it with `--dispatch-kind critic-verify` under the analyser's `reverify/<worker-id>` assignment ref. Input is the pre-vote coverage batch (`mode: coverage`, `gaps[]` with `gapId`, `summary`, `category`, `ticketIds`, `originEvidence`, optional `duplicateOf`) the lead later passes to `apply-critic-gaps`; gaps are assigned round-robin over the grouping's analysis roster exactly as `apply-critic-gaps` checks them, and the body carries only this analyser's share — each gap with the critic's result file (`<provider>-worker-critic-<task-type>-<seq>.md`) and `### [<gapId>]` section, the critic audit sidecar, and the adversarial response format. A batch with `mode: acceptance-devils-advocate` and `candidates[]` (`candidateId`, `statement`, `severity`, `originEvidence`) renders the confirm-or-downgrade instructions instead: every analyser gets every candidate, each pointing at the critic result section whose heading names that `candidateId`, in either the bracketed or the plain heading form. Exits 2 when the batch's taskKey or mode does not match, the run has no critic assignment, the critic result is not collected yet, the worker is not an analyser, or round-robin assigns it no gap |
|
|
895
|
-
| `okstra convergence collect-acceptance-votes --run-manifest <path> --candidates <batch.json> --result <worker>=<path>… --output <batch.json>` | Read the analysers' `critic-verify` responses to the acceptance candidates and write the `apply-acceptance-critic --results` batch: a candidate any analyser answers `SURVIVES` or `SURVIVES-WITH-CAVEAT` is `confirmed`, every other candidate `downgraded`; each candidate row keeps the per-analyser votes. Exits 2 when a worker is not an analyser or returned no verdict for a candidate |
|
|
896
|
-
| `okstra convergence census-audit --run-manifest <path> --result <worker>=<path>… [--gapfill <worker>=<path>…]` | Read every analysis worker's `Coverage Verdicts` against the run's coverage census and write `state/coverage-census-audit-<task-type>-<seq>.json`: each worker's cells without a usable verdict and why, the cell × worker matrix, the cells one worker judged `finding` and another `clean`, and per-cell grouping suggestions. `--gapfill` merges a worker's one `census-gapfill` result; a `--result` or `--gapfill` path that does not exist is recorded as missing. Prints a JSON summary with `gapfillNeeded` and per-worker `unverdicted` counts. Unjudged cells never change the exit code; a run without a census prints `"census": "absent"` and writes nothing |
|
|
897
|
-
| `okstra convergence census-gapfill-prompt --run-manifest <path> --worker <worker-id>` | Render one analysis worker's census gap-fill instructions from the latest audit to stdout: only the cells that worker left unjudged, grouped by why, plus the `**Prompt Delivery Mode:**` header and the `Primary analysis packet` line. The lead materializes it under the worker's `initial/<worker-id>` assignment with `--dispatch-kind census-gapfill`. Exits 2 when no audit exists, the worker left no cell unjudged, or the worker already had its one gap-fill |
|
|
898
|
-
| `okstra convergence apply-critic-gaps --work-state <path> --results <path>` | Apply one verified coverage-critic batch after the main queue reaches a terminal state |
|
|
899
|
-
| `okstra convergence apply-acceptance-critic --work-state <path> --results <path>` | Record the final-verification acceptance critic's confirm-or-downgrade accounting into `config.critic`. Takes `{schemaVersion, taskKey, mode: "acceptance-devils-advocate", provider, modelExecutionValue, candidates[]}` with one `{candidateId, verdict}` per candidate, `verdict` being `confirmed` or `downgraded`; `candidatesProposed` / `confirmedBlockers` / `downgradedToResidual` are derived here, not declared in the batch. `apply-critic-gaps` implements coverage merge/drop semantics and rejects this mode, so this is the only writer of the acceptance summary. Requires a terminal main queue and refuses a second application |
|
|
900
|
-
| `okstra convergence finalize --work-state <path> --output <path>` | Materialize the terminal schema v1.3 convergence state |
|
|
901
|
-
| `okstra convergence skip --run-manifest <path> --reason <text>` | Write the run's convergence final state at the manifest's `convergenceStatePath` when no analyser, designer, planner, verifier, or critic attempt returned a result (an implementation stage stopped before verification, or every verifier ended without one). The state is auto-disabled with `config.autoDisabled: "no-analyser-dispatched"` and the lead's text in `config.autoDisabledReason`. Exits 2 when any of those attempts returned a result or is still open, or when a convergence state already exists |
|
|
902
|
-
| `okstra convergence validate --state <path> --kind <working\|final>` | Validate replayable working state or a terminal final state |
|
|
903
|
-
| `okstra convergence example --kind <groups\|round-results\|critic-results\|coverage-batch\|acceptance-batch>` | Print one deterministic valid input example as JSON. Each kind feeds one command: `groups` → `seed --groups`, `round-results` → `apply-round --results`, `coverage-batch` → `apply-critic-gaps --results`, `acceptance-batch` → `apply-acceptance-critic --results`. `critic-results` feeds nothing — it is the critic worker's own result document, and feeding it to `apply-critic-gaps` is rejected by design; that reducer takes the coverage batch the lead assembles from those candidates plus each analyser's vote, which is what `--kind coverage-batch` prints |
|
|
904
|
-
| `okstra group-context init --project-root <root> --task-group <group>` | Write the task-group context skeleton `.okstra/briefs/<task-group>/group-context.md` from `templates/reports/group-context.template.md` and print the sections to fill. Exits 2 when the file already has human sections; a file okstra created with only its memory region gets the human skeleton inserted above that region. The filled document is validated by `validators/validate-brief.py` (frontmatter `type: group-context`), copied by preparation into `instruction-set/task-group-context.md`, and carried in the analysis packet's `## Task-Group Context` section ahead of the brief extract; the trailing `## Task Memory` region between `<!-- okstra:task-memory:begin -->` / `end` markers is written by `report-finalize` (`record-group-memory`) and reaches sibling tasks as `## Task-Group Memory`. Preparation refuses a file that still carries a `<...>` placeholder line, and a task-group without the file prepares as before |
|
|
905
|
-
| `okstra brief-sources attach --project-root <root> --brief <path>` | Upgrade a brief in place: for every git-untracked document under the project root (`.md`, `.markdown`, `.txt`, `.rst`, `.adoc`, outside `.okstra/`) that the brief names outside `## Source Material` without a `### Source N — file` entry, append one at the end of Source Material with `format: by-reference` and a project-relative `ref`. No other line changes, so end-state ids, External Gates and hand edits stay. Every later prepare copies those files read-only into the analysis packet's `## Cited Local Documents`. `validators/validate-brief.py` refuses such a brief until the entry exists (a task worktree is a checkout and lacks the file); prints `nothing to attach` when none is missing, and exits 2 without writing when the brief has no Source Material section, cannot be read, cites a missing document over 200,000 bytes (prepare does not copy one that large; capture the cited part as-is instead), or git fails inside the project's work tree |
|
|
906
|
-
| `okstra plan-items extract (--narrative <report-narrative.md>\|--data <historical-data.json>) --output <items.json>` | Deterministically extract the complete implementation-planning `P-*` queue. Contract v3 reads the report-writer narrative before publication; `--data` is the historical v2 reader. |
|
|
907
|
-
| `okstra plan-items validate (--narrative <report-narrative.md>\|--data <historical-data.json>) --items <items.json>` | Require the persisted `P-*` queue to match a fresh deterministic extraction exactly. |
|
|
908
|
-
| `okstra plan-items derivations --data <data.json> --response <user-response sidecar> [--clarification C-NNN]` | List the plan statements an answered clarification may have falsified. Extracts the symbols, paths, and ids the answer names (backticked spans plus `R-001` / `DEV-10174`-style ids) and reports every string in the plan body that mentions one, as a JSON pointer plus excerpt. Advisory: it says where a decision's subject is mentioned, never which mentions are now wrong — the supersession rule (`prompts/profiles/_common-contract.md`) requires the author to enumerate before editing, and this supplies the enumeration |
|
|
909
|
-
| `okstra plan-items <prepare\|prompt\|validate-prepared> --run-manifest <path> …` | Bind the implementation-planning verification queue to the run manifest. `prepare` extracts the exact queue from `--narrative` and, when `designPreparation.mode` is `no-design-inputs` and the Stage Map has one row, flips `convergence.planBodyVerification.gating` to `false` (stdout `Gating`). `prompt` emits its fixed lossless view, ending with the parser-facing `## Response format` block so the block reaches every verifier with the queue; `validate-prepared` proves the prepared queue still matches the narrative. With `--state <plan-body-verification.json>` the round is a re-verification: `prepare` also carries each queued item's recorded votes and `selfFixNote` into the envelope as `priorRounds`, `prompt` renders them as that item's `**Prior round dissent**` block behind a re-verification preamble, and `validate-prepared` re-derives the carry and rejects an envelope that dropped it. Python resolves the convergence-owned state path, so model callers never choose it. |
|
|
910
|
-
| `okstra plan-items seed --narrative <report-narrative.md> --state <plan-body-verification.json> [--prior-state <previous plan-body-verification.json>]` | Create the convergence-owned `planBodyVerification.planItems[]` rows every verdict lands in, from the same deterministic extraction `extract` uses. The historical v2 form is `--data <data.json>`. Idempotent by id: an existing row keeps its verdicts and carried fields. Reports `seeded` / `existing` counts. `--prior-state` carries the previous **run**'s verdicts into this one: a newly seeded item whose `contentHash` equals that run's `verifiedContentHash` for the same id inherits its `verdicts[]` and is tagged `carriedForwardFromSeq` with the seq read off the prior filename, so round 1 does not re-judge text nobody changed. A matching id alone never carries — `P-*` ids are positional and shift. It requires `--state`, refuses a prior state whose task root differs from the one `--state` lives under (the state file carries no task identity, so its path is the only identity there is), and when it carries anything it rewrites the sibling `plan-items-*.json` `dispatchQueue` the way `incremental-carry` does. Adds `carried` / `carriedForwardFromSeq` to the reported counts. |
|
|
911
|
-
| `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker-id>=<result.md>… --round <N>` | Read each worker's Markdown verdict directly, validate every current `P-*` id, reject duplicate worker submissions, and overwrite that round's stored verdicts. `--items <plan-items artifact>` narrows and persists the assignment shared by verdict validation and round completion to what a partial round actually dispatched — pass the `--tie-vote` artifact on a critic tie round, or every item the critic was never given is refused as unanswered. The unanswered check still applies inside the narrowed set. Earlier verdicts and completed-round history outside that set remain unchanged. The historical `--verdicts <file>` form remains automation compatibility only. Without `--append` every recorded verdict row of the queued items is replaced; when a row belongs to a round `complete-round` never closed, the command refuses before writing and names the `complete-round --round <M>` to run first. `--discard-open-rounds` replaces anyway — the recovery path when those rounds are being re-applied from their result files in order (the discarded rows are printed); it also restores `dispatchQueue` to the items those result files answer, since the persisted queue belongs to the latest round and an earlier round's verdicts would otherwise be refused as outside it. |
|
|
912
|
-
| `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N> [--items <plan-items artifact>] [--self-fix-note <item-id>=<markdown-file>]… [--self-fix-group <cause-file>=<item-id>[,<item-id>...]]… [--self-fix-stop-reason <all-resolved\|no-progress\|max-rounds-reached>]` | After `plan-verify` succeeds, atomically derive and record the round's per-item votes, gate result, participant counts from the actual assigned roster, immutable completion time, convergence history, and optional self-fix notes/groups read from Markdown files. `--self-fix-group` requires `--self-fix-stop-reason` — there is no default. `--self-fix-stop-reason` alone records a stop for a round that rewrote nothing and leaves `selfFixGroups` / `selfFixRoundsApplied` untouched. When `--items` is omitted, completion automatically reads this run's canonical prepared queue and restores it when it includes all votes recorded for the requested round. If that file belongs to a narrower later batch, the persisted queue stays authoritative. This recovers saved critic results after an upgrade without requiring the lead to add a recovery flag. An explicit `--items` still selects a prepared artifact. Only the assigned items need verdicts for this round; earlier verdicts elsewhere remain unchanged. Missing-verdict errors name the round and exact dispatched item ids. Models do not write the state JSON. Stdout also carries `nextDispatch`. With `gating=false`, critic corrections are exempt from the analyser round limit and do not require an even split. A later `--append` updates the critic verdict while retaining analyser votes and completed round history. A second automatic rewrite is rejected; the one rewrite may contain several cause groups. `selfFixRoundsApplied` remains its verification round number, not a rewrite count. |
|
|
913
|
-
| `okstra plan-items next-dispatch --state <plan-body-verification.json> [--run-manifest <path>]` | After `apply-verdicts`, decide whether this round opens a worker batch. `kind: none` — missing-dependency `UNVERIFIABLE` only, no new batch. `kind: worker-correction` — re-prompt only those workers; peers stay idle. `kind: critic-tie` — unsettled analyser 1-1 on a run that rostered a critic, `critic-worker` on those item ids only. `kind: user-decision` — the same 1-1 on a run with no critic rostered: no in-band vote can break it, so open one `okstra approval-decision open` per item (classification `correctness-critical` for unresolved kind `a` outside `P-Var-*` or kind `f` on `P-Req-*`, otherwise `noncritical-dissent`) plus its `## 1. Clarification Items` row and dispatch no further verification for them. `--run-manifest` is what tells the two apart (`invocationAssignments` `critic/*`); without it the answer stays `critic-tie`. A missing path is never environment-unverifiable. After the single automatic self-fix, remaining items route to `lead-decision` first, then `user-decision`, with no further automatic worker batch. |
|
|
914
|
-
| `okstra plan-items resolve-dissent --state <plan-body-verification.json> --item <P-id> --decision-file <markdown-file>` | Record the lead decision, its authority within agreed scope, and cited evidence after the one self-fix. Accepts only current, noncritical design judgements; facts, user-input requirements and non-results require user confirmation. Keeps original votes and appends the decision to the report dissent log. The decision expires when its content, scope or verdicts change. |
|
|
915
|
-
| `okstra plan-items correction-prompt --state <plan-body-verification.json> --run-manifest <path> --worker <id>` | Emit the planning-time environment-gap paragraph, then the assigned queue. The environment exception is first. Exits 2 unless `next-dispatch` named that worker as a blanket-UNVERIFIABLE correction target. |
|
|
916
|
-
| `okstra error-log append-observed --out <errors.jsonl> --task-key <key> --phase <task-type> --agent <assigned-worker-id> --agent-role worker --model <model> --error-type tool-failure --command-file <markdown-file> --command-kind <kind> --message-file <markdown-file> [--cause <cause> --evidence-file <kind=file>]…` | Worker-facing typed error recording surface. Python validates and serializes the JSONL record; a worker supplies scalar identity fields plus Markdown files for free-form command, message, and probe content, never a JSON sidecar or JSON argument. `sandbox-denied` requires both `targetProbe` and `controlProbe` evidence files. |
|
|
917
|
-
| `okstra config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Manage persistent settings such as `pr-template-path` with atomic JSON writes |
|
|
918
|
-
| `okstra memory <add\|list\|search\|show\|archive>` | Manage global conversation memory in `~/.okstra/memory-book`, a user-home store separate from project `.okstra/` and the CLI basis of the `save this in okstra` natural-language skill. `add --source-key <key>` records the source an entry stands for: adding the same key again returns the stored entry (`created: false`) instead of a second one, also when two adds race, and with `--json` a likely-secret refusal is printed as `{ ok: false, refused: "secret", secrets, message }`. An add without `--source-key` is unchanged |
|
|
919
|
-
| `okstra chat <rooms\|create\|join\|members\|send\|unread\|inbox\|log\|ack>` | Global rooms under `~/.okstra/chat`. Join takes an explicit `--name`. Send takes exactly one of `--to` (`all` or a member; may equal `--as`) or `--reply-to` (an id in that room), and exactly one of `--body` or `--body-file`; a body may span several lines. A reply inherits `to` from the parent (`all` stays `all`, otherwise the parent's `from`). Unread is the inbox after the read cursor minus messages the participant sent; it does not move the cursor. `inbox` and `log` keep those arrivals, including after ack. Rows are `id @from YYYY-MM-DD HH:MM body`; a reply inserts `↑parentId` after the time; the second and later lines of a body follow on rows indented by two spaces. `ack --through` rejects an id behind the current cursor. Room and display names `.` and `..` are reserved. A `.lock` left by a dead process (pid recorded in the file) or older than 5 s is reclaimed. CLI basis of the `okstra-chat` skill. |
|
|
920
|
-
| `okstra model-io verification-input --run-manifest <path>` | Validate the canonical run and its recorded frozen verification-input path, schema, cross-field constraints and byte digest before emitting QA declarations, procedure bodies and optional approved-plan fields as fixed text. Scalar values use JSON quoting to preserve command characters and line breaks. Current project settings are not reread. Errors return exit 2 without a partial input view. This is declaration input, not execution evidence. |
|
|
921
|
-
| `okstra model-io active-context-input --project-root <dir> --run-manifest <path>` | Resolve the prior implementation-planning active context only through the current project and run authority, then emit fixed fields such as the executor base ref. Caller-supplied active-context paths are not accepted. |
|
|
922
|
-
| `okstra convergence prepare-groups --run-manifest <path> --input <grouping.md> [--correction-round <N>]` | Parse fixed grouping Markdown, validate distinct per-worker evidence and group semantics against the run authority, then publish the schema-valid groups artifact at the run-owned path. |
|
|
923
|
-
| `okstra manager <init\|discover-projects\|new\|task\|list\|remove\|view> [--json]` | Public CLI for grouping cross-project okstra tasks into manager-owned context. The default is purpose-specific fixed text for model use; `--json` preserves the machine contract and exit codes. `new project --project-root` accepts only existing directories and performs setup-equivalent registration only if `.okstra/project.json` is absent. `list managers`, `list projects --manager-id <id>` and `list tasks --manager-id <id>` enumerate manager state; `view --manager-id <id>` writes `~/.okstra/managers/<id>/view/index.html` and prints its path and `file://` URL. `task split --plan <json>` writes one validated brief with a `## Project Scope` section into each project an issue is assigned to and registers those children; `task run` then passes `--task-brief`. `task run` re-reads the target child's state from its project and refuses a child that is already done there, naming its last phase and report, unless `--allow-completed` is given; `task status` prints `Synced at` and `Sync age` and marks children whose task manifest changed after that sync. For a child whose task type is `discussion`, `task sync` records a `discussion` block read from the discussion record without writing to it — state (`draft`, `completed`, or `unknown` when the record cannot be read), phase, pending questions, revisions with their change reasons, and each follow-up's pinned revision and impact-review state, re-read from the follow-up's brief — and `task status` counts the child under `discussion`, never under `done`. `task run` for a child without a registered brief takes the brief that `okstra discussion follow-up-brief` wrote for it, found in the last-synced links of a discussion child of the same manager task. `list task-groups` lists groups including empty ones; `task update` edits a task's objective, common brief or progress mode; `remove project`, `remove task`, `remove task-group` and `task remove-child` print their targets and delete manager files only with `--confirm`, and `remove project` keeps the project's children marked unlinked. |
|
|
924
|
-
| `okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>] [--text\|--json]` | Read-only backend for the okstra-rollup skill. `--text` emits ordered fixed labels for model use. The default and `--json` preserve the full machine JSON contract and exit codes. Omitting `--task-group` targets the whole project catalog. |
|
|
925
|
-
| `okstra usage-report [--days <positive-int>] [--project-root <dir>] [--cwd <dir>] [--text\|--json]` | Read-only backend for the okstra-usage skill. `--text` emits ordered fixed labels for model use. The default and `--json` preserve the full machine JSON contract and exit codes. Defaults to the current project's last 30 days. |
|
|
926
|
-
| `okstra worker-state transition --team-state <path> --worker <id> --status <in-progress\|completed\|timeout\|error\|not-run> [--reason <text>] [--model <execution-value>]` | Atomically update one persisted worker row. `in-progress` records the authoritative `startedAt` and clears `endedAt`; terminal states record `endedAt`; `timeout`, `error`, and `not-run` require a reason. Dispatch adapters use this same transition path, so CLI-backed and in-process orchestration share the status timestamp contract |
|
|
927
|
-
| `okstra worker-liveness [--team-state <path> --worker <id>]… [--max-idle <seconds>] [--launch-grace <seconds>] [--stall-confirm <seconds>] [--json]` | Judge whether pending workers are still alive so the lead's poll ends a stalled wait early instead of paying the full deadline. Prefer paired `--team-state <path> --dispatch-id <id>` options for identified attempts; do not mix them with `--worker`. Worker-name selection is retained only when the dispatch is unambiguous. Each retry starts a new wait for its own id. A selector error is a monitoring-input defect, not a failed worker. The worker row's `livenessMode` picks the probe: `audit-heartbeat` reads its `auditSidecarPath` and reports `stalled` when the `- PROGRESS:` heartbeat is past the idle budget; `wrapper-status` reads its `promptPath` and reports `did-not-launch` when neither the wrapper `.log` nor `.status.json` appears. Both graces start at the persisted `startedAt`, never at an artifact mtime — the audit sidecar is reused on re-dispatch, so a heartbeat older than this dispatch counts as no signal yet rather than a stall. A heartbeat budget breach is confirmed before it is reported: the probe re-reads the sidecar after `--stall-confirm` seconds (default: half that stage's budget; `0` disables) and reports `stalled` only when the newest heartbeat has not advanced, so a worker inside one long uninterruptible tool call is not judged dead for being slow. Healthy probes report `live`. It only judges—it never kills or re-dispatches. Exit 1 on an unhealthy verdict, so a poll loop can branch without parsing JSON. The heartbeat line shape and budget come from the `okstra_ctl.worker_heartbeat` SSOT shared with the Phase 7 audit (`validators/validate_session_conformance.py`) |
|
|
928
|
-
| `okstra verification-target --project-root <dir> --run-manifest <path> --expected-head <commit> --command <declared-command> [--baseline <json>]` | Read-only target observation for implementation and final verification. Reads the active run's worktree, checks the commit and rejects checkout-changing command syntax without executing the command. Save the JSON before the check; compare it with `--baseline` afterwards. Changed source fingerprints, commands, worktrees or commits invalidate reuse. A successful observation does not prove the declared command was executed. Exit 1 on a target or input error. |
|
|
929
|
-
| `okstra worktree-lock --worktree <dir> --command <declared-command>` | Launcher for an implementation verifier's Tier 1 command. Runs the command unchanged through `$SHELL -c` (or `/bin/sh`) with the worktree as its working directory, inside an exclusive `flock` keyed by the worktree's realpath, so the verifiers of one stage re-run fixed-port commands one at a time instead of killing each other's servers. Stdout and stderr pass through; the exit code is the command's (128+N for a signal). Lock notices go to stderr only. The lock file is `<okstra home>/.locks/worktree-exec/<hash>.lock` — outside the worktree and the project's `.okstra/`, which the verifier mutation audit watches. If that file cannot be created or locked, the command runs unlocked after a stderr warning. Exit 2 when `--worktree` is not a directory. |
|
|
930
|
-
| `okstra worker-audit-check --run-dir <runs/<task-type>/> --task-type <type> --seq <nnn> [--worker <id>]` | Apply the Phase 7 worker audit-sidecar rules mid-run, while the worker session is still alive. For each of this run's `worker-results/<worker>-<task-type>-<seq>.md` it checks that the file carries no `## 0. Reading Confirmation` heading, that the matching audit sidecar exists, and — for prompts carrying the required-v1 evidence-ledger marker — that every backticked `path:line` citation has an Evidence read row in that sidecar. `--worker` scopes it to the role that just returned. `--seq` accepts a bare number and zero-pads it to three digits, so `--seq 1` and `--seq 001` select the same run. Emits `{ok, inspected, inspectedFiles[], failures[], blocking[], advisory[], runImpact}` and exits 2 when `failures[]` (= `blocking` + `advisory`) is non-empty — and also when the selector matched no result file at all, in which case the payload carries `selectorError` and empty `failures[]`: nothing was judged, which is not a pass. Exit 2 means "fix it now", not "the run fails": only `blocking` rows (no audit sidecar) fail the run at Phase 7, while `advisory` rows (a citation with no matching Evidence read row) never fail the run and are only repairable while the worker session is alive — do not reject or re-dispatch a result over an advisory row alone. The rules come from the `okstra_ctl.worker_audit_ledger` SSOT shared with `validate-run.py`, so an early pass and the Phase 7 pass cannot disagree. Run it right after collecting a result: the same failure at Phase 7 leaves only a retroactive edit, which breaks the audit chain, or a failed run |
|
|
931
|
-
| `okstra prune-run-artifacts [--project-root <dir>] [--cwd <dir>] [--task-group <group> --task-id <id>] [--apply] [--text]` | List, under `.okstra/tasks` (or one task root) with sizes and a total, what no reader needs after a run: every `node_modules` and `.next` directory, and the dispatch snapshots (`*.mutation-audit.json`) and publication locks (`*.publish.lock`) that the team state records for a run whose `validation.status` is `passed`, or for an earlier run in the same run directory (lower manifest sequence) than a passed one. It removes them only with `--apply`. Symbolic links are neither followed nor removed; source copies, logs, lockfiles, diffs, prompts and results stay, so technical-verification experiment working directories remain valid. The `prune-run-artifacts` Phase 7 step does the same for its own run directory; this command cleans runs finalized before it |
|
|
932
|
-
| `okstra log-report [--project-root <dir>] [--cwd <dir>] [--top <N>] [--json]` | Read-only inventory of wrapper transcript `.log` files and their sibling prompt `.md` files. Each ranked entry preserves `path` / `sizeBytes` for compatibility and also reports `transcriptPath`, `transcriptBytes`, `promptPath`, `promptBytes`, and `transcriptToPromptRatio`; totals distinguish prompt bytes from transcript bytes and count paired files. Ranking remains transcript-size descending |
|
|
933
|
-
| `okstra recap <assemble\|record\|note> (<task-root\|task-key> \| --task-group <group>) …` | Backend for the okstra-inspect `recap` facet. `assemble` is read-only: for a task it prints a JSON summary of phase transitions across its runs; with `--task-group` it prints the group's start order (briefs in ordinal order, each `done` / `in progress` / `not started` from the catalog's task-manifests, memory entries only for tasks the catalog does not know) and every recorded task's latest conclusion from `group-context.md`'s Task Memory. `okstra model-io recap-input --task-group <group>` is the fixed-text projection of the same join. `record --kind <summary\|qa> --mode <artifact\|code> --answer <text> [--question <text>] [--citation <path:line> …]` appends one line to `<task-root>/recap/recap-log.jsonl`, or with `--task-group` to `.okstra/tasks/<group>/.recap/recap-log.jsonl`, and never mutates other artifacts. `note` is task-only. `note --kind <verification-evidence\|decision-draft\|analysis-note> --slug <topic> --purpose <text> --scope-note <text> (--body <markdown>\|--body-file <path>)` writes an agent-authored note to `<task-root>/notes/` and prints its path plus the `--clarification-response` argument for feeding it into a later run |
|
|
934
|
-
| `okstra user-response <list-view\|show-view\|begin\|answer\|plan-decision\|legacy-report-authoring\|finalize> …` | Backend for the `/okstra-user-response` skill. `list-view` and `show-view --report <md\|data.json> --project-root <dir>` are fixed-text model views; `show-view` validates that the report belongs to the explicit project root and prints each open row's why-asked line, linked plan items, and cited `path:line` artifacts so the skill can read them before asking. The legacy `list` and `show` JSON reads retain their automation-compatible fields. `begin --report <md\|data.json> --task-key <key>` returns an opaque transaction id. A predefined clarification choice uses `answer --transaction <id> --clarification-id <C-NNN> --kind <kind> --option-number <N>`; Python resolves the answer, disposition, reach, and scope effects from the validated report. Direct input instead uses `--disposition <answer\|reframe> --value-file <md> [--rationale-file <md>]`. Every value, rationale, and reason file must be a regular file under `<PROJECT_ROOT>/.okstra/tmp/user-response/`; external paths and symbolic links are rejected. `plan-decision` accepts `approved`, `revision-requested`, or `rejected`, validates any `--implementation-option` against the report candidates, and requires `--reason-file` for the latter two statuses. `legacy-report-authoring` is restricted to report contract 2.0. `finalize` validates the complete existing sidecar before a lossless merge, uses compare-and-swap under a run-local lock, and atomically publishes only the user-owned sidecar; exit 0 ok / 1 error. |
|
|
935
|
-
| `okstra option-comparison --report <data.json\|md>` | Read-only backend for the okstra-run comparison material. Prints one implementation-option-selection report's comparison facts as JSON: `criteria` (the eight evaluation criteria and their weights), `workers` (voting analysts in first-seen order), and per ranked direction `scores`, `scoreRationales`, the recorded `weightedScore` (publication already checks it against the recalculated value), `coverage` (verdict, counts, requirement ids), `safetyBlockers` and `unresolvedFeasibilityFacts` counts, and `votes` per worker (verdict, rationale, counterevidence); plus the report's `narrative` texts and `nextStep`, which is the next-phase pointer rationale. Exits 2 when the record has no `implementationOptionSelection` block or ranks no direction. |
|
|
936
|
-
| `okstra pr <template\|branches\|gen\|check> … [--json]` | Backend for the okstra-pr-gen skill. Git-only—no project registration required. `template list\|show <name\|default>\|add --name <name> (--content <text>\|--file <path>)\|path` manages PR body templates under `~/.okstra/template/pr/` (default `templates/pr/pr-body.template.md`, shared with release-handoff); `branches` recommends a base branch; `gen --base <ref> [--head <ref>] [--template <name\|default> \| --template-file <path>]` emits fixed `Base`, `Head`, `Current branch`, `Upstream`, `Merge base`, `Template name`, `Commits`, `Diff stat`, `Template`, and `Drafting rules` sections by default. `--head` reads a branch without checking it out. Commits and diff stat exclude what the base or its upstream already contains. `--repo <path>` on `branches`, `gen` and `check` reads that git work tree instead of the current directory (like `git -C`) and exits 1 when the path is outside one; `--template-file` and `--body-file` still resolve against the current directory. `check --body-file <path>` lists the lines of a drafted PR title/body that carry an okstra identifier (report ids, `.okstra/` paths, run artifact names, phase/stage/worker labels), skipping terms the repository's tracked files use; exit 1 when any is found. `--json` preserves the machine bundle for automation. |
|
|
937
|
-
| `okstra migrate [--apply] [--cwd <dir>] [--quiet]` | One-time migration of the project artifact root from `.project-docs/okstra/` to `.okstra/`. It is a dry run by default; `--apply` performs the move with `git mv` in a Git worktree, removes an empty `.project-docs/`, and synchronizes the `<PROJECT>/CLAUDE.md` import line, `.gitignore`, the project's rows in `~/.okstra/{recent,active}.jsonl`, and `~/.okstra/worktrees/registry.json`. It exits 1 if `.okstra/` already exists or the legacy directory is absent. Scheduled for removal by the end of v0.x |
|
|
938
|
-
| `okstra task-list [--project-root <path>]` | Combine `list_project_tasks` and `read_latest_task` into JSON containing the task catalog and latest task |
|
|
939
|
-
| `okstra task-show <task-key> [--project-root <path>]` | Summarize workflow, phase, status, and artifacts from the Task Read-Side Snapshot |
|
|
940
|
-
| `okstra stage-map <task-key> [--cwd <dir>\|--project <dir>]` | Dump the task's implementation-planning Stage Map as JSON: `{ ok, taskKey, taskRoot, state, sourcePlanPath, stages:[{stage_number,title,depends_on,step_count,cancelled}], doneStages:[int] }`. Each stage row carries `cancelled: true` when the plan marks that Stage Map row `status: cancelled`; such a stage is never selected, cannot be closed, and is left out of whole-task final verification and release handoff. `sourcePlanPath` is the task's latest implementation-planning report — the authority on which stages exist, so a plan amendment's added stages are selectable as soon as the amended plan lands. `state` is `ready` for a resolved source and `missing` when no Stage Map exists; a corrupt source returns a structured non-zero error instead of silently selecting another report. `doneStages` is read from the implementation-planning stage consumer state (with carry recovery). This is the read-side source `/okstra-schedule-gen [task-group]` uses to derive selectable unfinished stages and their completed dependency closure |
|
|
941
|
-
| `okstra stage-close <task-key> --stage <N> --from-commit <sha> [--supersede-failed <reason>] [--cwd <dir>\|--project <dir>]` | Record the `done` stage-consumer row an implementation run would have written, for a stage whose work is already committed but which never registered as done — the run ended before writing its carry sidecar, and `backfill_done_from_carry` recovers only from that file. Without it `stage-map` reports `doneStages: []` while the branch carries the commit, the next plan re-describes the stage, and every RED expectation it produces is unreachable. Refuses unless the Stage Map has that stage and does not mark it cancelled, no `done`/`failed` row exists for it, `--from-commit` resolves to a commit in the project repo, and the stage's conformance gate permits progress — the same `decide_conformance_gate` the run validator uses, so a stage closed here is not one the validator would have blocked. `--supersede-failed <reason>` closes a stage whose last row is `failed` under the same checks, for a failure that no longer applies (the checks ran in the wrong environment and the commit needs no product edit); the `done` row records `superseded_status`, the reason, the latest plan path and the conformance verdict. Closing also moves the `stage-<N>-exit` tag and releases the stage reservation, exactly as a normal stage completion does. Emits `{ ok, taskKey, taskRoot, stage, headCommit, conformance, consumersPath, supersededFailed, sourcePlanPath }` |
|
|
942
|
-
| `okstra stage-reopen <task-key> --stage <N> --reason <why> [--evidence <path>] [--cwd <dir>\|--project <dir>]` | Append a `failed` stage-consumer row after a stage's `done` row, so `/okstra-run` offers that stage again for a fix run and its dependents stop branching from the withdrawn head. Use it when a later verification found a defect in a done stage — a single-stage final-verification that ended `blocked` and points at `implementation` is the case the wizard otherwise refuses. The row records the reason, `reopened_by: stage-reopen`, the head it withdraws and, with `--evidence`, the project-relative report path. Refuses a stage that is not in the latest Stage Map, is cancelled, or whose last row is not `done`. Emits `{ ok, taskKey, stage, headCommit, reason, evidencePath, consumersPath }` |
|
|
943
|
-
| `okstra correction prompt --run-manifest <path> --round <N> --role <executor\|verifier> --base <sha> [--stage-base <sha>] [--finding <F-id> ...]` | Print the instruction body for one correction-round prompt of an implementation run, built from the convergence record that preceded the round (the run's initial one for round 1, round N-1's `convergence-correction-r<N-1>-…` re-convergence for round N): the findings to fix, the stage HEAD before the round, and the executor's or verifiers' rules. `--stage-base` adds one `FILE-SIZE:<path>` finding per file that `<stage-base>..<base>` leaves over the 500-line limit (advisory 300-line lines are not added); a round needs at least one finding from either source. Pass it to `okstra agent-prompt materialize --dispatch-kind correction-r<N>`. At most 2 rounds; exit 1 on an unknown finding or round. |
|
|
944
|
-
| `okstra correction file-size --base <stage-base> [--head <rev>] [--repo <dir>]` | Check a stage diff against the file-size limit (500 lines, blocking) and target (300 lines, advisory). A threshold is broken by a file the diff adds over it or takes past it; the target is also broken by a file the diff grows while already over it, including a file already over the limit at the stage base, which the limit does not block. Prints `FILE-SIZE:<path>:501 <before>-><after> lines (<kind>; limit 500)` per limit breach and `FILE-SIZE-ADVISORY:<path>:301 … (<kind>; target 300)` per file that breaks only the target, then `QA-RESULT: PASS\|FAIL`; only a limit breach fails. Lines are physical lines. Only `.py`, `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.kt`, `.kts`, `.rs` and `.java` files are checked; `.okstra`, `node_modules`, `vendor`, `fixtures`, `__fixtures__`, `__snapshots__`, `generated` and `__generated__` directories, `*.min.*` files, and files whose first 5 lines say `@generated` or `do not edit` are exempt. Writes nothing. Exit 1 on FAIL, 2 when git cannot read the range. |
|
|
945
|
-
| `okstra stage-done <task-key> --stage <N> --carry <carry.json> --report <path> [--cwd <dir>\|--project <dir>]` | Settle an implementation stage whose verdict is not FAIL: write the executor's Stage Carry Evidence JSON to the flat `runs/implementation/carry/stage-<N>.json`, then append the `done` row with that carry path, the report path relative to its run directory, the carry head and the completion time. A reopened stage's previous sidecar moves to `carry/superseded/stage-<N>-from-<task-type>-<seq>.json`. Refuses a carry for another stage, a failed carry, a stage already done at another head, and a carry whose `stageCommitRange` diff breaks the 500-line file-size limit (`okstra correction file-size`; the refusal names the `--stage-base` for a correction round); a repeat with the same carry writes nothing new. Prints JSON with `fileSizeCap` (`pass: <range>` or `not checked: <reason>`); exit 1 on a refusal. |
|
|
946
|
-
| `okstra stage-fail <task-key> --stage <N> --head-commit <sha> --report <path> --reason <why> [--cwd <dir>\|--project <dir>]` | Append the `failed` stage-consumer row an implementation run writes when its verdict is FAIL or no verifier returned a result. Dependents stay blocked and the stage becomes selectable for a fix run. Refuses a stage missing from or cancelled in the latest Stage Map, or already `done` (use `stage-reopen`). Prints JSON; exit 1 on a refusal. |
|
|
947
|
-
| `okstra discussion <confirm-subject\|ask\|address\|answer\|decide> <task-key> … --run-manifest <path>` / `okstra discussion draft <task-key>` | The facilitator's only way to write a discussion task's record under `<task-root>/discussion/`: the confirmed subject and question, questions for the user (`ask`), the user's question to one worker (`address`), answers and user decisions. `--run-manifest` must be a discussion run manifest of the same task; authors are `leader` or a worker of that run, and only a question's addressee answers it. A resent record returns the stored one (`created: false`). Every write rebuilds `draft.json`; `draft` prints it as the fixed text every participant reads. Write commands emit `{ ok, created, record, pendingForUser, pendingForParticipants }`. `add-material --kind <evidence|alternative>` records new evidence or a new alternative, and `status` prints the phase, the next question for the user, unrecovered failures and remaining disagreements |
|
|
948
|
-
| `okstra discussion <cycle-open\|settle\|cycle-close> <task-key> --run-manifest <path>` / `okstra discussion recover <task-key> --failure <X-NNNN> --choice <retry\|replace\|reduce> --run-manifest <path>` / `okstra discussion <question-prompt\|collect-answer> <task-key> --question <Q-NNNN> --run-manifest <path>` | The research, refutation and question cycle of a discussion, one research cycle per run. `cycle-open` writes the research instruction from the record and records its input references (start inputs, subject, answers, materials), or returns why nothing is dispatched: `await-user`, `await-participant`, `await-recovery`, `present-options` (the references equal the last closed cycle's) or `prepare-run` (the next cycle needs a run prepared with `--discussion-start <task-key>`). `settle` records each analyser's `initial` result and each failure the dispatcher left after its retry loop (`start` when the batch could not launch, `after-retries` otherwise); `recover` records the user's choice for one failure. `cycle-close` validates the run's convergence final state and imports its findings as claims with their origin worker and verdicts. `question-prompt` writes one direct question's instruction and `agent-prompt materialize --batch` file (dispatch kind `discussion-question`), and `collect-answer` records the addressee's whole result as the answer |
|
|
949
|
-
| `okstra discussion <add-requirement\|add-scope> <task-key> --text <what> --author <user\|leader\|worker-id> --run-manifest <path>` / `okstra discussion confirm-completion <task-key> --draft-version <sha256:…> --direction <text> --risk <text> --run-manifest <path>` / `okstra discussion reopen <task-key> --revision <task-key/revision-NNN> --reason <text> --run-manifest <path>` / `okstra discussion <revisions\|record> <task-key>` / `okstra discussion revision-show <task-key> --revision <id>` / `okstra discussion memory-sync <task-key> [--revision <id> [--summary-file <path>]]` | User completion of a discussion. `add-requirement` (`--applies-to <common\|follow-up label>`) and `add-scope --kind <in-scope\|excluded>` record the current draft's requirements and scope; an item the draft already holds is returned instead of added twice. After `reopen` the draft starts with the reopened revision's requirements and scope under their original record ids, marked with that revision, so unchanged items are not entered again; `okstra discussion withdraw <task-key> --item <N-NNNN\|B-NNNN> --reason <text> --run-manifest <path>` removes one item with the user's reason, and replacing an item is a withdrawal followed by an addition. `confirm-completion` binds the user's direction and risk confirmation to the draft version `status` prints, refuses a stale version or a draft missing its subject, a requirement, a scope entry, a closed research cycle, an answer or a failure choice, and publishes one read-only revision `<task-root>/discussion/revisions/revision-NNN.json` (id `<task-key>/revision-NNN`); a resent confirmation returns it. A completed discussion takes only `reopen`, which names the latest revision and the reason; the next revision carries both and lists under `itemChanges` the items it carried, added and withdrawn. `revisions` lists the publications, `revision-show` prints one revision byte-for-byte, `record` prints the draft read model with every research result in full. The run's final report references the revision only by id and content digest. After publication, `confirm-completion` registers the revision in the Memory Book without a prompt (`okstra memory add --source-key discussion:<revision-id>`): a summary of decisions, disagreements, risks and unverified scope with the revision id, content digest, project and task, kept with its registration state in `<task-root>/discussion/memory/`; its `memory` field names the entry or the state. A failed registration leaves the revision published and `pending`; `status` lists it under `memoryRegistration`, and `okstra discussion memory-sync <task-key>` retries it with the same source key. A summary refused as a likely secret is `refused` and is not retried until `memory-sync --revision <id> --summary-file <path>` supplies a changed summary |
|
|
950
|
-
| `okstra discussion follow-up-brief <task-key> --revision <id> --follow-up <label> --target-task <task-key> [--target-project-root <dir>] [--end-state <N-NNNN>=<EB\|PB\|EO>[:<how>]]… [--replace]` / `okstra discussion links <task-key>` / `okstra discussion impact <task-key> --from <id> --to <id> [--follow-up <label>]` / `okstra discussion apply <task-key> --revision <latest id> --target-task <task-key> --choice <adopt\|keep> [--end-state …]… [--replace]` | Follow-up tasks of a published revision, run outside a discussion run at the user's request. `follow-up-brief` writes `<target-project-root>/.okstra/briefs/<task-group>/<task-id>-<label>.md` from the revision's common requirements and those of `--follow-up`, through `validators/validate-brief.py`; it recommends `requirements-discovery` and pins the discussion, revision id, content digest and requirement ids in the frontmatter, which prepare copies into the run inputs as `discussionRevisionRef`. `--end-state` maps a requirement to an `EB`/`PB`/`EO` item; an observation method the revision does not carry leaves the brief `reporter-confirmations: pending` with an `intent-check:` row for the user. The brief is written before the link in `<task-root>/discussion/links.jsonl`, so a resend after an interruption records the link once; a brief this command did not write last needs `--replace`. `links` re-reads every target (`current`, `needs-impact-review`, `kept`, `amendment-pending`, or `unknown` when the target cannot be read), `impact` prints the changes between two revisions, and `apply` records the user's choice for one target and the latest revision: `keep`, or `adopt`, which rewrites the brief of a target without an implementation-planning plan and routes a target with a plan to the plan amendment path without touching its plan, brief or source. A resent choice returns the stored record. `okstra discussion complete-amendment <task-key> --revision <id> --target-task <task-key> [--end-state …]… [--replace]` finishes a routed adoption once the target has an implementation-planning report newer than the one it had at routing whose `frontmatter.approved` is `true`: it rewrites the brief to pin the revision and records the plan report it relied on, and `links` then shows the target `current`. Without such a report it is refused and names what is missing, and `links` shows the same in the target's `next`; it never edits or approves a plan |
|
|
951
|
-
| `okstra incremental-scope <args…>` | Decide re-verify vs carry-forward scope for an `implementation-planning` clarification re-run. Thin shim into `scripts/okstra_ctl/incremental_scope.py` (deterministic): it reads the dependency graph from the prior run `data.json`'s `implementationPlanning.stageMap` and returns `mode:"incremental"` only when the base-ref SHA is unchanged and the affected stages' `downstream_stage_closure` covers at most half of all stages; `--full-reason` (selected option / Stage Map / approach) still forces `mode:"full"`. An answered `C-NNN` that traces to no stage returns `mode:"unresolved"` rather than full — pass `--impacted` with the stage numbers or `--full-reason`. `--run-manifest <path>` is required for a decision (not for `--preview`): the same decision is written to the record that manifest names in `incrementalDecisionPath`, so the report writer's authoring contract and `okstra incremental-carry` read it instead of CSVs the lead re-typed. `mode: "unresolved"` is a question back to the lead and is deliberately not recorded. `--preview --prev-data <path> --answered-clarifications <csv>` runs the link half alone — no base SHA, no side effects — and prints `{wouldForceFull, unlinkedIds, reason}`; unlinked ids set `wouldForceFull: false` and fill `unlinkedIds` |
|
|
952
|
-
| `okstra incremental-carry <args…>` | Merge carried-forward plan-item verdicts into an incremental re-run. Contract v3 takes `--prev-data`, `--cur-narrative`, and the convergence-owned `--state`; it verifies carried stage rows and writes only `--out-state`, tagging copied verdicts with `carriedForwardFromSeq`. Pass `--decision <incrementalDecisionPath>` for the two stage sets — the same record the report writer's authoring contract was built from — instead of `--carry-stages` / `--reverify-stages`, which the lead re-typed off stdout; the two forms cannot be combined, and a record whose `mode` is not `incremental` is refused. Unchanged `P-Val-*` / `P-Req-*` / `P-Rb-*` rows whose extract hash still matches are carried the same way, and the sibling `plan-items-*.json` `dispatchQueue` is rewritten to match. The historical v2 `--cur-data --out` form remains readable. Ownership, scope, item, or schema drift raises `CarryError` and forces a full fallback. |
|
|
953
|
-
| `okstra code-review target --task-key <k> --stage <N> [--project-root <dir>] [--cwd <dir>] [--json]` / `okstra code-review target --branch <name> --base <ref> [--date <YYYY-MM-DD>] [--project-root <dir>] [--cwd <dir>] [--json]` | Resolve what a code review reads and where its result file goes. Output is always JSON, so `--json` only makes that explicit. `--project-root` and `--cwd` are shared pre-dispatch arguments and apply to both modes; `--cwd` is only consulted when `--project-root` is absent. Both modes return `{ ok, projectRoot, mode, worktreePath, branch, baseCommit, headCommit, reviewPath, round }`; stage mode additionally returns `taskKey`, `taskRoot`, and `stage`. Stage mode takes the diff base from the `base_ref` recorded on that stage's worktree-registry row when it was provisioned — not from a rule re-applied at review time — and names the result `.okstra/tasks/<task-group>/<task-id>/code-reviews/stage-<NN>.md`, where a re-review of the same stage becomes `-r2`, `-r3`, … (the `round` field). Only a legacy row provisioned before `base_ref` was recorded falls back to re-deriving the base through `stage_targets`, and a failure there is reported as `stage_base_unresolved`. `worktreePath` comes back empty whenever the stage worktree is not usable as a live checkout — the registry row is no longer `active` (whole-task final-verification released it), the row never carried a path, or the recorded directory is gone — and the review then reads the `branch` ref instead. Branch mode requires an explicit `--base` branch or commit, rejects invalid refs, freezes it as a commit, leaves `worktreePath` empty for fixed-head reads, and names the result `.project-docs/code-reviews/<branch>/<YYYY-MM-DD>-<NN>.md`, where `<NN>` (the `round` field) is the next sequence number for that date — the highest already on disk plus one. Read-only: it resolves paths and creates no directory and no file, so the review directory does not exist until the caller writes the report. Backend for the okstra-code-review skill |
|
|
954
|
-
| `okstra code-review check-coverage --project-root <dir> --base <baseCommit> --head <headCommit> --census <table-path> --completion <completion-path> [--completion <gap-fill-path> ...]` | Audits compact grouped-cell verdicts from one reviewer's verified standalone completions. Rejects changed model assignments, invalid evidence or a declared Review head baseline different from the requested head (exit 2); lists missing/unknown IDs (exit 1); complete usable coverage exits 0. The census has `## Rules` (Rule, Group, Reference) and `## Cells` (Cell, Target, Group) tables. Each result row explicitly accounts for the group's rules through Checked, N/A and Findings, with one target-source path:line that exists at `--head`; evidence files are read from that commit, not the working tree. Explicit `base:path:line` evidence reads the supplied `--base`; line 0 is a file-level anchor accepted only for an empty regular file. `check-lines` also accepts removed base lines and changed empty-file anchors. Checked general G2/G3/G5 criteria also require source-cited observations after ` :: ` in Evidence. Missing rules or observations are reported without expanding a target-by-bullet table; the lead audits selected references and semantic truth. |
|
|
955
|
-
| `okstra code-review scope --project-root <dir> --base <baseCommit> --head <headCommit> --census <path> --policy <path> [--policy <path> ...] [--previous-head <priorHead> --previous-census <path> --completion <path> ...]` | Read-only scope proposal per reviewer. Fingerprints catalog resources and all supplied policy/calibration/instruction sources; prints the baseline, Recheck IDs and Carry candidates. Verified prior completion baselines and dependency inventories permit candidates only for unchanged clean/N/A cells with identical identities. Prior findings, changed dependencies and missing inventories reopen cells; changed rules/base, rewritten history or unmapped changed files require full inspection. Invalid input/evidence exits 2. Pass the skill, calibration, duty and applied project instructions as policies. Current reviewers independently validate the impact closure and publish full current verdicts through the existing completion boundary; candidate status never proves a clean verdict or dependency completeness. |
|
|
956
|
-
| `okstra set-work-status <token> <todo\|in-progress\|blocked\|done> [--note <text> \| --note-file <path>] [--task-group <g>] [--project-root <dir>]` | Update user-managed `workStatus`. Existing briefs can be registered without a run. Direct completion requires a work and verification summary; use a UTF-8 note file for longer results. Records are shared through group context, inspect, and subsequent runs without claiming cross-verification. Ambiguous IDs return `matches[]`. A `share` failure with `statusRecorded:true` can be retried with the same command. |
|
|
957
|
-
| `okstra worktree-lookup <project-id> <task-group> <task-id>` | Return the `worktree_registry.lookup` result: reserved path, branch, base ref, and current status |
|
|
958
|
-
| `okstra worktree-status [--path <dir>] [--check-clean]` | Answer "is this worktree clean?" over source paths only, excluding what okstra provisioned there — `.okstra`, the configured sync entries (`.project-docs`, `.claude`, …), and any nested stage worktree. A bare `git status --porcelain` in a task worktree is never empty for that reason, so a plan step asserting a clean tree with one fails on okstra's scaffolding instead of on the stage's own work; this is the same gate `handoff` and stage integration use. Output is JSON `{ ok, path, clean, entries, excluded }` where `entries` holds the `git status --short` rows that made it dirty. Exit code is 0 regardless unless `--check-clean` is given, which exits 1 on a dirty tree so it can stand as a shell assertion (`okstra worktree-status --check-clean`). okstra writes `stage-<N>-exit` itself when it settles the stage, so a plan step must not tag. A path outside a git work tree exits 2 rather than reporting a clean tree |
|
|
959
|
-
| `okstra plan-validate <plan-path>` | Run `_validate_approved_plan` and report frontmatter `approved` recognition plus unresolved Blocks=approval rows |
|
|
960
|
-
| `okstra render-bundle <args…> [--stage <auto\|N>] [--stages <csv>] [--summary-only]` | Thin shim over `prepare_task_bundle(render_only=True)` with the same signature as `python3 -m okstra_ctl.run --render-only`. `--summary-only` omits the lead prompt body from stdout while preserving preparation status, artifact paths, concurrency warnings, and all saved artifacts; default output still includes the full prompt. `--stage` is for `implementation` and `final-verification`: for implementation, `auto` (default) selects the earliest incomplete stage with satisfied dependencies, while `<N>` forces a stage; for final-verification, `<N>` verifies one stage with artifacts under `runs/final-verification/stage-<N>/` and a `-fv-s<N>` team suffix, while an empty value performs whole-task verification with the flat layout. The separate `--stages <csv>` channel is for `release-handoff`: it names the stages to open a PR for, one PR per stage, and an empty value takes every eligible stage. Preparation enforces eligibility—`done` + accepted `verified` + not yet `pr`—and automatically creates an input document that cites verification reports. `--discussion-start <link\|text\|task-key>` is for `discussion`, which takes no `--task-brief`: prepare records the start input in the task's discussion record and writes the input document from it |
|
|
961
|
-
| `okstra profile show <task-type> [--resolved]` | Print a phase profile. `--resolved` expands its `{{INCLUDE:}}` targets and appends the lazy-read sidecars named in the profile body — transitively, because sidecars name sidecars of their own (`_implementation-executor.md` points at the coding-conventions preflight, the diff-review sweep, and the completion self-check). That matters because a profile is assembled from three places, so grepping only the top-level file returns false negatives: `grep clarification scripts/okstra_ctl/phases/implementation/profile.md` finds nothing while the assembled profile has many hits. One grep over this output answers whether a task-type covers a rule. The sidecar list is read from the profile body, never hard-coded, so a newly added sidecar is picked up without a code change. Read-only: it writes no manifest and registers no run, which is what separates it from `render-bundle` — `render-bundle` answers the same question but records a run in `recent.jsonl`, so it cannot be used to look something up. Exits 2 for an unknown task-type |
|
|
962
|
-
| `okstra codex-run <args…>` | Codex lead-adapter dry-run entry point. Accepts the same arguments as `render-bundle` but owns `--render-only --lead-runtime codex`. It prepares the task bundle and prints the prompt for the Codex lead without dispatching workers |
|
|
963
|
-
| `okstra worker-dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--dry-run]` | Provider-neutral deterministic dispatcher for `runner=cli-wrapper` assignments. It verifies each adjacent invocation specification against the immutable run manifest immediately before process creation and records `core-pre-dispatch`; native-session rows stay with the host. The default selects CLI analysis assignments only. Phase 6 uses explicit `--workers report-writer`, and a mixed analysis/report batch is rejected. `--dry-run` performs the same verification and resolution without starting a provider process. A real dispatch records the lead checkpoints it owns in the run's lead-events ledger and returns them as `progressLines`: `phase-3-team-create` when it writes the implicit-team marker, `phase-4-dispatch` for each `initial` job, `phase-6-synthesis` on the first report-writer dispatch, and `phase-5-collect` for each `initial` dispatch it settled. |
|
|
964
|
-
| `okstra codex-dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--dry-run]` | Compatibility alias for `okstra worker-dispatch`; it no longer selects a Codex-only transport-agent path. |
|
|
965
|
-
| `okstra agent-prompt resolve-operation --operation <id> [--json]` | Print what a non-run operation runs: its duty, its canonical role, the worker count, and one slot line per worker carrying that slot's provider and model reference. The operation contract (`agents/operations/<id>.json`) owns the duty and the count; the models come from the same project/global/bundled default chain a run uses, one distinct model per slot. A machine with fewer distinct models than the contract requires fails here rather than dispatching a short roster. The default output is fixed text because a skill body must not instruct a model to parse okstra-owned JSON; `--json` is for programmatic callers. |
|
|
966
|
-
| `okstra agent-prompt jobs --project-root <dir> --run-manifest <path> --dispatch-kind <kind> --metadata <path> [--metadata <path>] --out <path> [--json]` | Generate an immutable v2 jobs file from verified invocation metadata. Reads canonical identity, role, five digests, and actual result anchors; validates the full batch through the dispatch consumer before publishing. Rejects mixed runs or dispatch kinds and duplicate attempts. Reuses identical output; preserves differing output and requests a new `--out` path. Does not launch workers. |
|
|
967
|
-
| `okstra agent-prompt materialize --project-root <dir> --run-manifest <path> --batch <file> [--jobs-out <path>] [--json]` | Materialize every invocation of one dispatch batch in one call. The batch file holds `{"invocations": [...]}`; each entry maps the run-mode per-invocation flags (`invocation-id`, `audience`, `instruction`, `prompt`, `worker-id`, `dispatch-kind`, `assignment-ref`, `source-role-execution-ref`, `result`, `corrections`, `audit-source`, and `replace-undispatched: true`) to values. Every entry goes through the same parser and materialization as a single call and fails with the same error. Entries run in order; a failure names the entry and every invocation already published, and an identical rerun after the fix reuses those. An unknown key, a repeated invocation id, a per-invocation flag given at the top level, or mixed dispatch kinds under `--jobs-out` is refused before any entry is written. `--jobs-out` (also accepted by a single run-mode `materialize`) writes the verified jobs file for `okstra team dispatch --jobs-file` exactly as `agent-prompt jobs` would; every entry must share one dispatch kind. Prints each prompt path and then the jobs path; `--json` returns `invocations` (one single-call payload each) and `jobsPath`. |
|
|
968
|
-
| `okstra agent-prompt materialize\|check-corrections\|apply-corrections\|verify\|record-dispatch\|link-result\|reject-result\|abandon-attempt\|materialize-result\|complete\|verify-completion` | Internal invocation-contract CLI. `materialize` composes model assignment, functional duty, and task instructions; `verify` rejects identity, path, snapshot, assignment, source, or digest drift. Every run-branch report-writer prompt gets its `## Output` section (narrative, pointer record, reading audit) rendered by okstra, and an instruction body that writes a `## Output` or `## Corrections` heading is refused. A corrective report-writer round — the narrative at `reportNarrativePath` already exists and its structure parses, value defects included — must pass `--corrections <ledger>` (`schemas/report-writer-corrections-v1.0.schema.json`: `replace` / `remove` / `add` / `move` / `rewrite` entries keyed by the validator's field-path grammar, `baseNarrativePath` naming a preserved copy of the attempt, and optional `baseNarrativeSha256` binding that version): the ledger is applied to that base and checked against the writer-owned schema and the task's semantic validator before dispatch, every defect is reported at once, and okstra renders the prompt's `## Corrections` section from it; a report-writer materialization without a ledger over such a narrative is refused before any prompt is written, while a narrative whose structure does not parse (line grammar, unknown top-level field) is re-authored without one. `check-corrections --run-manifest <path> --corrections <ledger> [--json]` runs the same check without materializing (exit 1 lists the defects; `mechanical: true` means every entry is a validated `replace`, `remove`, `add`, or `move`, including derived planning step counts). `apply-corrections` with the same arguments applies such a mechanical ledger without a writer round: it writes the corrected narrative to `reportNarrativePath` and records a `lead-correction-applied` activity row (`evidenceRefs` = ledger path + correction ids) through the run's activity contract; `--rewrite-results <file>` also accepts hash-bound replacement values for exactly the requested rewrite ids. Correction-only materialization sends those target fields, evidence, and constraints instead of the initial instructions and complete synthesis packet; the runtime merges the submitted values and checks the complete narrative before writing. It refuses unresolved `rewrite` entries or any defect, a stale live narrative, a base that is the live narrative, a run without `activityContractVersion` 1, and a ledger already applied. An empty ledger can preflight the initial writer result and derive `stageMap[].stepCount` from matching execution rows without another writer call. Run-backed calls resolve `assignmentRef` from the manifest, enforce `authorizedPaths`, and reject real-path or symbolic-link escape. `record-dispatch` records a verified host-native specification before dispatch and `link-result` binds the accepted result; one result path belongs to one dispatch, so a corrective round retires the first attempt with `reject-result --dispatch-id <first> --superseded-by <corrective> --reason <text>` before the new link is accepted — the rejected row stays in `agentResultLinks` carrying `supersededBy` and `rejectionReason` rather than being deleted. The corrective dispatch is a new invocation: an invocation whose last attempt finished with a mutation takes no further attempt (`execution_manifest._validate_next_attempt` lets only `failed-no-mutation` be followed), so a retry attempt of the rejected invocation itself is refused by the manifest, and `reject-result` does not make it possible. `abandon-attempt --invocation-ref <ref> --reason <text>` closes a started attempt whose worker died without producing a result — the one case neither `link-result` (which needs the result file) nor the dispatch-failure path covers — so a retry can follow it instead of the run having to be re-rendered. It refuses any attempt whose `writePolicy.sourcePolicy.mode` is not `source-readonly`: closing an attempt records `failed-no-mutation`, which is true by policy for a read-only worker and a guess for a mutating one. Standalone calls are identified by `(purpose, invocationId)` under `.okstra/agent-invocations/<purpose>/`; they publish a canonical result envelope and publish the completion marker last. Consumers use only the `returnedBody` from `verify-completion`. Metadata contains exactly `catalogDigest`, `assignmentDigest`, `dutyDigest`, `instructionDigest`, and `promptDigest`; JSON inputs use UTF-8, sorted keys, compact separators, and no non-finite values, while duty files use versioned sorted-name/byte framing. Instruction sources use `{kind: project\|runtime, path: <relative POSIX path>}` and never persist an installed absolute runtime path. A published prompt is immutable, so re-running `materialize` with an edited instruction file fails as `existing_invocation_conflict`; `--replace-undispatched` is the one exit, for a call that failed a pre-dispatch gate and therefore ran nowhere — it covers a differing prompt and a differing metadata alike, since the two are published together and describe one call. It republishes prompt and metadata together, and it is verified rather than trusted — a row in `agentDispatches` or `workerDispatches` naming this `invocationId` refuses the replacement and names the dispatch that used it. |
|
|
969
|
-
| `okstra agent-prompt refreeze-contracts --project-root <dir> --run-manifest <path> [--json]` | Re-freeze one run's duty contract snapshot in the installed format and stamp `agentContract.catalogDigest` and `contractFormatVersion` on its run manifest. A run freezes its contracts at prepare time and pins their digest; installing a release that changed the contract format leaves that digest unmatchable, so the run can materialize no further prompt and `materialize` stops with the format message naming this command. It replaces the frozen directory's contents (no file of the old format is kept), touches no prompt, result or ledger, and reports `changed: false` when the run is already on the installed format. User-invoked recovery only — nothing runs it automatically, because a run's contracts are frozen on purpose. |
|
|
970
|
-
| `okstra team dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--jobs-file <path>] [--dry-run]` / `okstra team await --project-root <dir> --run-manifest <path> [--json]` / `okstra team teardown --project-root <dir> --run-manifest <path> [--dry-run] [--json]` | Read a `leadRuntime=external` run manifest and dispatch, await, or tear down pane-backed workers. On a `cmux-pane` run, dispatch records `phase-3-team-create` when it writes the implicit-team marker, `phase-4-dispatch` for each `initial` job and `phase-6-synthesis` on the first report-writer dispatch; await records `phase-5-poll` and `phase-5-collect` for each `initial` dispatch it settled. Both write the run's lead-events ledger and print the `PROGRESS:` lines to emit (`progressLines` under `--json`). Any other run records nothing there. Default dispatch excludes report writer; Phase 6 selects it explicitly, and mixed analysis/report jobs are rejected. If a pane cannot be opened, gracefully degrade to the CLI wrapper, print a `DEGRADED <role>: cmux-pane -> cli-wrapper (<why>)` line to stderr (stdout stays one JSON object), and record the fallback in `workerDispatches[].degradedFrom` with the reason in `degradedReason`. A degraded worker is not waited for inside the dispatch — it settles through `okstra team await` like a pane worker, so the round still runs concurrently |
|
|
971
|
-
| `okstra agent-activity append --project-root <dir> --run-manifest <path> --kind <kind> --agent <assigned-id> (--summary <text>\|--summary-file <markdown>) --outcome <outcome> [--plan-item-id <current-id>]… [--command <text> --command-cwd <dir> --command-exit-code <n> --command-output-file <markdown>] [--request-ref <returned-ref>]` | Append one structured activity after checking the agent against this run's role assignments and every plan item against its current convergence state. Python returns an `activityRequestRef`; supply only that returned value with `--request-ref` to retry idempotently. A new call without it remains a distinct activity even with identical contents. Legacy JSON command records remain automation compatibility only. |
|
|
972
|
-
| `okstra agent-activity project --project-root <dir> --run-manifest <path> --data <data.json>` | Project this run's canonical activity events into `agentActivity[]`. The command preserves event order, rejects duplicate or decreasing activity IDs, and replaces no other report field. A historical manifest without `activityContractVersion: 1` returns an empty projection and leaves data.json unchanged. Normal Phase 7 execution reaches this behavior through `report-finalize`; use the standalone command only for diagnostics. |
|
|
973
|
-
| `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id> [--worker <role>] [--field NAME=VALUE]… [--detail <text>]` | Append one `PROGRESS:` checkpoint to the run's `leadEventsPath` and print the line to emit to the user as `progressLine`. The checkpoint is what `validate_session_conformance.py` reads, and on a host whose adapter declares `sessionAccounting: artifact-only` the ledger is the only place it can read one — a conversation line alone is not retained there. `--phase` accepts the phase ids the lead contract's "Progress reporting (BLOCKING)" list defines; the fixed-prose checkpoints render their contract wording without `--detail`. `--worker` is resolved against team-state and rewritten to the roster `workers[].role` the per-worker checks match, so a phase-specific functional label still lands on the right worker; a name that matches no roster row is written through with a note on stderr. |
|
|
974
|
-
| `okstra approval-decision <open\|resolve\|carry> --ledger <approval-decisions.json> …` | Write the lead-owned clarification and approval ledger. `open` validates classification-specific dispositions and complete option fields, and its repeatable `--supersedes <C-NNN>` names a carried decision the new question replaces (assembly publishes that carried row as `obsolete` once the new row is resolved), and `--candidate-ref <IO-NNN>` names the implementation option the decision is about (a candidate's `splitAcceptance` may cite only a decision opened for it), `resolve` requires real `A-NNN` check references, and `carry` keeps prior resolved decisions outside the active clarification list. `carry --from-responses <instruction-set/clarification-response.md>` is the source of truth for an answer given in an earlier run: the bundle is task-level and cumulative, each response section names the report that posed the question, and `--clarification-id` repeats to carry several ids in one call. `carry --source-ledger` remains for a prior run's ledger that is still on disk and needs `--source-run-ref`. Prepare seeds `carriedDecisions[]` itself when it creates a run's ledger from a `--clarification-response` that names a report record — every row that record answered or resolved, plus rows its user-responses sidecars answered (`scripts/okstra_ctl/approval_decisions.py` `seed_carried_decisions`) — so `carry` is for ids that record does not answer. |
|
|
975
|
-
| `okstra option-votes gaps --task-manifest <task-manifest.json> (--report <final-report .data.json> \| --narrative <report-writer narrative.md>) [--json]` | List the `implementation-option-selection` candidates that fail the ranking rule on the every-analyser clause alone, and name the analyser owing each vote. Round 1 runs the designers in parallel, so each votes only on the candidates it proposed and the merged set keeps a different hole per analyser; a run whose comparison had converged can end `blocked` with an empty `rankedOptions` for that reason alone. The lead reads this before concluding `blocked` and dispatches one vote-completion assignment per named analyser — a feasibility verdict on the named candidate and nothing else, so the run stays in `candidate-comparison` mode. A candidate carrying `safetyBlockers` or `unresolvedFeasibilityFacts`, or one that could not reach two `feasible` votes even with every missing vote, is excluded: another round would not change it. `--narrative` reads the writer's markdown before assembly and tolerates its value defects; `--report` reads a published record. |
|
|
976
|
-
| `okstra design-snapshot --narrative <report-narrative.md> --output <design-preparation.json>` | Detect implementation-planning design surfaces and write the detector-owned snapshot consumed by final report assembly. |
|
|
977
|
-
| `okstra plan-verify --narrative <report-narrative.md> --state <plan-body-verification.json>` | Recompute the plan-body gate from the convergence-owned state before `data.json` publication. `--report <historical-data.json>` remains the v2 reader. |
|
|
978
|
-
| `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run Phase 7 in the manifest's contract order. Contract v3 collects usage into team state, assembles all single-owner inputs into `data.json` once, renders the views from that record (the report writer already wrote its prose in `reportLanguage`), spawns follow-ups, records a `verified` row per cleared stage for a release-ready final-verification (`record-verified`, the same write as `okstra handoff record-verified`), validates, records the run's conclusion and the group's start order into the task-group's `group-context.md` (`record-group-memory`, creating the file when absent), tears down eligible stage worktrees, and removes what no reader needs after the run (`prune-run-artifacts`: every `node_modules` and `.next` directory under the run directory, and the dispatch snapshots and publication locks of a passed run or of an earlier run superseded by one). Contract v2 retains its historical in-place projection sequence as a read-only compatibility path. A failed step still runs every later check through `validate-run`; `record-group-memory` and `teardown-stages` are skipped so a failed run neither hands an unvalidated conclusion to sibling tasks nor reclaims worktrees; `prune-run-artifacts` still runs, because the lockfiles, logs and experiment directories it leaves are enough to reinstall and it leaves the dispatch snapshots of a failed run that no later run has passed. The result carries `nextInGroup` (the first task in start order not yet started) and, for a terminal pointer, `nextCommand` closes on starting it from its brief. Reports each step and prints the ordered `--only` recovery tail from the earliest failure. Repairable failures return `recovery.mode=same-run`, complete assembly owner issues, and `resumeCommand` using this manifest; `nextCommand` does not ask for a new run. A validator-only failure targeting an earlier phase retains that recovery target. Finalization step failures and run-bound contract exceptions from `plan-items` and `agent-prompt` write bounded runtime error records, with any logging failure reported separately. Without `--only` it first records the lead's `phase-7-persist` checkpoint, ahead of `validate-run`, and returns it as `progressLines`. This is the shared path for every lead adapter. |
|
|
979
|
-
| `okstra render-views <final-report.data.json\|final-report.md>` | The Phase 7 `render-views` step, runnable on its own. Schema v2 data is rendered directly, and schema v3 data uses the same always-generated, task-specific human HTML path. The full reading copy uses `templates/reports/final-report-v2.template.md` and is rendered on demand with `okstra render-final-report`. Passing the Markdown sibling locates the same data.json. Schema v1 and quick reports keep the legacy conditional renderer. The Node wrapper calls `scripts/okstra-render-report-views.py`; `validators/validate-report-views.py` verifies source/schema/template digests, required human fields, form controls, external assets, diagram/table ID parity, Response ID parity, and that every in-page `href="#…"` lands on an element of the page. For a non-English report the command prints two counts: `translated N string(s) into <lang> (M left in English, K unresolved)` from the sidecar overlay, and `rendered R line(s) still in English on the <lang> page` from the written page itself — the second sees fields the extractor does not offer, so `M = 0` with `R > 0` means a reader-facing key is missing from `PROSE_KEYS`. |
|
|
980
|
-
| `okstra design-prep <list\|show\|write>` | Review AI-prepared implementation design requests, inspect their effective confirmed response, or append a confirmed user/wizard response without editing the planning report |
|
|
981
|
-
| `okstra wizard <init\|step\|render-args\|confirmation\|outcome> --state-file <path>` | Interactive input state machine for okstra-run, implemented by `okstra_ctl.wizard`. Seed a state file with `init`, then repeatedly call `step --answer <val>` to receive the next `Prompt` JSON. `--answer` is **required**; use `--no-submit` to peek at the next prompt without submitting a response. A `pick` with more choices than the host picker can display keeps `kind: "pick"` but adds `presentation: "numbered-text"`; render every option as a numbered Markdown list and submit the user's 1-based number, exact value, or exact label. Invalid, out-of-range, and ambiguous answers re-prompt without dropping choices. `render-args` returns the final `render-bundle` argument map, and `confirmation` returns the user echo block. On a completed wizard, `outcome` returns `renderArgs`, `persistActions`, and `confirmationText` together; project/global release-handoff PR-template persistence appears as `persistActions[].command == "config.set"`. For an `implementation` task type, `stage_pick` follows `approved_plan_pick` and selects the stage before `executor_pick`. The brief step appears only for entry task types—requirements-discovery, error-analysis, improvement-discovery, project-analysis, feature-analysis, and change-impact-analysis. Analysis inputs use `feature_evidence_pick` / `feature_evidence`, `project_evidence_pick` / `project_evidence`, and `analysis_target_pick` / `analysis_target`; a revision-requested report prioritizes its same-task, same-type rerun. Downstream lifecycle phases automatically carry the manifest brief, with a three-option `brief_carry` fallback when none is registered; `release-handoff` has no brief and enters multi-select `handoff_stage_pick` for eligible stage groups or the whole task |
|
|
982
|
-
| `okstra token-usage ...` | Wrap the installed `okstra-token-usage.py` to collect and substitute run token usage. Session JSONL is incrementally scanned by default through a byte-cursor cache at `$OKSTRA_HOME/cache/token-usage/`; `--no-cache` bypasses the cache and forces a full rescan as an accuracy fallback |
|
|
983
|
-
|
|
984
|
-
In prose, `okstra agent-prompt materialize|verify|record-dispatch|link-result|materialize-result|complete|verify-completion` denotes that internal command family; the vertical bars separate subcommands and are not literal shell arguments. `check-corrections` and `apply-corrections` belong to the same family and are described in the table row above.
|
|
985
|
-
|
|
986
|
-
The convergence state lifecycle is `groups v1.0 → work v1.0 → final v1.3`; round-plan, round-results, and optional critic-results v1.0 artifacts provide the auditable transitions between those endpoints.
|
|
987
|
-
|
|
988
|
-
`okstra convergence apply-critic-gaps` is the only transition that may add verified coverage gaps to terminal main-queue state. `okstra plan-items extract` creates the complete plan queue, and `okstra plan-items validate` rejects any omission or drift before verifier dispatch.
|
|
989
|
-
|
|
990
|
-
`okstra convergence` and `okstra plan-items` are internal admin CLI families used by the lead protocol. Each is an internal admin CLI, not a user-facing skill, and their presence does not add a public skill. The former `okstra-convergence` skill remains obsolete; the installed `prompts/lead/convergence.md` and `scripts/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md` contracts tell the lead when to invoke these operations.
|
|
991
|
-
|
|
992
|
-
> Every subcommand is wired to `PYTHONPATH` and `~/.okstra/lib/python` by the Python helper (`src/lib/python-helper.mts`) spawned by `bin/okstra`. When invoking `python3 -m okstra_ctl.*` directly, you must configure `PYTHONPATH` yourself.
|
|
993
|
-
|
|
994
|
-
#### `okstra design-prep`
|
|
995
|
-
|
|
996
|
-
Use these commands after an `implementation-planning` report has prepared concrete domain, schema, interface, lifecycle, rollout, or manual-test input. `show` and `write` accept the Markdown report path or its `.data.json` sibling.
|
|
997
|
-
|
|
998
|
-
```bash
|
|
999
|
-
okstra design-prep list [--project-root <path>] [--report <path>]
|
|
1000
|
-
okstra design-prep show --report <path> [--item PREP-001]
|
|
1001
|
-
okstra design-prep write --report <path> --item PREP-001 \
|
|
1002
|
-
--decision <accept-draft|modify-draft|reject-draft|defer> \
|
|
1003
|
-
[--overrides '<json-object>'] [--notes <text>] --confirmed
|
|
1004
|
-
```
|
|
1005
|
-
|
|
1006
|
-
- `list` returns `{"reports": [<snapshot-summary>, ...]}`. With `--report`, it reads only that report; otherwise it discovers planning reports below the resolved project root.
|
|
1007
|
-
- `show` without `--item` returns `report`, `outcome`, `reason`, `warnings`, and all item views. With `--item`, it returns `report`, the full AI-prepared `item`, `effectiveInput`, `assessmentFingerprint`, and `requestPath`.
|
|
1008
|
-
- `write` returns `path`, `revision`, `inputId`, and `assessmentFingerprint`. The path is a new `design-prep-inputs/...-r<revision>-<uuid>.md` sidecar; it never mutates the report or an earlier response.
|
|
1009
|
-
- `--overrides` must be a JSON object and is accepted only with `modify-draft`. `reject-draft` requires a non-empty note.
|
|
1010
|
-
- `--confirmed` is required for every write. Without it, no revision, UUID, timestamp, or file is allocated.
|
|
1011
|
-
|
|
1012
|
-
Successful commands and `--help` exit `0`. Contract, path, JSON, or confirmation errors exit `1` and write a `design-prep:` message to stderr. Argument-parser errors such as a missing required flag or unknown decision exit `2`. Successful command stdout is JSON.
|
|
1013
|
-
|
|
1014
|
-
The selected implementation stage resolves only items that cite it in `stageRefs`:
|
|
1015
|
-
|
|
1016
|
-
| Effective state or response | Preflight result |
|
|
1017
|
-
|---|---|
|
|
1018
|
-
| `ready`, `not-applicable`, or `no-design-inputs` | `proceed` |
|
|
1019
|
-
| `provisional` with no response, `defer`, `accept-draft`, or a non-triggering `modify-draft` | `proceed`; inject the effective proposal and working assumption into the executor prompt |
|
|
1020
|
-
| `provisional` with `reject-draft` | `wait_for_input` |
|
|
1021
|
-
| `provisional` with a modified `replanTriggerFields` path | `replan` |
|
|
1022
|
-
| `blocked` with no response, `defer`, or `reject-draft` | `wait_for_input` |
|
|
1023
|
-
| `blocked` with `accept-draft` or `modify-draft` | `replan`, because the approved plan must incorporate the newly authorized decision |
|
|
1024
|
-
| markerless legacy plan | `proceed` with `legacy-unassessed` warning; no report rewrite |
|
|
1025
|
-
|
|
1026
|
-
Both `wait_for_input` and `replan` stop before a stage worktree is provisioned and before a `status:"started"` consumer row is appended. Other stages whose `stageRefs` do not include the unresolved item remain eligible.
|
|
1027
|
-
|
|
1028
|
-
### Live-log sidecar
|
|
1029
|
-
|
|
1030
|
-
For every dispatch, whichever provider runs it, okstra creates a `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` sidecar and writes the CLI's output into it. All five `okstra-<provider>-exec.sh` entrypoints share one implementation for this, so the log contract does not vary by provider.
|
|
1031
|
-
|
|
1032
|
-
**Progress appears in the worker's own pane.** Earlier versions split a sibling `tail -F` trace pane next to each worker; they no longer do, and no trace pane is created at all. Instead the presentation is passed to the entrypoint as `--presentation live|quiet`, and only a backend that opened a pane asks for `live` — the default, and what a `cli-wrapper` subagent dispatch passes, is `quiet`. Under `live` each event becomes one readable row on the worker's own streams — `→ Bash: npm run check`, then ` ← ok (2481 bytes)`, and `!! PERMISSION DENIED — <tool>: <reason>` for a refusal. Under `quiet` progress is withheld and only the worker's closing text is printed, which is what a dispatch on a machine with no pane surface needs. The `.log` sidecar records the progress either way, so withholding it from the screen loses nothing.
|
|
1033
|
-
|
|
1034
|
-
Every pane tag this script once scanned has lost its writer, and the script itself is gone. `@okstra_trace_run` / `@okstra_status` went inert when the wrappers stopped splitting a trace pane; `@okstra_worker_run` went with the pane-tagging dispatch backend; and `okstra-trace-cleanup.sh` followed, because its title scan never matched a cmux surface and current runs are cmux (`terminalBackend: cmux-pane`). What okstra closes now are the panes it opened itself and recorded as `paneId` in `team-state.workerDispatches[]`. `okstra team reclaim` is the round boundary: it closes the panes of dispatches that have finished, leaves an in-progress one alone, records `phase-batch-cleanup panes=<n>` with the number it closed (`--gate` prints `phase-gate-cleanup` before a user gate and records nothing), and with `--dry-run` prints the same set without closing. `okstra team teardown` is the end of the run: every recorded pane, plus a write-off for any dispatch that never finished. A pane the harness opened for its own teammate is out of scope for both — okstra never opened it and holds no id for it. An `okstra-compact-reminder.sh` `SessionStart` hook (matcher `compact`) re-injects the boundary obligation after a `/compact`.
|
|
1035
|
-
|
|
1036
|
-
## Business flow explanations
|
|
1037
|
-
|
|
1038
|
-
`okstra explain-flow --question "How does order cancellation work?"` starts a standalone investigation without requiring a task or brief. The equivalent explicit form is `okstra explain-flow explain --question "How does order cancellation work?"`.
|
|
1039
|
-
|
|
1040
|
-
Common options are `--project-root <directory>`, `--json`, `--report-language <language tag>` and `--host-runtime <host id>`. The default report language uses the existing project/global language resolver. `--source-root <checkout>` selects the source checkout while keeping the original project as artifact owner. Repeat `--source-artifact <path>` to supply existing verification records. The investigation itself does not run verification commands.
|
|
1041
|
-
|
|
1042
|
-
For before/after comparison, run `okstra explain-flow explain --question "Order cancellation" --mode pre`, retain the returned execution id, and later use `--mode post --baseline <execution id>`. `--task-key <key>` associates a standalone explanation with a task's provenance; automatic task hooks maintain task links separately.
|
|
1043
|
-
|
|
1044
|
-
`okstra explain-flow knowledge --query "cancellation retry"` selects matching and connected stored facts across registered projects, preserving owner, producer, evidence level, source freshness and conflict status. `okstra explain-flow status --execution <id>` reads an existing execution. `okstra explain-flow rerun --execution <id>` creates a new investigation from the saved request and retains earlier artifacts.
|
|
1045
|
-
|
|
1046
|
-
`complete` means the accepted investigation has no recorded gap. `partial` retains useful findings with inaccessible candidates, missing baselines or unresolved conflicts. `failed` includes the reason and an explanation-only retry command and exits with status 1. Optional task hooks keep these statuses separate from task success and next-phase routing.
|
|
1047
|
-
|
|
1048
|
-
The standalone preparation API is shared with `okstra agent-prompt materialize`; its `--execution-runner cli-wrapper` option explicitly selects process execution for standalone callers that execute the prompt themselves.
|
|
1049
|
-
|
|
1050
|
-
After a task checkout has been removed, retry against an available checkout with `okstra explain-flow rerun --execution <id> --source-root <path>`. The original request and captured baseline remain unchanged; the retry creates a new execution and task-history entry.
|
|
1051
|
-
|
|
1052
|
-
## Reusable verification procedures
|
|
1053
|
-
|
|
1054
|
-
`okstra qa show --project-root <project>` lists QA declarations, procedure references, entry digests, and related-source freshness as fixed text. `okstra qa check --project-root <project>` also exits 1 when related sources differ from their registered baseline. Invalid declarations, missing files, traversal, and symlinks exit 2. When a referenced file is missing, `show` still prints the declaration and its update digest before returning the error. Neither command executes the application or treats structural validity as functional verification. Without execution evidence, the output says `not-queried`.
|
|
1055
|
-
|
|
1056
|
-
Register an existing procedure with `okstra qa register --project-root <project> --id <id> --category test --label <label> --cmd <command> --procedure-input <file> --source-path <relative-file>`. Repeat `--source-path` for related sources and `--resource-key` for non-secret shared-resource identifiers. `--category` accepts `test` or `db-test`. The command is the executable authority; examples in the procedure are not executed.
|
|
1057
|
-
|
|
1058
|
-
Code-fenced examples do not count as procedure sections. Procedures contain the Markdown headings `Execution`, `Environment`, `User actions`, `Success observations`, and `Cleanup` at level two. Existing project documents are referenced without rewriting them. An input outside the project is copied into `.okstra/verification/procedures/<id>/<content-digest>.md`. Source files and repository procedures are read from `--source-root <checkout>` when supplied; otherwise the original project is explicitly reported as the source. Procedures under `.okstra` belong to the original project.
|
|
1059
|
-
|
|
1060
|
-
Updating an existing id requires `--expected-entry-digest <digest>` from `show`. Registration serializes concurrent QA registrations and project auto-registration, preserves unrelated project fields, and atomically publishes the config only after validating the procedure. Existing entries without ids and repeated labels remain supported. A successful registration is not evidence that the feature works.
|