okstra 0.229.0 → 0.230.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +105 -16
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +11 -18
  12. package/package.json +1 -2
  13. package/runtime/BUILD.json +2 -2
  14. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  15. package/runtime/prompts/launch.template.md +5 -5
  16. package/runtime/prompts/lead/convergence.md +4 -4
  17. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  18. package/runtime/prompts/lead/phase-routing.md +1 -1
  19. package/runtime/prompts/lead/report-writer.md +3 -3
  20. package/runtime/prompts/lead/team-contract.md +3 -3
  21. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  22. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  23. package/runtime/python/okstra_ctl/cmux.py +4 -2
  24. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  25. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  26. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  27. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  28. package/runtime/python/okstra_ctl/conformance.py +30 -0
  29. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  30. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  31. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  32. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  33. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  34. package/runtime/python/okstra_ctl/ids.py +1 -41
  35. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  36. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  37. package/runtime/python/okstra_ctl/locks.py +28 -1
  38. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  39. package/runtime/python/okstra_ctl/paths.py +75 -33
  40. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  41. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  42. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  43. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  44. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  45. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  46. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  47. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  48. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  49. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  50. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  51. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  52. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  53. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  54. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  55. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  56. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  57. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  58. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  59. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  63. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  64. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  66. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  67. package/runtime/python/okstra_ctl/process_group.py +26 -3
  68. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  69. package/runtime/python/okstra_ctl/recap.py +1 -2
  70. package/runtime/python/okstra_ctl/render.py +10 -2
  71. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  72. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  73. package/runtime/python/okstra_ctl/run.py +24 -20
  74. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  75. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  76. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  77. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  78. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  79. package/runtime/python/okstra_ctl/verification_generation.py +22 -12
  80. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  81. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  82. package/runtime/python/okstra_ctl/verification_inputs.py +73 -2
  83. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  84. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  85. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  86. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  87. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  88. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  89. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  90. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  91. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  92. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  93. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  94. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  95. package/runtime/skills/okstra-run/SKILL.md +6 -6
  96. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  97. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  98. package/runtime/validators/validate-run.py +110 -19
  99. package/docs/cli.md +0 -1060
  100. package/docs/container.md +0 -100
  101. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  102. package/docs/performance-improvement-plan-v2.md +0 -369
  103. package/runtime/python/okstra_ctl/container.py +0 -702
  104. package/runtime/python/okstra_ctl/rollup.py +0 -241
  105. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  106. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  107. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  108. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  109. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  110. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  111. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  112. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  113. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  114. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  115. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  116. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  117. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  118. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  119. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -11,7 +11,7 @@ description: >-
11
11
  Model reviewers consolidate their teams before the orchestrator settles the
12
12
  combined findings. A coverage audit repeats missing checks on their original model and specialty slots,
13
13
  and the orchestrator verifies and settles findings. NOT for writing a PR body (okstra-pr-gen), starting a run
14
- (okstra-run), or inspecting a finished task (okstra-inspect).
14
+ (okstra-run).
15
15
  ---
16
16
 
17
17
  # OKSTRA Code Review
@@ -116,7 +116,7 @@ pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
116
116
  3. **Route the packs once, here — and fix both absolute paths the briefs carry.** `okstra paths --field home` prints the okstra home; read `<okstraHome>/prompts/coding-preflight/overview.md` and walk all three stages of its routed resource selection over the changed-file list. The result is the applied pack list — the absolute paths reviewers will read. This routing happens exactly once per run; no reviewer repeats it.
117
117
 
118
118
  The second path is this skill's own calibration file. A subagent has no "next to this file" coordinate, so the brief must spell it out: `okstra install` writes this skill to `~/.agents/skills/okstra-code-review/` on every machine (and to `~/.claude/skills/` only when `~/.claude` exists), making the literal path `~/.agents/skills/okstra-code-review/references/review-calibration.md` — the same string whether the skill was copied in or dev-linked. Carry it, together with the pack list, into every Step 3 brief.
119
- 4. Build the cells per `references/census-rules.md` and print, in this response: one cell table per axis, the exclusion list with a reason on every entry, and the applied pack list.
119
+ 4. Build the cells per `references/census-rules.md` with `okstra code-review census --project-root <projectRoot> --base <baseCommit> --head <headCommit> --rules <rules-path> --out <census-path>`, where `<rules-path>` holds the shared rule catalog for the routed packs; on a follow-up add `--previous-census <prior-census-path>` so identical targets keep their IDs. Exit 1 lists changed non-Python code under Unresolved function boundaries: add those function cells by hand before dispatch. Then print, in this response: one cell table per axis, the exclusion list with a reason on every entry, and the applied pack list.
120
120
  5. Restate both completion criteria and show they hold: censused files + exclusions = files in the diff, and every hunk maps to a censused function or to file-level code.
121
121
 
122
122
  **Membership is mechanical; judgment only ever decides a cell's verdict.** Never drop a cell because you doubt the rule applies to it — that doubt is the reviewer's answer, and its name is `clean`. Over-inclusion costs one line; a judged exclusion is the run-to-run variance this census exists to remove.
@@ -125,7 +125,7 @@ A large census is never truncated. Report the cell count and confirm before disp
125
125
 
126
126
  ## Step 3 — Select one to three model teams with six specialists each
127
127
 
128
- Let the user choose one to three reviewers with distinct models at review start; the default is 2. Honor an explicit count without asking again. Otherwise offer 2 as the default/recommended choice, with 1 and 3 as alternatives. Carry the selected value as `<reviewerCount>`; use 2 when the user accepts the default or supplies no count. Keep that count for this review and its gap-fills. The instruction and its default are checked by `tests/contract/test_standalone_agent_invocation_surfaces.py::test_code_review_dispatches_use_verified_standalone_invocations`; the runtime count range is enforced by `resolve_operation_slots` and `tests/run/test_operation_invocation.py::test_the_caller_picks_a_count_up_to_the_contract_s`. This skill is model-agnostic: do not hard-code provider names, model names or versions, preferred model order, or specialty-to-model mappings. Resolve the roster from the runtime's registered model pool for each new review:
128
+ Let the user choose one to three reviewers with distinct models at review start; the default is 2. Honor an explicit count without asking again. Otherwise offer 2 as the default/recommended choice, with 1 and 3 as alternatives. Carry the selected value as `<reviewerCount>`; use 2 when the user accepts the default or supplies no count. Keep that count for this review and its gap-fills. The instruction and its default are checked by the retired Python suite; the runtime count range is enforced by `resolve_operation_slots` and the retired Python suite. This skill is model-agnostic: do not hard-code provider names, model names or versions, preferred model order, or specialty-to-model mappings. Resolve the roster from the runtime's registered model pool for each new review:
129
129
 
130
130
  ```
131
131
  okstra agent-prompt resolve-operation --operation code-review --count <reviewerCount>
@@ -153,7 +153,7 @@ Each returned slot is a model-team coordinator, not a specialty. Every coordinat
153
153
 
154
154
  Each model coordinator divides its received full census into six assigned censuses and passes each one to its responsible subagent. The orchestrator supplies the same full census to each coordinator; the coordinator owns division and delivery within its team. Copy the specialty's rules and all cells of its axis without changing IDs, targets, references or ordering. Naming/readability share semantic cell IDs; state/tests share state-and-tests cell IDs. Their rule subsets differ. Within each team, assigned `(cell ID, rule ID)` pairs are disjoint and their union equals the full census's pairs. Across models the entire assignment repeats independently. Never partition specialties between models. An empty specialty is recorded by its coordinator as not applicable without inventing checks or dispatching an empty review. Do not pass an empty census to `scope` or `check-coverage`, which require cells.
155
155
 
156
- Show all selected model teams and the six-specialty division policy before dispatching coordinators. Each coordinator records its concrete child assignments before spawning them. The initial review includes `reviewerCount` coordinator calls and up to `6 × reviewerCount` specialty subagent calls, plus automatic coverage gap-fills under Step 3.5. Honor any user-set cost or call limit; an insufficient limit blocks dispatch rather than silently reducing the team. This authorization does not cover provider retries, new scope, another model or a new implementation round. Instruction presence is checked by `tests/contract/test_standalone_agent_invocation_surfaces.py::test_code_review_dispatches_use_verified_standalone_invocations`; delegation, authorization and assignment accuracy remain lead checks.
156
+ Show all selected model teams and the six-specialty division policy before dispatching coordinators. Each coordinator records its concrete child assignments before spawning them. The initial review includes `reviewerCount` coordinator calls and up to `6 × reviewerCount` specialty subagent calls, plus automatic coverage gap-fills, format repairs and single provider retries under Step 3.5. Honor any user-set cost or call limit; an insufficient limit blocks dispatch rather than silently reducing the team. This authorization does not cover further provider retries, new scope, another model or a new implementation round. Instruction presence is checked by the retired Python suite; delegation, authorization and assignment accuracy remain lead checks.
157
157
 
158
158
  Each selected model coordinator itself spawns its six specialty subagents through a supported delegation surface, collects their verified completions, requests any specialty gap-fills, and consolidates their results before returning its model report. The orchestrator launches the selected coordinators; it does not spawn their children on their behalf or consolidate raw child results. These are actual separate model calls, not six headings in one response. Preserve the verified provider/model binding and standalone evidence for every child. If a coordinator cannot spawn and collect its children under that binding, report an execution blocker rather than moving those responsibilities to the orchestrator, substituting a model or replacing the team with one serial review. Specialty subagents do not delegate further. Never share other model teams' verdicts before independent team reports are complete.
159
159
 
@@ -183,7 +183,7 @@ it. **Every reviewer receives its assigned census** and independently owns its v
183
183
  - **the assigned census** — its rule subset and grouped cells, verbatim, plus its model-team slot, specialty, parent coordinator ID and the full census path for context. Coordinators receive the full census and all six child assignments; children receive only their own verdict assignment
184
184
  - the absolute paths of the packs allocated to its axes (from step 2's routing)
185
185
  - shared test execution evidence, including missing or blocked verification
186
- - the full-context inspection requirement: read whole target files, enclosing definitions, affected callers and callees, contracts, outcome consumers and related tests at the frozen head; follow transitive effects as needed. Specialty limits verdict ownership, not access to context. Report a suspected issue outside the assignment to the lead, who checks it and routes any required inspection to the owning specialist without duplicating or changing cells
186
+ - the full-context inspection requirement: read whole target files, enclosing definitions, affected callers and callees, contracts, outcome consumers and related tests at the frozen head; follow transitive effects as needed. Read with targeted `git show` ranges and `git grep`; never print a whole generated report or graph dump (for example under `graphify-out/`) into a child's context. Specialty limits verdict ownership, not access to context. Report a suspected issue outside the assignment to the lead, who checks it and routes any required inspection to the owning specialist without duplicating or changing cells
187
187
  - the calibration path, written out in full as Step 2 fixed it — `~/.agents/skills/okstra-code-review/references/review-calibration.md`. The verdict format, the severity points, and the rules for a legitimate `clean` are defined there, not in the brief; a reviewer that cannot open this file cannot return a usable verdict, so never hand it a relative path or a "next to the skill" hint
188
188
 
189
189
  **Resolve each slot's inspection scope before materializing its prompt.** Run:
@@ -237,6 +237,8 @@ Pass the `headCommit` that `okstra code-review target` returned. The command rea
237
237
 
238
238
  Automatically fill missing verdicts, unaccounted rules and malformed rows within the authorized review. Preserve every raw response and completion. For each incomplete specialist, dispatch one gap-fill on its original slot and specialty carrying only its incomplete grouped cells, their assigned rule subset, the same range, rule paths and full-context requirements. Ask for a complete row per affected cell under that subset. Use a new invocation ID and repeat materialize → verify → dispatch → materialize-result → complete → verify-completion. Audit that child's initial and gap-fill markers against its entire assigned census. Earlier usable verdicts remain unchanged. Repeat while the incomplete cell count decreases, until every assigned cell passes. Do not rerun completed specialists or borrow another model team's verdicts.
239
239
 
240
+ Two cases get one bounded repeat before the no-progress rule applies. A row rejected only for its syntax (cell or rule separators, escaping, a column count, an observation form the calibration does not allow there) gets one format repair: a continuation on the same child that carries the parser's rejection text and asks for the same verdicts in the calibration row format. That repair does not count toward the no-progress stop. An invocation that exits non-zero without a returned body is retried once on the same slot and specialty under a new invocation ID; a second failure is a provider-execution stop. Each specialist's gap-fills, repair and retry are judged separately: one specialist's stop never stops another specialist that has not had its own gap-fill.
241
+
240
242
  Stop with incomplete coverage when a gap-fill makes no progress, a user-set call/cost limit is reached, source evidence is unavailable, or an invocation fails authentication, billing, provider execution or integrity verification. Unknown cell IDs are invalid: preserve the response and report the blocker rather than relabeling IDs or retrying automatically. Do not treat infrastructure failures as missing inspections. A stopping condition fails the review instead of pausing it for authorization: dispatch no further gap-fills, continue to Step 3.6 with the verified results, and record every unaccounted `(cell ID, rule ID)` pair as a `must-fix` `now` coverage finding that names the pair, its responsible team and specialty, and the blocker. That finding stays open until a later review round accounts for the pair. A manual assessment does not satisfy reviewer coverage or create a verified completion. The lead checks these stopping conditions; the parser only checks accounting and source anchors.
241
243
 
242
244
  An isolated false observation reopens the affected cells and any dependent conclusions, not automatically every valid verdict. Record the excluded completion/cells and retain only independently valid evidence. Semantically rejected rows enter the same affected-cell gap-fill procedure; count them as incomplete when checking progress. If an older row is syntactically valid but disproved, pass the corrected completion first so the existing first-usable rule selects it; retain the older completion only for unaffected rows. If the error's extent cannot be bounded, report the unresolved extent; a full correction requires explicit authorization. Never edit an immutable response to make it pass.
@@ -85,7 +85,7 @@ Two consequences:
85
85
 
86
86
  Test files (the project's test-path or test-suffix convention — `*_test.*`, `*.test.*`, `*.spec.*`, `tests/`, `spec/`) are censused on `state-and-tests` only. They are not excluded: they are covered by a different rule group.
87
87
 
88
- Enumerate functions from the frozen source and intersect their signature/body spans with the diff's changed lines. Include every matching enclosing or nested function, including same-line anonymous functions distinguished by column. Use base-side source spans to locate deletion-only changes and map surviving targets to their head positions. A removed function has no head target; account for its deletion in the surviving file's file-level cells. Changes outside functions (imports, module wiring, top-level declarations, class-level constants) also belong to file-level cells. If boundaries cannot be established, report the incomplete census and stop before dispatch instead of claiming the hunk criterion holds. Instruction presence is checked by `tests/contract/test_standalone_agent_invocation_surfaces.py::test_code_review_dispatches_use_verified_standalone_invocations`; boundary accuracy remains a lead check.
88
+ Enumerate functions from the frozen source and intersect their signature/body spans with the diff's changed lines. Include every matching enclosing or nested function, including same-line anonymous functions distinguished by column. Use base-side source spans to locate deletion-only changes and map surviving targets to their head positions. A removed function has no head target; account for its deletion in the surviving file's file-level cells. Changes outside functions (imports, module wiring, top-level declarations, class-level constants) also belong to file-level cells. If boundaries cannot be established, report the incomplete census and stop before dispatch instead of claiming the hunk criterion holds. Instruction presence is checked by the retired Python suite; boundary accuracy remains a lead check.
89
89
 
90
90
  ## Exclusions
91
91
 
@@ -143,7 +143,7 @@ Keep the original PR base and rebuild its full net-diff census at the new head.
143
143
 
144
144
  Keep all six specialty assignments stable within each selected model team. Run scope/coverage checks separately for each `(model-team slot, specialty)` against its current and previous subset census, then check each coordinator's consolidated report against the full census. Do not substitute another specialty's or model's completions. Each model independently covers the full census through its children. An empty assignment is acknowledged by its coordinator as described in SKILL.md, not passed to these commands.
145
145
 
146
- The `code-review scope` command proposes carry candidates per reviewer. It verifies prior completion integrity, role/model consistency within the prior results, complete prior coverage, ancestor history, exact base/head baseline, catalog references, and rule/policy content fingerprints. It reopens cells with prior findings, changed targets or changed recorded inputs. Missing dependency records reopen their cells. Any changed path outside the prior inventory, changed rules/base, rewritten history or missing baseline falls back to full review. Invalid completion integrity stops scope calculation. These checks are enforced by `code_review_scope.py::review_scope` and the standalone completion scope tests.
146
+ The `code-review scope` command proposes carry candidates per reviewer. It verifies prior completion integrity, role/model consistency within the prior results, ancestor history, exact base/head baseline, catalog references, and rule/policy content fingerprints. It reopens cells with prior findings, changed targets or changed recorded inputs, and cells the prior results left unverified. Missing dependency records reopen their cells. A changed path outside the prior inventory reopens only the cells that list it and is named in the scope reason so reviewers search it for further effects. Changed rules/base, rewritten history, unknown prior cell IDs or a missing baseline fall back to full review. Invalid completion integrity stops scope calculation. These checks are enforced by `code_review_scope.py::review_scope` and the standalone completion scope tests.
147
147
 
148
148
  Record each inspected cell's repository-relative input files under `Review Dependencies`: its whole target file, definitions/callees, callers, outcome consumers, relevant tests and contracts read to justify the verdict. Include transitive dependencies. Paths describe files, not line ranges; changing any part reopens the dependent cell. An external rule or instruction belongs in the repeated `--policy` inputs instead. A gap-fill retains the same baseline and records dependencies for its inspected cells.
149
149
 
@@ -39,4 +39,4 @@ Read the returned human report. Explain the business findings, verified scope an
39
39
 
40
40
  The investigation reads source, configuration, test bodies and explicitly supplied existing results. Its policy forbids executing tests, starting services, deploying, migrating or editing investigated projects. The report distinguishes that policy and the before/after source audit from an enforced write boundary. A report and a shared fact use the same accepted evidence. New runs retain prior reports and source baselines.
41
41
 
42
- Enforcement: `business_flow.engine` validates the result schema, source evidence and source stability before contribution; `agent.invocation` verifies standalone completion; `business_flow.store` preserves claim provenance and source versions. These behaviors are covered by `tests/run/test_business_flow.py` and existing invocation/JSON-boundary contract tests.
42
+ Enforcement: `business_flow.engine` validates the result schema, source evidence and source stability before contribution; `agent.invocation` verifies standalone completion; `business_flow.store` preserves claim provenance and source versions. These behaviors are covered by the retired Python suite and existing invocation/JSON-boundary contract tests.
@@ -39,9 +39,9 @@ For settings, `kind: done` means the settings transaction finished: show `next.l
39
39
 
40
40
  ## When NOT to Use
41
41
 
42
- - User explicitly asks to spawn a new terminal / new agent session — use `okstra-inspect history.4` (resume command) or instruct them to run `okstra` in another terminal.
43
- - User wants status only — use `okstra-inspect status`.
44
- - User wants past runs — use `okstra-inspect history`.
42
+ - User explicitly asks to spawn a new terminal / new agent session — instruct them to run `okstra` in another terminal.
43
+ - User wants status only — use `okstra task-show <task-key>`.
44
+ - User wants past runs — use the task timeline.
45
45
 
46
46
  <!-- BEGIN FRAGMENT: wizard-relay-protocol -->
47
47
  ## How the wizard talks to you
@@ -176,7 +176,7 @@ This prints one absolute path on stdout (e.g. `/var/folders/.../okstra-wizard.Ab
176
176
 
177
177
  Then initialize the wizard with the literal `projectRoot` / `projectId` you parsed from Step 1 and the literal state-file path from above.
178
178
 
179
- For task continuity, pass `--preferred-task-key <project-id:task-group:task-id>` on every initialization when this conversation has a known task. Use the task explicitly requested in the current message first; otherwise use the last task the user selected in this conversation's wizard. Resolve abbreviated task IDs against the project catalog before passing the full key. If the ID is ambiguous, ask which matching task the user means. Never infer this conversation's selection from project-wide `latest-task.json`, catalog recency, or another session. With neither an explicit task nor a prior selection in this conversation, omit the flag. The runtime puts the preferred task first, including a completed task when explicitly carried in, and rejects a key absent from the catalog instead of substituting another task; ordering is covered by `tests/domain/wizard/test_task_selection.py`. The task picker still lets the user change tasks.
179
+ For task continuity, pass `--preferred-task-key <project-id:task-group:task-id>` on every initialization when this conversation has a known task. Use the task explicitly requested in the current message first; otherwise use the last task the user selected in this conversation's wizard. Resolve abbreviated task IDs against the project catalog before passing the full key. If the ID is ambiguous, ask which matching task the user means. Never infer this conversation's selection from project-wide `latest-task.json`, catalog recency, or another session. With neither an explicit task nor a prior selection in this conversation, omit the flag. The runtime puts the preferred task first, including a completed task when explicitly carried in, and rejects a key absent from the catalog instead of substituting another task; ordering is covered by the former Python suite; that regression check is now retired. The task picker still lets the user change tasks.
180
180
 
181
181
  After a successful task selection, retain the returned full task key in this conversation as its task context, including in continuation summaries, and carry it into the next initialization. A different selection replaces it. Selecting a brand-new task clears the previous selection; retain the new full key once its project, group, and task ID are resolved. This conversation carry-forward is a lead instruction, not automatic host-session discovery by the runtime.
182
182
 
@@ -447,7 +447,7 @@ When the user picks a waiver, append `--qa-waiver "<stageKey>:<reason>"` to the
447
447
  If `render-bundle` stdout carries an `okstra concurrent-run stages: <stages>` label line (another implementation run on the same task-key is occupying `<stages>`), the launch prompt has already been rendered with the "Concurrent-run marker" gate. If this line is absent it is not a concurrent run, so skip this branch. If present, before dispatch present a 3-option recommendation picker to the user (run-prompt recommendation rule: 1–2 recommendations + Enter directly; this picker is authored by the skill, so it is unconstrained by the wizard `options[]` rule):
448
448
 
449
449
  1. (recommended) Proceed as-is — use the already-rendered bundle. Each session uses its own implicit team, so concurrent runs have no team conflict and split-pane works fine.
450
- 2. Wait — hold the dispatch for now. The stage worktree·run-context are preserved, so after the other occupying run finishes, resuming the same stage takes the normal team path. Print the resume command (`okstra-inspect` history → resume) to the user.
450
+ 2. Wait — hold the dispatch for now. The stage worktree·run-context are preserved, so after the other occupying run finishes, resuming the same stage takes the normal team path. Tell the user to resume the same stage with `okstra-run` after the other run finishes.
451
451
  3. Enter directly.
452
452
 
453
453
  ### Stale git SHA recovery (git-reconcile gate)
@@ -554,4 +554,4 @@ Follow the rendered launch prompt's "Progress, remaining work, and recommendatio
554
554
  - Echo each captured answer (`result.echo`) on one short line so the user sees what was registered.
555
555
  - Name every file you show the user as a markdown link — `[<short label>](<absolute path>)`, with the absolute path inside the parentheses and a short label naming what the file is. A relative destination does not open from an external program. That is the only form the host renders as clickable; a path in backticks is text the user has to copy out. The `report-finalize` result's `reportPaths.markdown` carries the run's report, report record, and team state already in that form. Commands stay in backticks — a link is for a file, not for something to run.
556
556
  - Never invent identity; if a `text` prompt returns an empty answer where the wizard rejects it, the user must retry.
557
- - After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, finish after Step 6 and any same-run recovery, unless the user has already authorized continuing the task through further phases. In an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. When `report-finalize` returns `recovery.mode: same-run`, continue the authorized corrections in this run and execute `recovery.resumeCommand` before closeout; preserve approvals and model choices without reopening the wizard. The command and owner issues are supplied by `report_finalize._finalize_recovery`. When the lead (or this skill, after the lead returns) reports a successfully finalized run over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take the pointer from the `report-finalize` result's top-level `nextRecommendedPhase` (`phase`, `status`, `rationale`; also on stderr as `next phase status:` / `next phase:` / `next phase rationale:`) — do not re-derive it from the report, and treat a `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. The same result also carries `nextCommand` — `{command, note}`, the table below already applied to this run. When `command` is non-empty it is the close; when it is empty the `note` says what to do with the `rationale` instead. After `implementation-planning`, open `blocks: approval` rows → `/okstra-user-response`. A recorded `accept-risk` / `select` / `answer` is not an open blocker. No open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run; do not say `/okstra-inspect`). For every other task type, quote the pointer's `rationale` in every branch — that sentence is the report's own reason and it is what the user asked to be analysed. Pointer `status: ready` → `/okstra-run` for that phase; `status: terminal` → say the task is finished, name any follow-up tasks this run registered, and do not say `/okstra-inspect`; `status: blocked` → issue the command the `rationale` calls for (`/okstra-user-response` for the `C-NNN` ids, `/okstra-run` for the phase it names); `validate-run` failed with `recovery.mode: phase-reentry` → name the cause and use `nextCommand` for the recorded earlier phase; otherwise `/okstra-inspect status`.
557
+ - After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, finish after Step 6 and any same-run recovery, unless the user has already authorized continuing the task through further phases. In an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. When `report-finalize` returns `recovery.mode: same-run`, continue the authorized corrections in this run and execute `recovery.resumeCommand` before closeout; preserve approvals and model choices without reopening the wizard. The command and owner issues are supplied by `report_finalize._finalize_recovery`. When the lead (or this skill, after the lead returns) reports a successfully finalized run over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take the pointer from the `report-finalize` result's top-level `nextRecommendedPhase` (`phase`, `status`, `rationale`; also on stderr as `next phase status:` / `next phase:` / `next phase rationale:`) — do not re-derive it from the report, and treat a `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. The same result also carries `nextCommand` — `{command, note}`, the table below already applied to this run. When `command` is non-empty it is the close; when it is empty the `note` says what to do with the `rationale` instead. After `implementation-planning`, open `blocks: approval` rows → `/okstra-user-response`. A recorded `accept-risk` / `select` / `answer` is not an open blocker. No open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run). For every other task type, quote the pointer's `rationale` in every branch — that sentence is the report's own reason and it is what the user asked to be analysed. Pointer `status: ready` → `/okstra-run` for that phase; `status: terminal` → say the task is finished, name any follow-up tasks this run registered; `status: blocked` → issue the command the `rationale` calls for (`/okstra-user-response` for the `C-NNN` ids, `/okstra-run` for the phase it names); `validate-run` failed with `recovery.mode: phase-reentry` → name the cause and use `nextCommand` for the recorded earlier phase; otherwise `okstra task-show <task-key>`.
@@ -16,7 +16,7 @@ Generate a consolidated work schedule for the selected `implementation-planning`
16
16
  - User asks to generate a work schedule / plan / "schedule" for an entire `task-group`
17
17
  - User wants a single document that summarizes all non-done tasks with effort, risk, and dependencies
18
18
 
19
- **Do NOT use** for single-task analysis (use `okstra-inspect status`) or to execute one task (use `okstra-run`).
19
+ **Do NOT use** for single-task analysis or to execute one task (use `okstra-run`).
20
20
 
21
21
  Public invocation: `/okstra-schedule-gen [task-group]`. A title or directive may be supplied in the host conversation. If none is, name the schedule after the work itself — read the task titles in scope and write what they do (e.g. `폰트 업로드 경로 개선 — 작업 일정`). Never title it after the group token: that is a directory name, not what the work is.
22
22
 
@@ -103,7 +103,7 @@ One computation rule the template scaffold cannot carry inline:
103
103
 
104
104
  ### Step 2: Filter by workStatus
105
105
 
106
- For inference when `workStatus` is missing or empty, defer to the inference table in `skills/okstra-inspect/SKILL.md` (`status.4` → "Default value convention") — do not duplicate it here. Then filter: resolved `done` → exclude; everything else (`todo` / `in-progress` / `blocked` / `phase-done` / inferred non-done) → include.
106
+ When `workStatus` is missing or empty, infer `done` if `currentStatus` is `completed` and `workflow.nextRecommendedPhase.status` is `terminal`; infer `phase-done` if `currentStatus` is `completed` and `workflow.currentPhaseState` is `completed`; infer `blocked` if `currentStatus` is `contract-violated` or `workflow.currentPhaseState` is `blocked`; otherwise infer `in-progress`. Do not write inferred values back. Then filter: resolved `done` → exclude; everything else (`todo` / `in-progress` / `blocked` / `phase-done` / inferred non-done) → include.
107
107
 
108
108
  If 0 tasks remain, output `All tasks in this task-group are done. There is no schedule to generate.` and stop **without creating a file**.
109
109
 
@@ -305,7 +305,7 @@ Reached only after both Step 5.5 gates return `pass`. Promote the verified same
305
305
 
306
306
  | Case | Handling |
307
307
  |------|----------|
308
- | `workStatus` absent or empty | Resolve via the `okstra-inspect status.4` inference table; include unless resolved `done` |
308
+ | `workStatus` absent or empty | Apply the inference rules above; include unless resolved `done` |
309
309
  | Filtered task count is 0 | Emit the "all tasks are done" message; do NOT create a file |
310
310
  | No implementation-planning report | List with a `[NEEDS-PLANNING]` banner only; no stage picker / Gantt / day total |
311
311
  | 0 remaining stages (all done, workStatus unmarked) | `_Complete — no remaining stage_`, no forward computation |
@@ -20,8 +20,7 @@ machine, or when adopting okstra in a new project.
20
20
 
21
21
  ## When NOT to use
22
22
 
23
- - A task is already in flight → use [`okstra-run`](../okstra-run/SKILL.md) or
24
- [`okstra-inspect status`](../okstra-inspect/SKILL.md).
23
+ - A task is already in flight → use [`okstra-run`](../okstra-run/SKILL.md).
25
24
  - Day-to-day usage in a project that already has `project.json` — skip this skill.
26
25
 
27
26
  ## Prerequisites
@@ -56,7 +55,7 @@ Replace `<host-runtime>` with the resolved literal value before executing each
56
55
  command. Keep the same resolved host for installation, preflight, diagnostics,
57
56
  and retries, including retries against another project or npm cache directory.
58
57
  The runtime registry validates host IDs; the skill command contract is checked
59
- by `tests/contract/test_docs_runtime_contract.py::test_skills_declare_their_host_runtime_explicitly`.
58
+ by the former Python suite; that regression check is now retired.
60
59
 
61
60
  ```bash
62
61
  npx -y okstra@latest install --runtime <host-runtime>
@@ -193,6 +193,11 @@ from okstra_ctl.conformance import (
193
193
  qa_result_from_dict,
194
194
  validate_conformance_manifest,
195
195
  )
196
+ from okstra_ctl.conformance_evidence import ( # noqa: E402
197
+ RunConformanceEvidence,
198
+ collect_conformance_evidence,
199
+ )
200
+ from okstra_ctl.verification_conformance import conformance_stage # noqa: E402
196
201
  from okstra_ctl.dispatch_state import ( # noqa: E402
197
202
  DispatchError,
198
203
  v2_worker_state_key,
@@ -1925,6 +1930,70 @@ def _load_conformance_results(qa_dir: Path, manifest: dict) -> dict:
1925
1930
  return results
1926
1931
 
1927
1932
 
1933
+ def _evidence_conformance_results(
1934
+ run_manifest_path: Path | None,
1935
+ project_root: Path | None,
1936
+ manifest: dict,
1937
+ scoped: dict,
1938
+ failures: list[str],
1939
+ ) -> tuple[dict, dict, dict[str, str]] | None:
1940
+ """Gated entries, results and unusable-record messages of a
1941
+ `verificationEvidenceVersion` run.
1942
+
1943
+ None for a run without that field, whose results stay the verifier-written
1944
+ sidecars. A marked run never reads a sidecar: a stage without an execution
1945
+ record has no result, and a stage whose latest records are no usable
1946
+ evidence is reported with those records instead of as never run.
1947
+ """
1948
+ if run_manifest_path is None or project_root is None:
1949
+ return None
1950
+ run_manifest = load_json(run_manifest_path)
1951
+ if "verificationEvidenceVersion" not in run_manifest:
1952
+ return None
1953
+ entries = [entry for entry in manifest.get("entries", []) if isinstance(entry, dict)]
1954
+ evidence = RunConformanceEvidence(frozenset(), {})
1955
+ if run_manifest["verificationEvidenceVersion"] != "1.0":
1956
+ failures.append(
1957
+ "conformance gate BLOCKING: unsupported verification evidence version "
1958
+ f"{run_manifest['verificationEvidenceVersion']!r} in {run_manifest_path}"
1959
+ )
1960
+ else:
1961
+ try:
1962
+ evidence = collect_conformance_evidence(
1963
+ project_root, run_manifest_path,
1964
+ [entry["stageKey"] for entry in entries],
1965
+ )
1966
+ except ValueError as exc:
1967
+ failures.append(
1968
+ "conformance gate BLOCKING: verification execution evidence "
1969
+ f"could not be collected for {run_manifest_path}: {exc}"
1970
+ )
1971
+ gated = list(scoped.get("entries", []))
1972
+ for entry in entries:
1973
+ if entry not in gated and _entry_stage(entry) in evidence.stages:
1974
+ gated.append(entry)
1975
+ results = {
1976
+ key: stage.result for key, stage in evidence.results.items()
1977
+ if stage.result is not None
1978
+ }
1979
+ unusable = {
1980
+ key: "no usable execution record: " + "; ".join(
1981
+ f"{path} ({reason})" for path, reason in stage.rejections.items())
1982
+ for key, stage in evidence.results.items()
1983
+ if stage.result is None and stage.rejections
1984
+ }
1985
+ return {"entries": gated}, results, unusable
1986
+
1987
+
1988
+ def _entry_stage(entry: dict) -> int | None:
1989
+ try:
1990
+ return conformance_stage(str(entry.get("stageKey")))
1991
+ except ValueError:
1992
+ # expected-miss: a stage key without a stage number names no stage a
1993
+ # generation can require; `_scope_manifest_entries` gates it by suffix.
1994
+ return None
1995
+
1996
+
1928
1997
  def _diff_summary_files(report_data: Mapping[str, Any]) -> list[str]:
1929
1998
  """implementation 리포트가 신고한 변경 파일 목록 (`implementation.diffSummary.files[].file`).
1930
1999
 
@@ -2332,9 +2401,15 @@ def _validate_conformance(
2332
2401
  failures: list[str],
2333
2402
  surface_patterns: object = None,
2334
2403
  approved_plan_path: Path | None = None,
2404
+ run_manifest_path: Path | None = None,
2405
+ project_root: Path | None = None,
2335
2406
  ) -> list[str]:
2336
2407
  """Tier 3 conformance 게이트(implementation / final-verification).
2337
2408
 
2409
+ A run manifest with `verificationEvidenceVersion` takes results from the
2410
+ verification execution records alone and also gates every stage its
2411
+ generations require, such as an earlier stage whose script changed.
2412
+
2338
2413
  A missing task-level manifest is inert only without approved-plan evidence.
2339
2414
  When a recorded approved plan declares conformance for the in-scope stage,
2340
2415
  disappearance of that manifest is a blocking structural failure. Otherwise,
@@ -2425,9 +2500,16 @@ def _validate_conformance(
2425
2500
  f"in {manifest_path}"
2426
2501
  )
2427
2502
  scoped = _scope_manifest_entries(manifest, stage_name)
2503
+ evidence = _evidence_conformance_results(
2504
+ run_manifest_path, project_root, manifest, scoped, failures,
2505
+ )
2506
+ gated, results, unusable = (
2507
+ evidence if evidence is not None
2508
+ else (scoped, _load_conformance_results(qa_dir, scoped), {})
2509
+ )
2428
2510
  entries_by_key = {
2429
2511
  entry.get("stageKey"): entry
2430
- for entry in scoped.get("entries", [])
2512
+ for entry in gated.get("entries", [])
2431
2513
  if isinstance(entry, dict) and isinstance(entry.get("stageKey"), str)
2432
2514
  }
2433
2515
  for stage_key, entry in entries_by_key.items():
@@ -2444,8 +2526,7 @@ def _validate_conformance(
2444
2526
  "conformance result or record a user-acknowledged waiver. See "
2445
2527
  "docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md §7.1."
2446
2528
  )
2447
- results = _load_conformance_results(qa_dir, scoped)
2448
- for verdict in evaluate_conformance(scoped, results):
2529
+ for verdict in evaluate_conformance(gated, results):
2449
2530
  if verdict.status == "ADVISORY":
2450
2531
  entry = entries_by_key.get(verdict.stage_key, {})
2451
2532
  warnings.append(
@@ -2456,9 +2537,13 @@ def _validate_conformance(
2456
2537
  f"manifest: {manifest_path}"
2457
2538
  )
2458
2539
  elif not verdict.ok:
2540
+ # `unusable` keys only result-less stages, whose BLOCKING verdict
2541
+ # reads "never ran"; their rejected records exist, so the records
2542
+ # and their defects replace that message.
2459
2543
  failures.append(
2460
2544
  f"conformance gate BLOCKING for stage {verdict.stage_key}: "
2461
- f"{verdict.message}. Run the stage's conformance script (or declare "
2545
+ f"{unusable.get(verdict.stage_key, verdict.message)}. "
2546
+ f"Run the stage's conformance script (or declare "
2462
2547
  f"an exemption / user waiver) — see "
2463
2548
  f"docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md."
2464
2549
  )
@@ -2471,6 +2556,23 @@ def _validate_conformance(
2471
2556
  return warnings
2472
2557
 
2473
2558
 
2559
+ def _validate_run_conformance(
2560
+ report_path: Path, run_manifest_path: Path, project_root: Path,
2561
+ failures: list[str],
2562
+ ) -> list[str]:
2563
+ """The conformance gate as `run_preflight` and `main` both run it."""
2564
+ return _validate_conformance(
2565
+ report_path,
2566
+ failures,
2567
+ surface_patterns=_project_surface_patterns(project_root),
2568
+ approved_plan_path=_approved_plan_path_from_run_inputs(
2569
+ run_manifest_path, failures
2570
+ ),
2571
+ run_manifest_path=run_manifest_path,
2572
+ project_root=project_root,
2573
+ )
2574
+
2575
+
2474
2576
  _TEST_FILE_RE = re.compile(r"(\.spec\.|\.test\.|(^|/)test_|_test\.|(^|/)tests?/)")
2475
2577
  # okstra ships deliberately self-mocked samples as detector fixtures; gating
2476
2578
  # them would make okstra permanently fail its own gate when verifying itself.
@@ -5758,13 +5860,8 @@ def run_preflight(report_path: Path, run_manifest_path: Path) -> int:
5758
5860
  project_root = Path(
5759
5861
  str(manifest.get("projectRoot") or run_manifest_path.parent)
5760
5862
  )
5761
- warnings = _validate_conformance(
5762
- report_path,
5763
- failures,
5764
- surface_patterns=_project_surface_patterns(project_root),
5765
- approved_plan_path=_approved_plan_path_from_run_inputs(
5766
- run_manifest_path, failures
5767
- ),
5863
+ warnings = _validate_run_conformance(
5864
+ report_path, run_manifest_path, project_root, failures,
5768
5865
  )
5769
5866
  elif task_type == "implementation-planning":
5770
5867
  from okstra_ctl.report_assembly import selected_direction_plan_errors
@@ -6008,14 +6105,8 @@ def main() -> int:
6008
6105
  failures,
6009
6106
  )
6010
6107
  if task_type in ("implementation", "final-verification"):
6011
- conformance_warnings = _validate_conformance(
6012
- report_path,
6013
- failures,
6014
- surface_patterns=_project_surface_patterns(project_root),
6015
- approved_plan_path=_approved_plan_path_from_run_inputs(
6016
- run_manifest_path,
6017
- failures,
6018
- ),
6108
+ conformance_warnings = _validate_run_conformance(
6109
+ report_path, run_manifest_path, project_root, failures,
6019
6110
  )
6020
6111
  _validate_selfmock(report_path, failures)
6021
6112
  for warning in conformance_warnings: