okstra 0.226.0 → 0.228.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 +2 -1
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/wizard.mjs +12 -15
- package/dist/commands/execute/wizard.mjs.map +1 -1
- package/docs/architecture/storage-model.md +77 -0
- package/docs/cli.md +43 -7
- package/docs/project-structure-overview.md +13 -3
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/code-review.json +1 -1
- package/runtime/prompts/duties/code-reviewer.json +1 -0
- package/runtime/prompts/lead/convergence.md +5 -19
- package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
- package/runtime/prompts/wizard/prompts.ko.json +44 -0
- package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
- package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
- package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
- package/runtime/python/okstra_ctl/brief_sources.py +162 -44
- package/runtime/python/okstra_ctl/code_review_coverage.py +81 -19
- package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
- package/runtime/python/okstra_ctl/code_review_target.py +115 -55
- package/runtime/python/okstra_ctl/conformance.py +9 -3
- package/runtime/python/okstra_ctl/correction_cli.py +6 -5
- package/runtime/python/okstra_ctl/correction_round.py +1 -1
- package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
- package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
- package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
- package/runtime/python/okstra_ctl/fixed_text.py +31 -9
- package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
- package/runtime/python/okstra_ctl/json_registry.py +3 -18
- package/runtime/python/okstra_ctl/manager_split.py +201 -84
- package/runtime/python/okstra_ctl/model_io/references.py +31 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
- package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
- package/runtime/python/okstra_ctl/path_hints.py +13 -1
- package/runtime/python/okstra_ctl/paths.py +4 -0
- package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +4 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +5 -3
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/plan_items.py +9 -11
- package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
- package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
- package/runtime/python/okstra_ctl/prior_planning.py +6 -17
- package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
- package/runtime/python/okstra_ctl/qa_commands.py +66 -1
- package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
- package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
- package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
- package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
- package/runtime/python/okstra_ctl/render.py +10 -0
- package/runtime/python/okstra_ctl/report_assembly.py +12 -12
- package/runtime/python/okstra_ctl/run.py +123 -6
- package/runtime/python/okstra_ctl/stage_done.py +5 -4
- package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
- package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
- package/runtime/python/okstra_ctl/verification_plan.py +116 -0
- package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
- package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
- package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
- package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
- package/runtime/python/okstra_ctl/wizard/render.py +2 -2
- package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
- package/runtime/python/okstra_ctl/wizard/state.py +55 -14
- package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
- package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
- package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
- package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
- package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
- package/runtime/python/okstra_ctl/write_policy.py +33 -18
- package/runtime/python/okstra_project/dirs.py +22 -0
- package/runtime/python/okstra_project/resolver.py +10 -0
- package/runtime/schemas/final-report-v3.0.schema.json +5 -1
- package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
- package/runtime/skills/okstra-code-review/SKILL.md +59 -63
- package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
- package/runtime/skills/okstra-code-review/references/review-calibration.md +32 -9
- package/runtime/skills/okstra-manager/SKILL.md +2 -2
- package/runtime/skills/okstra-run/SKILL.md +21 -1
- package/runtime/skills/okstra-setup/SKILL.md +2 -0
- package/runtime/skills/okstra-setup/references/project-config.md +2 -0
- package/runtime/validators/validate-brief.py +21 -5
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: okstra-run
|
|
3
|
-
description: Use when the user wants to start or continue an okstra cross-verification task
|
|
3
|
+
description: Use when the user wants to start or continue an okstra cross-verification task in this session, or configure its saved worker roles, models, and counts. Includes "okstra run", "run the next phase", and "okstra-run worker settings".
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# OKSTRA Run (in-session)
|
|
@@ -17,6 +17,25 @@ Launch an okstra task — gather inputs interactively via the **wizard state mac
|
|
|
17
17
|
|
|
18
18
|
- The user is inside a supported agent host and asks to start an okstra task ("run okstra here", "start an error-analysis on this branch", "okstra implementation-planning for INV-1234").
|
|
19
19
|
- Continue an existing task (next phase) without leaving the current agent session.
|
|
20
|
+
- Configure global worker defaults or project overrides without starting a task.
|
|
21
|
+
|
|
22
|
+
## Worker settings mode
|
|
23
|
+
|
|
24
|
+
When the user asks to configure saved worker roles, models, or counts, enter settings mode before the task-launch preflight. The wizard owns the scope, role editor, review, save, and cancel flow. Use `okstra wizard` rather than editing the configuration files directly.
|
|
25
|
+
|
|
26
|
+
Use the host identity and live semantic-function declaration from Step 1. Settings do not start a lead or require a configured project. To discover the current project's registration, use `okstra config show --scope project --cwd <absolute-current-directory>`; when its project entry is unavailable, omit both project flags below. Do not start `/okstra-setup` for a global settings request.
|
|
27
|
+
|
|
28
|
+
Get a state path with `okstra wizard new-state-file`, then initialize with literal values:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
okstra wizard init --worker-settings --state-file /absolute/state.json --host-runtime <host-runtime> --available-function plain_text_input
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
For a registered project, also pass its `--project-root` and `--project-id`. The response includes the absolute `relayContract` path and `runtime`. Read that contract and compute the allowed live-function intersection using Step 1's relay rules. If the intersection includes additional functions, initialize the same still-unanswered settings state once more with those `--available-function` flags. Settings initialization does not write configuration.
|
|
35
|
+
|
|
36
|
+
Relay `next` through the existing prompt loop and submit with `okstra wizard step --state-file <literal-path> --answer <literal-answer>`. The wizard shows all role summaries together and lets the user edit only the roles they choose. Project inheritance, explicit zero workers, and save validation belong to the wizard. Changes remain drafts until the user chooses Save on its review screen.
|
|
37
|
+
|
|
38
|
+
For settings, `kind: done` means the settings transaction finished: show `next.label` and stop. `kind: aborted` means no settings were saved. Do not continue to launch Step 5, `outcome`, `render-args`, or `render-bundle` in either case. Resume ordinary task launching only on a separate user request.
|
|
20
39
|
|
|
21
40
|
## When NOT to Use
|
|
22
41
|
|
|
@@ -208,6 +227,7 @@ Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How
|
|
|
208
227
|
That is the entire interactive flow. The wizard handles:
|
|
209
228
|
|
|
210
229
|
- project report language before task selection: when `.okstra/project.json` has no `reportLanguage` value, ask for a language tag and save the answer to that file. An existing value skips this question. Prompt rendering and progress estimation do not save a language,
|
|
230
|
+
- saved worker rosters: `workerDefaults` in the project configuration replaces that role's global array in `~/.okstra/config.json`. The array fixes both models and count; an empty array explicitly disables an optional role. Valid configured roles skip their selection screens without a separate defaults question. Missing or unavailable roles alone are asked. The confirmation shows the count, models, source, and disabled roles; Edit changes only this run. Explicit inputs and an explicitly reused previous roster take precedence. `modelDefaults` remains a candidate-order preference and does not skip screens. Dynamic verifiers retain their source assignments,
|
|
211
231
|
- new-vs-existing task split (remaining work — `workStatus != done` — top-3 newest recommendations + Enter directly), task-group / task-id slug validation (task-group offers the top-3 newest candidates combining recent task use + recent `.okstra/briefs/<group>/` creation activity + Enter directly; task-id offers the top-3 recent candidates from the same group + Enter directly),
|
|
212
232
|
- task-type pick (3 options + Enter directly; Enter directly is validated against the full task-type whitelist in a follow-up `text` step). **For a brand-new task the brief is asked first** and the three options are entry phases only (`requirements-discovery` / `improvement-discovery` / `project-analysis` / `feature-analysis` / `change-impact-analysis` / `error-analysis`) — a new task-key has no approved plan, no implementation and no commits, so `implementation`, `final-verification` and `release-handoff` cannot be entered there; the recommended slot comes from the selected brief's `Recommended next phase:` line and falls back to `requirements-discovery` when the brief carries none. For an existing task-key what fills those three depends on `workflow.nextRecommendedPhase` — an object `{phase, status, rationale}`, not a phase-name string. `status: ready` gives the classic trio: its `phase` marked recommended, re-run the current phase, the lifecycle's next step. Any other status contributes nothing at all, since both the recommended slot and the next-step slot derive from that phase — re-run the current phase becomes the first option and the remaining slots fill unlabelled from recently used task-types and then the whitelist. Never recover a phase name from a non-`ready` pointer and propose it yourself: prepare deliberately lowers the pointer to `pending` while its run is unfinished, and the missing recommendation is that signal,
|
|
213
233
|
- brief path — **for a new task it is asked right after task-group, before the task-type** (it is the only input that says what the task is, and the task-type recommendation reads it); for an existing task it is **asked only for entry task-types (requirements-discovery / error-analysis / improvement-discovery / project-analysis / feature-analysis / change-impact-analysis)** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, sorted by the newer of file-created/modified time and latest task-catalog use; direct input last; `Keep / Change` for existing entry tasks). `project-analysis`, `feature-analysis`, and `change-impact-analysis` are brief entry task types. On an existing task a downstream lifecycle task-type auto carries in the manifest's brief, and when no registered brief exists a `brief_carry` 3-option prompt appears (recommend switching to entry / Enter directly / Abort). `release-handoff` has no brief step of its own — a new-task run answers the brief before the type is known, and the brief is dropped at render time, so prepare always generates the input document that cites the verification report,
|
|
@@ -166,6 +166,8 @@ matching section:
|
|
|
166
166
|
into task worktrees.
|
|
167
167
|
- **B. project QA commands** (`qaCommands`, recommended) + **B.1 `qaEnv`** —
|
|
168
168
|
check-only lint/format/typecheck/test baselines and the Tier 3 environment.
|
|
169
|
+
The reference also describes `okstra qa register/show/check` for reusable
|
|
170
|
+
feature procedures; registration and structural checks do not execute the feature.
|
|
169
171
|
Local `io` conformance is blocking; DB/HTTP/external QA is advisory and
|
|
170
172
|
remains user-owned when automatic execution cannot PASS.
|
|
171
173
|
- **C. `.claude/settings.local.json` symlink** — automatic; read only to
|
|
@@ -90,6 +90,8 @@ The field is preserved across the runtime's auto-upserts of `project.json`, so
|
|
|
90
90
|
manual edits to `qaCommands` survive every subsequent `okstra setup` /
|
|
91
91
|
`okstra run` invocation.
|
|
92
92
|
|
|
93
|
+
For reusable feature procedures, use `okstra qa register --project-root <absolute-root> --id <id> --category test --label <label> --cmd <command> --procedure-input <file> --source-path <relative-source>`. The procedure has five level-two headings: `Execution`, `Environment`, `User actions`, `Success observations`, and `Cleanup`. Read existing project checks before authoring it. Use `okstra qa show --project-root <absolute-root>` to inspect registration and `okstra qa check --project-root <absolute-root>` to check structure and related-source freshness. These commands do not execute the feature. See the CLI manual's reusable verification procedures section for update digests, source worktrees, and resource keys.
|
|
94
|
+
|
|
93
95
|
### B.1 `qaEnv` — Tier 3 conformance environment
|
|
94
96
|
|
|
95
97
|
`implementation` / `final-verification` verifiers run **stage conformance
|
|
@@ -58,7 +58,8 @@ Checks performed per brief file:
|
|
|
58
58
|
the analysis packet. `okstra brief-sources attach` appends the missing
|
|
59
59
|
entries in place. The project root is the parent of a `--briefs-root`
|
|
60
60
|
of the form `<root>/.okstra/briefs`; for any other briefs root, or
|
|
61
|
-
outside a git checkout, the check is skipped
|
|
61
|
+
outside a git checkout, the check is skipped; a git failure inside a
|
|
62
|
+
checkout fails the brief with git's message. The codebase-scan variant
|
|
62
63
|
has no Source Material section and is not checked.
|
|
63
64
|
|
|
64
65
|
Exit code 0 on PASS, 1 on FAIL.
|
|
@@ -85,7 +86,12 @@ from okstra_ctl.phases.improvement_discovery.lenses import (
|
|
|
85
86
|
MIN_PRIORITY_LENSES,
|
|
86
87
|
)
|
|
87
88
|
from okstra_ctl.group_context import GROUP_CONTEXT_TYPE, validate_group_context
|
|
88
|
-
from okstra_ctl.brief_sources import
|
|
89
|
+
from okstra_ctl.brief_sources import (
|
|
90
|
+
TOO_LARGE_REASON,
|
|
91
|
+
GitQueryError,
|
|
92
|
+
too_large_to_cite,
|
|
93
|
+
uncited_local_documents,
|
|
94
|
+
)
|
|
89
95
|
from okstra_ctl.ids import slugify_task_segment
|
|
90
96
|
|
|
91
97
|
REQUIRED_FRONTMATTER_KEYS = {
|
|
@@ -770,12 +776,22 @@ def check_cited_local_documents(
|
|
|
770
776
|
) -> None:
|
|
771
777
|
if project_root is None or scope == "codebase":
|
|
772
778
|
return
|
|
773
|
-
|
|
774
|
-
|
|
779
|
+
try:
|
|
780
|
+
uncited = uncited_local_documents(text, project_root)
|
|
781
|
+
except GitQueryError as exc:
|
|
782
|
+
errors.append(f"local document check could not run: {exc}")
|
|
783
|
+
return
|
|
784
|
+
for relative in uncited:
|
|
785
|
+
prefix = (
|
|
775
786
|
f"local document {relative!r} is cited in the brief but has no "
|
|
776
787
|
"`### Source N — file` entry in Source Material; it is untracked, "
|
|
777
788
|
"so the task worktree lacks it and no run will show it to workers. "
|
|
778
|
-
|
|
789
|
+
)
|
|
790
|
+
if too_large_to_cite(project_root.resolve(), relative):
|
|
791
|
+
errors.append(f"{prefix}It is {TOO_LARGE_REASON}")
|
|
792
|
+
continue
|
|
793
|
+
errors.append(
|
|
794
|
+
f"{prefix}Run `okstra brief-sources attach --project-root {project_root} "
|
|
779
795
|
"--brief <this brief>` to append it by reference"
|
|
780
796
|
)
|
|
781
797
|
|