okstra 0.231.1 → 0.233.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -271
- package/dist/cli-registry.mjs +14 -1
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/render-bundle.d.mts +6 -1
- package/dist/commands/execute/render-bundle.mjs +139 -32
- package/dist/commands/execute/render-bundle.mjs.map +1 -1
- package/dist/commands/lifecycle/config.mjs +6 -74
- package/dist/commands/lifecycle/config.mjs.map +1 -1
- package/dist/commands/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.mjs.map +1 -1
- package/dist/commands/trace/capacity.d.mts +12 -0
- package/dist/commands/trace/capacity.mjs +21 -0
- package/dist/commands/trace/capacity.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +89 -0
- package/dist/commands/trace/model.mjs +251 -0
- package/dist/commands/trace/model.mjs.map +1 -0
- package/dist/commands/trace/progression.d.mts +11 -0
- package/dist/commands/trace/progression.mjs +194 -0
- package/dist/commands/trace/progression.mjs.map +1 -0
- package/dist/commands/trace/review.d.mts +7 -0
- package/dist/commands/trace/review.mjs +51 -0
- package/dist/commands/trace/review.mjs.map +1 -0
- package/dist/commands/trace/task-link.d.mts +18 -0
- package/dist/commands/trace/task-link.mjs +72 -0
- package/dist/commands/trace/task-link.mjs.map +1 -0
- package/dist/commands/trace/trace.d.mts +1 -0
- package/dist/commands/trace/trace.mjs +293 -0
- package/dist/commands/trace/trace.mjs.map +1 -0
- package/dist/lib/bounded-file.d.mts +1 -0
- package/dist/lib/bounded-file.mjs +36 -0
- package/dist/lib/bounded-file.mjs.map +1 -0
- package/dist/lib/config-store.d.mts +34 -0
- package/dist/lib/config-store.mjs +70 -0
- package/dist/lib/config-store.mjs.map +1 -0
- package/dist/lib/file-lock.mjs +4 -5
- package/dist/lib/file-lock.mjs.map +1 -1
- package/dist/lib/input-limit.d.mts +4 -0
- package/dist/lib/input-limit.mjs +8 -0
- package/dist/lib/input-limit.mjs.map +1 -0
- package/dist/lib/memory-auto-register.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +98 -0
- package/dist/lib/memory-auto-register.mjs.map +1 -0
- package/dist/lib/memory-entry-contract.d.mts +12 -0
- package/dist/lib/memory-entry-contract.mjs +46 -0
- package/dist/lib/memory-entry-contract.mjs.map +1 -0
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +3 -2
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/record-secrets.d.mts +1 -0
- package/dist/lib/record-secrets.mjs +28 -0
- package/dist/lib/record-secrets.mjs.map +1 -0
- package/dist/lib/report-language-tag.d.mts +1 -0
- package/dist/lib/report-language-tag.mjs +4 -0
- package/dist/lib/report-language-tag.mjs.map +1 -0
- package/dist/lib/report-language.d.mts +1 -0
- package/dist/lib/report-language.mjs +50 -0
- package/dist/lib/report-language.mjs.map +1 -0
- package/dist/lib/skill-catalog.mjs +3 -0
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/dist/lib/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +163 -5
- package/docs/architecture.md +17 -4
- package/docs/cli.md +511 -0
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +33 -42
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- package/runtime/agents/operations/trace-interface-review.json +6 -0
- package/runtime/agents/operations/trace-scope-review.json +6 -0
- package/runtime/agents/roles/verifier.json +2 -4
- package/runtime/bin/okstra-provider-exec.py +10 -4
- package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
- package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
- package/runtime/prompts/coding-preflight/clean-code.md +88 -286
- package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
- package/runtime/prompts/coding-preflight/languages/java.md +3 -5
- package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
- package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
- package/runtime/prompts/coding-preflight/languages/python.md +2 -7
- package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
- package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
- package/runtime/prompts/coding-preflight/overview.md +25 -38
- package/runtime/prompts/coding-preflight/review-rules.json +30 -0
- package/runtime/prompts/duties/code-reviewer.json +15 -18
- package/runtime/prompts/duties/implementation-verifier.json +1 -0
- package/runtime/prompts/duties/interface-reviewer.json +32 -0
- package/runtime/prompts/host-orchestration/README.md +18 -9
- package/runtime/prompts/launch.template.md +3 -2
- package/runtime/prompts/lead/context-loader.md +2 -0
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +6 -6
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
- package/runtime/prompts/profiles/_common-contract.md +1 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
- package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
- package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/code_review_census.py +162 -7
- package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
- package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
- package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
- package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
- package/runtime/python/okstra_ctl/code_review_run.py +384 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +49 -9
- package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
- package/runtime/python/okstra_ctl/code_review_target.py +212 -13
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/coverage_census.py +11 -2
- package/runtime/python/okstra_ctl/design_review.py +207 -0
- package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
- package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
- package/runtime/python/okstra_ctl/direct_work.py +45 -3
- package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
- package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
- package/runtime/python/okstra_ctl/doctor.py +8 -25
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
- package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
- package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
- package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
- package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +300 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
- package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
- package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
- package/runtime/python/okstra_ctl/json_boundary.py +51 -5
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +148 -1
- package/runtime/python/okstra_ctl/manager_journal.py +126 -0
- package/runtime/python/okstra_ctl/manager_launch.py +3 -3
- package/runtime/python/okstra_ctl/manager_log.py +221 -0
- package/runtime/python/okstra_ctl/manager_paths.py +8 -0
- package/runtime/python/okstra_ctl/manager_registration.py +29 -0
- package/runtime/python/okstra_ctl/manager_resume.py +59 -0
- package/runtime/python/okstra_ctl/manager_split.py +2 -2
- package/runtime/python/okstra_ctl/manager_store.py +116 -17
- package/runtime/python/okstra_ctl/manager_sync.py +45 -25
- package/runtime/python/okstra_ctl/manager_view.py +35 -2
- package/runtime/python/okstra_ctl/material.py +2 -0
- package/runtime/python/okstra_ctl/model_cli.py +64 -14
- package/runtime/python/okstra_ctl/model_defaults.py +22 -0
- package/runtime/python/okstra_ctl/model_io/renderers.py +16 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
- package/runtime/python/okstra_ctl/path_hints.py +14 -3
- package/runtime/python/okstra_ctl/paths.py +6 -1
- package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +23 -8
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -9
- package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +6 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
- package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
- package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
- package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
- package/runtime/python/okstra_ctl/render.py +28 -2
- package/runtime/python/okstra_ctl/report_assembly.py +53 -11
- package/runtime/python/okstra_ctl/report_contract.py +26 -0
- package/runtime/python/okstra_ctl/report_corrections.py +36 -20
- package/runtime/python/okstra_ctl/report_inputs.py +1 -0
- package/runtime/python/okstra_ctl/report_language.py +4 -1
- package/runtime/python/okstra_ctl/report_narrative.py +182 -7
- package/runtime/python/okstra_ctl/report_projections.py +64 -18
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
- package/runtime/python/okstra_ctl/review_policy.py +359 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
- package/runtime/python/okstra_ctl/run.py +67 -36
- package/runtime/python/okstra_ctl/run_context.py +10 -1
- package/runtime/python/okstra_ctl/set_work_status.py +4 -15
- package/runtime/python/okstra_ctl/stage_done.py +11 -0
- package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
- package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
- package/runtime/python/okstra_ctl/task_query.py +239 -0
- package/runtime/python/okstra_ctl/trace_review.py +264 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
- package/runtime/python/okstra_ctl/user_authorization.py +14 -0
- package/runtime/python/okstra_ctl/verification_generation.py +23 -1
- package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
- package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
- package/runtime/python/okstra_ctl/verification_target.py +2 -0
- package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
- package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
- package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
- package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
- package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
- package/runtime/python/okstra_ctl/wizard/render.py +8 -0
- package/runtime/python/okstra_ctl/wizard/state.py +2 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- package/runtime/python/okstra_ctl/write_policy.py +34 -1
- package/runtime/python/okstra_project/__init__.py +2 -0
- package/runtime/python/okstra_project/dirs.py +18 -0
- package/runtime/python/okstra_project/state.py +45 -20
- package/runtime/python/okstra_token_usage/blocks.py +74 -0
- package/runtime/python/okstra_token_usage/cli.py +23 -10
- package/runtime/python/okstra_token_usage/collect.py +25 -22
- package/runtime/python/okstra_token_usage/policy.py +193 -0
- package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
- package/runtime/schemas/doyouknow-v1.schema.json +65 -0
- package/runtime/schemas/final-report-v2.0.schema.json +157 -0
- package/runtime/schemas/final-report-v3.0.schema.json +157 -0
- package/runtime/schemas/memory-entry-contract-v1.json +11 -0
- package/runtime/schemas/record-secret-patterns.json +41 -0
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
- package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
- package/runtime/skills/_fragments/wizard-preflight.md +1 -1
- package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
- package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
- package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
- package/runtime/skills/okstra-code-review/SKILL.md +92 -136
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
- package/runtime/skills/okstra-discussion/SKILL.md +22 -38
- package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
- package/runtime/skills/okstra-manager/SKILL.md +31 -0
- package/runtime/skills/okstra-memory/SKILL.md +8 -1
- package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +55 -183
- package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
- package/runtime/skills/okstra-setup/SKILL.md +3 -2
- package/runtime/skills/okstra-setup/references/project-config.md +2 -4
- package/runtime/skills/okstra-tdd/SKILL.md +187 -0
- package/runtime/skills/okstra-user-response/SKILL.md +4 -2
- package/runtime/templates/implementation-worker-preamble.md +4 -9
- package/runtime/templates/manager/view.template.html +4 -0
- package/runtime/templates/report-writer-prompt-preamble.md +15 -3
- package/runtime/templates/trace/trace.template.md +42 -0
- package/runtime/templates/worker-prompt-preamble.md +4 -12
- package/runtime/validators/checks/fixtures-02.py +25 -33
- package/runtime/validators/validate-run.py +107 -38
|
@@ -62,7 +62,7 @@ Submit the answer shape required by `interaction.answerProtocol`; do not add nor
|
|
|
62
62
|
|
|
63
63
|
The final `confirm` step is a normal `pick` step with three options — `Proceed` / `Edit` / `Abort`(abort) — and is rendered the same way (no special handling). `Edit` rewinds to any earlier step (including `base-ref`); `Abort` terminally cancels the wizard. The branch/worktree decision the run will actually use (for `implementation`, the **stage worktree** — not the task-key directory) is folded into the Step 4 confirmation summary block as a `worktree` line, so there is no separate branch-confirm prompt.
|
|
64
64
|
|
|
65
|
-
Never invent additional questions.
|
|
65
|
+
Never invent additional questions. Relay every `pick` / `pick_group` option the wizard sends, in order, including the flagged recommendation: the wizard's arrays are the complete choice set whatever the host UI's usual option limit, and the run-prompt recommendation rule (1–2 recommendations + Enter directly) applies only to prompts this skill authors itself. It does not excuse you from recommending: before relaying a wizard step whose answer turns on something readable (the carried report, the sidecar the user already wrote, the prior Stage Map), read it, put what you found in the question body, and name which of the wizard's own options you recommend and why. Relaying a step with no context and no recommendation hands the whole question back to the user — see the lifecycle core contract "Asking the user (BLOCKING)".
|
|
66
66
|
|
|
67
67
|
**One recommendation, shown in one place, and it is option 1.** Wizard labels carry no recommendation marker of their own. The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — except on model-selection steps (`role-models:*`, `role-model:*`), which keep provider display order, so the flagged model may sit anywhere in the list. Append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option, whose recommendation is not placed first on a single-select step or is not the leading run on a checkbox step (both position checks are skipped on `role-models:*` / `role-model:*` steps), or that marks the free-input / abort escape as a recommendation.
|
|
68
68
|
<!-- END FRAGMENT: wizard-relay-protocol -->
|
|
@@ -82,7 +82,7 @@ Run one shell-command tool call (Shell invocation rule from the top of this file
|
|
|
82
82
|
okstra preflight --runtime <host-runtime>
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
-
Read the fixed text lines. If the first line is `Okstra preflight: failed`, show `Runtime readiness` and every repeated `Readiness check`, `Readiness check status`, and `Readiness check action`, then stop before Step 2. Show `Reason` and `Recovery` for every failure. Do not relabel a host login, license, daemon, trust, or other readiness failure as missing Okstra setup. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary). Do **not** try to invoke `npx -y okstra@latest ...` as a fallback —
|
|
85
|
+
Read the fixed text lines. If the first line is `Okstra preflight: failed`, show `Runtime readiness` and every repeated `Readiness check`, `Readiness check status`, and `Readiness check action`, then stop before Step 2. Show `Reason` and `Recovery` for every failure. Do not relabel a host login, license, daemon, trust, or other readiness failure as missing Okstra setup. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary). Do **not** try to invoke `npx -y okstra@latest ...` as a fallback — every later wizard call still invokes the stale `okstra` on PATH, so an `npx` call does not recover the run. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so never `export PYTHONPATH=...`.
|
|
86
86
|
|
|
87
87
|
On `Okstra preflight: ready`, require `Runtime readiness: ready` before Step 2. These checks come from the selected host adapter and are independent of worker-provider choices. Any other readiness value is unrecognized runtime output: show it and stop before Step 2 instead of guessing that the host is ready.
|
|
88
88
|
|
|
@@ -145,7 +145,7 @@ Use this built-in mapping only when the successful preflight response omitted `r
|
|
|
145
145
|
For numbered interactions, render every option as a 1-based Markdown item containing its label followed by its description verbatim, in original order. For `sequential-group`, ask every question in order and build one compact JSON object keyed by `questions[].step`. Submit each user message unchanged; the wizard owns numbered and grouped normalization.
|
|
146
146
|
<!-- END FRAGMENT: wizard-preflight -->
|
|
147
147
|
|
|
148
|
-
The supported lead hosts are a `claude-code` lead, or any lead under cmux.
|
|
148
|
+
The supported lead hosts are a `claude-code` lead, or any lead under cmux. With any other lead, stop before Step 2 and say so instead of moving the user to another session. **Not enforced:** `render-bundle` always passes `--render-only`, which skips prepare's lead-runtime check.
|
|
149
149
|
|
|
150
150
|
## Step 2: Initialize the wizard for a discussion
|
|
151
151
|
|
|
@@ -184,15 +184,13 @@ Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How
|
|
|
184
184
|
```
|
|
185
185
|
If the answer contains spaces or shell metacharacters, wrap it in double quotes around the literal string only — never inside `"$VAR"`.
|
|
186
186
|
|
|
187
|
-
|
|
187
|
+
Pass `--answer` even when the user's reply is empty:
|
|
188
188
|
```bash
|
|
189
189
|
okstra wizard step --state-file /var/folders/.../okstra-wizard.AbCd.json --answer ""
|
|
190
190
|
```
|
|
191
|
-
|
|
191
|
+
Without `--answer` or `--no-submit`, `wizard step` returns `ok: false` naming `--answer`, exits 2 and submits nothing, so `--answer ""` is the only way past an intentionally blank step (e.g. "use phase default"). If the literal answer contains `"`, escape each occurrence as `\"` inside the double-quoted argument.
|
|
192
192
|
|
|
193
|
-
**
|
|
194
|
-
|
|
195
|
-
**Enforced:** `tests-js/wizard.test.mjs` pins `parseFlags` on the empty literal (`--answer=` parses to the empty string, a value beginning with `--` is kept) and on the `--no-submit` peek that is the only sanctioned way to see the current prompt without submitting; the Node wrapper (`src/commands/execute/wizard.mts`) is what forwards them to Python.
|
|
193
|
+
**Not enforced:** no test pins the empty-literal parsing or the `--no-submit` peek; the Node wrapper (`src/commands/execute/wizard.mts`) forwards both flags to Python.
|
|
196
194
|
3. **Handle result**:
|
|
197
195
|
- `ok: true` → echo `result.echo` to the user on one short line, then loop with `result.next`.
|
|
198
196
|
- `ok: false` → show `result.error` to the user verbatim, then loop with `result.current` (re-prompt the same step). If `result.current` is `null`, do not loop — the current step cannot render (e.g. corrupt Stage Map); surface the error and stop so the user fixes the plan.
|
|
@@ -203,7 +201,7 @@ The discussion steps the wizard asks, in order: task selection (or task-group an
|
|
|
203
201
|
<!-- BEGIN FRAGMENT: wizard-confirm-step -->
|
|
204
202
|
## Step 4: The confirm step's question text is the selection summary
|
|
205
203
|
|
|
206
|
-
When `next.step == "confirm"`, the prompt's `label` already carries the full selection summary (`선택 확인:` followed by one line per resolved input — task-type, task-key, brief, base-ref, worktree, every role slot, directive, related-tasks, clarification, stage, …) and ends with the question. Render that `label` **verbatim, every line, as the question text** of the `confirm` picker (Proceed / Edit / Abort) — the same way you render any other pick step's label. Do not re-author it as a table, do not summarise it into prose, do not drop a line because its value is `(none)`: the user confirms what is on screen, and a line you left out is a setting they never saw
|
|
204
|
+
When `next.step == "confirm"`, the prompt's `label` already carries the full selection summary (`선택 확인:` followed by one line per resolved input — task-type, task-key, brief, base-ref, worktree, every role slot, directive, related-tasks, clarification, stage, …) and ends with the question. Render that `label` **verbatim, every line, as the question text** of the `confirm` picker (Proceed / Edit / Abort) — the same way you render any other pick step's label. Do not re-author it as a table, do not summarise it into prose, do not drop a line because its value is `(none)`: the user confirms what is on screen, and a line you left out is a setting they never saw. Render the picker **as the final output of that turn** — emit nothing after the picker call.
|
|
207
205
|
|
|
208
206
|
`okstra wizard confirmation --state-file <path>` returns the same block as `{ok: true, text: ...}` for a text-only host or when the user asks to see the summary again; it is not a substitute for the label.
|
|
209
207
|
|
|
@@ -219,51 +217,35 @@ When `next.kind == "done"`, fetch the public wizard outcome:
|
|
|
219
217
|
okstra wizard outcome --state-file /var/folders/.../okstra-wizard.AbCd.json
|
|
220
218
|
```
|
|
221
219
|
|
|
222
|
-
Output: `{ok: true, outcome: {renderArgv: ["--lead-runtime", "...", ...], renderArgs: {...}, orchestration: {chainStages: "..."}, persistActions: [...], confirmationText: "..."}}`.
|
|
223
|
-
|
|
224
|
-
`renderArgv` is the canonical ordered `okstra render-bundle` argument list. Pass its tokens verbatim and in order. Repeated `--role-count` and `--role-model` flags are intentional. `renderArgs` is a compatibility and inspection view only; do not reconstruct an invocation from it. `orchestration` holds signals this skill acts on itself — never pass its entries to `render-bundle`.
|
|
225
|
-
|
|
226
|
-
`userAuthorization`, when present, preserves the confirmation prompt actually emitted by this wizard and the relayed `proceed` response. Its `--user-authorization-json` token carries that record into the run manifest; preserve it unchanged. Do not synthesize a receipt for older confirmed states. The record documents task scope; it does not grant host execution privileges.
|
|
220
|
+
Output: `{ok: true, outcome: {renderArgv: ["--lead-runtime", "...", ...], renderArgs: {...}, orchestration: {chainStages: "...", hostRulesPath: "..."}, persistActions: [...], confirmationText: "..."}}`.
|
|
227
221
|
|
|
228
|
-
|
|
222
|
+
Use the outcome to inspect the confirmed scope and `orchestration.chainStages`. `renderArgv` and `renderArgs` remain compatibility and inspection views; do not copy their tokens into a command. Bundle preparation reads the confirmed state file directly and preserves empty values and repeated role/model flags in code. `orchestration` holds signals this skill acts on itself — never pass its entries to `render-bundle`.
|
|
229
223
|
|
|
230
|
-
|
|
224
|
+
Before the first `render-bundle` invocation, read `outcome.orchestration.hostRulesPath` verbatim when it is non-empty. The wizard selects and checks this absolute runtime path; it contains the selected task's waiver, recovery, and chaining rules needed even when preparation fails. An empty string means this task declares no host rules. Use the emitted path rather than constructing one from the task type.
|
|
231
225
|
|
|
232
|
-
|
|
233
|
-
{"command":"config.set","key":"pr-template-path","scope":"project|global","value":"<path>"}
|
|
234
|
-
```
|
|
226
|
+
After successful preparation, use the frozen `instruction-set/host-orchestration-rules.md` identified by the rendered launch prompt for resumed work and stage chaining. Read that frozen copy within the run as the launch prompt requires: reading the canonical file before preparation does not satisfy the implementation session read gate. An already prepared legacy run without the new outcome field keeps its existing skill and prepared-instruction contract. If a fresh outcome omits `hostRulesPath` or its non-empty path cannot be read, stop and report a runtime/skill version mismatch; do not infer waiver or recovery rules.
|
|
235
227
|
|
|
236
|
-
|
|
228
|
+
`userAuthorization`, when present, preserves the confirmation prompt actually emitted by this wizard and the relayed `proceed` response. Preparation carries that record into the run manifest unchanged. Do not synthesize a receipt for older confirmed states. The record documents task scope; it does not grant host execution privileges.
|
|
237
229
|
|
|
238
|
-
|
|
239
|
-
okstra config set pr-template-path "<value>" --scope project
|
|
240
|
-
okstra config set pr-template-path "<value>" --scope global
|
|
241
|
-
```
|
|
230
|
+
Before retrying a worker in an existing run, inspect its last invocation attempt: await running work; append an attempt only after `failed-no-mutation` within the retry budget. Preserve every other terminal attempt. `okstra team dispatch` routes the legacy declaration-only implementer failure to a separate same-model evidence-recovery invocation; collect its result before independent verification. Other terminal failures need `okstra agent-prompt materialize` with a new `--invocation-id`, distinct `--prompt`/`--result` paths, and unchanged assignment/model for a bounded correction. Do not restart completed implementation or request renewed approval for unchanged scope. Enforcement: `dispatch_core._next_attempt` and `execution_manifest._validate_next_attempt`.
|
|
242
231
|
|
|
243
|
-
|
|
232
|
+
`render-bundle --wizard-state-file` applies the confirmed PR-template save action before preparing the bundle. Do not execute `outcome.persistActions[]` separately. An unknown action, missing save authorization, or changed save scope stops preparation before settings are written. If an older confirmation did not record the save scope, reopen that confirmation rather than inventing a receipt. A settings write failure stops preparation; a later preparation failure reports that the successful settings write remains saved.
|
|
244
233
|
|
|
245
234
|
Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — close the panes of the dispatches that finished in the prior round so they do not accumulate: `okstra team reclaim --project-root <projectRoot> --run-manifest <RUN_MANIFEST_PATH>` closes them, records `phase-batch-cleanup panes=<n>` with the number it closed, and prints that `PROGRESS:` line last — emit it as printed and do not call `okstra lead-progress append` for it. The command reads each dispatch's recorded status, so an in-progress worker keeps its pane whichever moment you call it. It closes only the panes okstra opened and recorded — a pane the harness opened for its own teammate carries no recorded id and is not okstra's to close. After collecting results and token usage, apply the selected adapter's `shutdown_workers` operation only to confirmed-complete workers; preserve in-flight workers and the lead. A `cli-wrapper` run holds no pane at all and `team reclaim` refuses it, so record the checkpoint there with `okstra lead-progress append … --phase phase-batch-cleanup --field panes=0`.
|
|
246
235
|
|
|
247
236
|
Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run `okstra team reclaim … --gate` first: it closes the finished panes and prints `PROGRESS: phase-gate-cleanup panes=<n>` for you to emit, without recording a batch cleanup. Then apply the selected adapter's `shutdown_workers` operation to confirmed-complete workers after collecting their results and token usage; preserve in-flight workers and the lead. This keeps a user gate from being shown while finished worker panes remain; in-progress dispatches keep their panes. Then follow `prompts/lead/okstra-lead-contract.md` "User confirmation before an approval blocker": read cited plan items, worker findings, and files before asking, and ask in the user's language with each option's outcome.
|
|
248
237
|
|
|
249
|
-
|
|
238
|
+
Prepare the bundle with the same literal absolute state-file path used by the wizard. Do not append scope inputs such as task type, role/model, directive, or lead runtime; the command rejects mixing those inputs with `--wizard-state-file`.
|
|
250
239
|
|
|
251
240
|
Before invoking it, follow the active host relay's execution-permission guidance. For Codex, read "Permission before bundle preparation" in the relay already selected at preflight: bundle preparation can write protected Git metadata while creating a branch and worktree, even with `--render-only`. Apply this guidance to the first invocation and each subsequent phase or stage preparation.
|
|
252
241
|
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
Step 3's empty-answer and escaping rules apply verbatim: every flag in `renderArgv` whose following value is the empty string MUST still be passed explicitly (e.g. `--related-tasks ""`, `--directive ""`) — the wizard's intent is always "flag present with empty value", even where prepare's default happens to be the same empty value.
|
|
256
|
-
|
|
257
|
-
`renderArgv` already contains exactly one `--lead-runtime <host-runtime>` pair. Do not add or replace it. Do not enumerate a fixed provider list in this skill because the wizard and role model pool own the ordered tokens.
|
|
242
|
+
The only preparation additions are `--summary-only`, a stage in the confirmed implementation chain, and the existing separately user-confirmed `--tdd-bypass` / `--qa-waiver` exceptions under their host orchestration rules. Never infer an exception grant from the original wizard confirmation.
|
|
258
243
|
|
|
259
244
|
```bash
|
|
260
|
-
okstra render-bundle --summary-only
|
|
261
|
-
<outcome.renderArgv token 1> \
|
|
262
|
-
<outcome.renderArgv token 2> \
|
|
263
|
-
<each remaining outcome.renderArgv token in order>
|
|
245
|
+
okstra render-bundle --wizard-state-file /var/folders/.../okstra-wizard.AbCd.json --summary-only
|
|
264
246
|
```
|
|
265
247
|
|
|
266
|
-
`render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, `okstra run manifest:`, and other preparation status. `--summary-only` omits the lead prompt body from stdout; Step 6 reads the verified saved prompt from the manifest path. Parse the labelled lines for `TASK_ROOT`, `INSTRUCTION_SET_PATH`, and `RUN_MANIFEST_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "Concurrent-run detection branch"
|
|
248
|
+
`render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, `okstra run manifest:`, and other preparation status. `--summary-only` omits the lead prompt body from stdout; Step 6 reads the verified saved prompt from the manifest path. Parse the labelled lines for `TASK_ROOT`, `INSTRUCTION_SET_PATH`, and `RUN_MANIFEST_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "Concurrent-run detection branch" in the selected host rules).
|
|
267
249
|
|
|
268
250
|
Before acting as the lead, read `resources.leadPromptMetadataPath` from the run
|
|
269
251
|
manifest and execute the host-native specification-link gate:
|
|
@@ -282,9 +264,11 @@ it does not claim that the host exposed or attested the delivered prompt bytes.
|
|
|
282
264
|
|
|
283
265
|
The python function underneath allocates the run sequence number and writes `run-context-*.json` under the per-task lock (`~/.okstra/.locks/<task-key>.lock`), then writes `run-inputs-*.json` + all manifests + discovery files outside that lock, and registers the run in `~/.okstra/recent.jsonl` with status `prepared` under the central `~/.okstra/.lock` (a registration failure is reported on stderr and does not fail prepare).
|
|
284
266
|
|
|
285
|
-
|
|
267
|
+
Enforcement: `wizard.launch.load_confirmed_launch` validates the confirmed snapshot and save receipt; `render-bundle.prepareRenderBundle` preserves ordered inputs and rejects scope overrides before writes. `tests/wizard/test_launch.py` and `tests-js/render-bundle.test.mjs` cover these contracts. Host execution permission remains a separate host decision.
|
|
268
|
+
|
|
269
|
+
After successful preparation of a single run, delete the literal state-file path. For an implementation chain with multiple stages, keep it until preparation of the last confirmed stage succeeds. Do not delete it after a failed preparation. Invoke `command rm` with the literal path (e.g. `command rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable. `command` keeps an interactive `rm` alias from blocking cleanup. The preparation code never deletes this file.
|
|
286
270
|
|
|
287
|
-
|
|
271
|
+
If the file disappears before a remaining stage is prepared, stop that chain and report the completed and remaining stages. Reopen the wizard for the remaining scope; do not rebuild its inputs or approval receipt from a previous run. Already prepared runs resume from their run manifest without this file. After an interrupted or uncertain preparation, inspect the task's existing runs before retrying: this command does not promise exactly-once preparation.
|
|
288
272
|
<!-- END FRAGMENT: wizard-render-bundle -->
|
|
289
273
|
|
|
290
274
|
<!-- BEGIN FRAGMENT: wizard-lead-takeover -->
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: okstra-explain-flow
|
|
3
|
-
description:
|
|
3
|
+
description: Use when the user asks how a product business flow works across related projects, or wants to query or retry a stored business explanation; no okstra task is required. Explains a product business flow across related projects, including inbound and outbound dependencies, business rules, states, errors, before/after changes, risks and side effects. Query or retry shared business explanations independently of okstra-run.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Explain a Business Flow
|
|
@@ -13,7 +13,11 @@ Run the shared runtime from the project:
|
|
|
13
13
|
okstra explain-flow --question "<the user's business question>" --report-language <reader language> --host-runtime <current host runtime>
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
<!-- BEGIN FRAGMENT: host-runtime-selection -->
|
|
17
|
+
Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present; otherwise use the registered host ID declared by the current harness. Do not infer the host from worker models, installed executables, or `PATH`. If neither source identifies the host, report that it is unknown instead of substituting another host. Keep the same resolved host when retrying against another project directory.
|
|
18
|
+
<!-- END FRAGMENT: host-runtime-selection -->
|
|
19
|
+
|
|
20
|
+
The runtime owns operation/model resolution, auditable invocation preparation, provider execution, source snapshots, validated result publication, shared knowledge and reports. Do not dispatch an unaudited replacement investigator or rerun an entire task when only an explanation failed.
|
|
17
21
|
|
|
18
22
|
For relevant stored knowledge:
|
|
19
23
|
|
|
@@ -45,15 +45,46 @@ okstra manager remove project --manager-id <manager-id> --project-id <project-id
|
|
|
45
45
|
okstra manager remove task --manager-id <manager-id> --task-group <task-group> --task-id <task-id> [--confirm]
|
|
46
46
|
okstra manager remove task-group --manager-id <manager-id> --task-group <task-group> [--confirm]
|
|
47
47
|
okstra manager view --manager-id <manager-id>
|
|
48
|
+
okstra manager journal add --manager-id <manager-id> --kind <decision|finding|followup|session-summary> --body-file <path> [--task-group <task-group> --task-id <task-id>] [--resolves <entry-id>]
|
|
49
|
+
okstra manager resume --manager-id <manager-id> [--recent <n>]
|
|
50
|
+
okstra manager log --manager-id <manager-id> [--task-group <task-group> --task-id <task-id>] [--kind <name>] [--since <ISO>] [--grep <text>] [--open-followups] [--limit <n>]
|
|
48
51
|
```
|
|
49
52
|
|
|
53
|
+
`log` is read-only. It shows the CLI-recorded manager and task events, the `task note` directives and the journal entries, newest first, as numbered entries with their origin and kind, and lists damaged log lines under `damaged`. `--open-followups` keeps only followups that no entry has resolved. `resume` is read-only and prints the last session summary, the number of entries after it (`Unsummarized activity`), open followups, recent decisions, the most recent entries and each task's sync state; a task whose files cannot be read shows its error and the rest is still printed.
|
|
54
|
+
|
|
50
55
|
- Public child task identity is `project-id:task-group:task-id`.
|
|
51
56
|
- `--task` on `new task` is optional and repeatable; without it the task is created with no children.
|
|
52
57
|
- `okstra manager new task --task ...` should prefer the full child key form above. The CLI also accepts shorthand under the command's `--task-group`, but the full key is the public form to show users.
|
|
53
58
|
- When a manager task id differs from the actual child task id for a specific project, pass `--child-task-id <child-task-id>` to `task assign` and `task run`.
|
|
54
59
|
|
|
60
|
+
## Session Start
|
|
61
|
+
|
|
62
|
+
When the user names the manager id, run `okstra manager resume --manager-id <manager-id>` before any other manager command. Tell the user the last session summary (or that there is none), the `Unsummarized activity` line when it is not `none`, and the open followups with their entry ids.
|
|
63
|
+
|
|
64
|
+
## Recording Decisions
|
|
65
|
+
|
|
66
|
+
`task note` reaches the child task: `task run` copies its directives into the child context. `journal add` is manager-only: no child task reads it. Choose by audience.
|
|
67
|
+
|
|
68
|
+
- A direction, scope or priority the user decided: `--kind decision`.
|
|
69
|
+
- A fact confirmed by investigation: `--kind finding`.
|
|
70
|
+
- Work deferred to later: `--kind followup`. When a later entry settles it, pass that followup's id with `--resolves <entry-id>`.
|
|
71
|
+
- Pass `--task-group` and `--task-id` when the entry is about one manager task.
|
|
72
|
+
|
|
73
|
+
Show the user the body before writing it. Write the body with the Write tool to a scratch path outside the project roots and pass that path as `--body-file <path>`; do not put conversation or ticket text on the command line. `--body <text>` is only for a short literal you typed yourself with no quotes, backticks or `$`. Do not repeat in the journal what a state-changing command already recorded (assignments, splits, syncs, removals): `log` shows those. A refused entry (empty, over 4,000 characters, a likely secret, an unknown task, or an invalid `--resolves`) writes nothing; fix the input instead of retrying the same text.
|
|
74
|
+
|
|
75
|
+
## Session End
|
|
76
|
+
|
|
77
|
+
When the user ends the session or a batch of work is finished, write one `--kind session-summary` entry with what was done, what was decided and what is left. The next `resume` counts activity from this entry.
|
|
78
|
+
|
|
55
79
|
## Removal Rule
|
|
56
80
|
|
|
81
|
+
Successful native state changes also register that manager's saved sources in
|
|
82
|
+
doyouknow when automatic registration is enabled. Read commands and removal dry
|
|
83
|
+
runs do not register anything. A registration warning leaves the original command
|
|
84
|
+
successful; recover with `okstra doyouknow retry --source manager` or
|
|
85
|
+
`okstra doyouknow sync --source manager`. Do not replay a state change solely to
|
|
86
|
+
repair its graph registration.
|
|
87
|
+
|
|
57
88
|
`remove project`, `remove task`, `remove task-group` and `task remove-child` change nothing without `--confirm`; they print what would be removed (`Removed: no — dry run`). Run the command without `--confirm` first, show the user the listed project, path, tasks or kept children, and rerun with `--confirm` only after the user approves that exact target. These commands touch manager files only; project `.okstra/` state and briefs written by `task split` stay.
|
|
58
89
|
|
|
59
90
|
- `task status` shows the snapshot as of `Synced at` with its `Sync age`; a child marked `changed since sync: yes` has a project task manifest written after that sync, so run `task sync` before reporting its state.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: okstra-memory
|
|
3
|
-
description: Use when the user
|
|
3
|
+
description: Use when the user asks, in any language, to save, remember, recall, search, list or archive conversation notes, decisions or preferences in okstra's global Memory Book (memory-book). Not for project task artifacts.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# okstra-memory
|
|
@@ -94,6 +94,13 @@ okstra memory add --content "<summary markdown>" --title "<short title>" --type
|
|
|
94
94
|
Use repeated `--tag` / `--project` flags when needed. Omit `--project` when no
|
|
95
95
|
project is clearly related. `--project-group` is the group chosen in Step 1.
|
|
96
96
|
|
|
97
|
+
Native `add` and `archive` also register their saved source in doyouknow when
|
|
98
|
+
automatic registration is enabled. This uses the existing entry and group;
|
|
99
|
+
do not ask for the group again for that derived registration. A registration
|
|
100
|
+
warning does not undo the saved note. Recover with `okstra doyouknow retry --source memory`
|
|
101
|
+
or `okstra doyouknow sync --source memory` instead of repeating
|
|
102
|
+
a plain `add`.
|
|
103
|
+
|
|
97
104
|
## Search / read / archive
|
|
98
105
|
|
|
99
106
|
Scope reads to the chosen project-group by default; drop `--project-group` only
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: okstra-pr-gen
|
|
3
|
-
description: Use when the user wants to register a PR body template or generate a PR description from a branch diff using a stored (or default) template. Manages templates under ~/.okstra/template/pr and drives okstra pr {template,branches,gen}.
|
|
3
|
+
description: Use when the user wants to register a PR body template or generate a PR description from a branch diff using a stored (or default) template. Manages templates under ~/.okstra/template/pr and drives okstra pr {template,branches,gen}.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# okstra-pr-gen
|