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
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md
CHANGED
|
@@ -204,22 +204,49 @@ The final report keeps both — executor's `Validation evidence` AND each verifi
|
|
|
204
204
|
|
|
205
205
|
### Static design & test-quality review (gate — runs after the command re-run, before the verdict)
|
|
206
206
|
|
|
207
|
+
When the dispatch supplies Frozen Design Review, its census is the assigned worklist.
|
|
208
|
+
Return the binding lines, grouped Coverage Verdicts and Design Findings format it
|
|
209
|
+
specifies. Do not substitute file-level summaries or the executor's self-check for
|
|
210
|
+
function-level M1/M2/M3 judgments. Missing accounting remains incomplete.
|
|
211
|
+
|
|
212
|
+
When Verification inputs contains a Frozen Review Policy, apply its captured
|
|
213
|
+
rule sources, architecture declaration and `review-rules.json` metadata instead
|
|
214
|
+
of current project settings and installed rules. Read them through the
|
|
215
|
+
verification-input projection. Original paths identify provenance, not a live
|
|
216
|
+
baseline. Select applicable resources with the router below. Legacy inputs
|
|
217
|
+
without this policy continue to use the lookup below.
|
|
218
|
+
For the captured policy, repeat `--source-path <repository-relative-path>` for
|
|
219
|
+
the relevant changed files in one `okstra model-io verification-input
|
|
220
|
+
--run-manifest <run-manifest>` call. Read complete selected rule bodies, not only
|
|
221
|
+
the available-resource index, and do not clip normative lines.
|
|
222
|
+
|
|
223
|
+
Apply the captured `clean-code.md` "Five simultaneous quality outcomes" to the
|
|
224
|
+
actual diff: correctness, coding principles, performance, safety and security
|
|
225
|
+
retain their applicable acceptance conditions. Reuse declared bounds and shared
|
|
226
|
+
execution evidence. A necessary missing bound or check remains unverified;
|
|
227
|
+
neither a green command nor complete grouped rows establish all five outcomes.
|
|
228
|
+
|
|
229
|
+
Resolve conflicts by `overview.md` policy precedence: explicit repository
|
|
230
|
+
instructions and declared architecture, the common pack, then surrounding code
|
|
231
|
+
conventions. Cite the governing instruction for an exception; an existing code
|
|
232
|
+
pattern alone does not waive an explicit architecture rule.
|
|
233
|
+
|
|
207
234
|
Re-running commands proves the diff *builds and passes*; it does NOT prove the diff is *well-designed*. Lint/test green is necessary but not sufficient — self-mocked tests, interaction-only assertions, and untruthful names all survive a green pipeline. This gate is the filter for exactly those defects, so the executor's design errors are caught here instead of in post-merge PR review. It is a real gate, not a checklist: it enumerates the full diff and a blocking hit forces `FAIL`. This blocking-check taxonomy is the **gate counterpart** of the executor's `Pre-commit diff review sweep` (`_implementation-diff-review.md`) prevention pass — the same defect families, different action (executor fixes in place; verifier fails the verdict). Both lists are inlined on purpose: each sidecar is delivered stand-alone into a flat CLI prompt (lazy-read, not INCLUDE-expanded), so neither can factor the taxonomy into a shared fragment.
|
|
208
235
|
|
|
209
|
-
- **Scope (no silent sampling).** Enumerate every changed
|
|
210
|
-
- **Load the
|
|
211
|
-
- **Load the project's review rule packs.**
|
|
212
|
-
- **Declared architecture style
|
|
236
|
+
- **Scope (no silent sampling).** Enumerate every changed file via `git diff --name-only <base>...HEAD`, apply the shared census exclusion policy and review every retained file, including executable configuration. Record each exclusion and its reason; extension alone does not establish one. Skipping a retained changed file silently is a `contract-violated` outcome. If a file's language has no reference and is not covered by the agnostic checks below, record `design-review skipped: <file> (language=<x> no reference)` — never pass it silently.
|
|
237
|
+
- **Load the executor's selected frozen conventions.** Use the captured projection above when available and record `coding-conventions: resources=<...>`. Only legacy inputs without that policy use the `**Coding preflight pack:**` installed path and its router, including every matching language/framework/architecture resource. A missing required captured source is blocked input; never replace it with live content. For unreadable legacy resources only, retain the agnostic checks and record `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>`.
|
|
238
|
+
- **Load the project's review rule packs.** Union the policy's standing standards with exact `SKILL.md` paths cited by the task brief's `Source Material` / `Reporter Confirmations`. With a frozen policy, use their captured bodies and directly named captured `references/*.md` bodies from the verification-input projection. A cited pack or reference missing from that capture is blocked input to report for recapture; do not omit it or read live originals. Only unfrozen legacy inputs run project-context for `Project Review Rule Packs` and read those declared files and their directly named references. Do not search parent directories or host skill catalogs. Apply the rules as an overlay on this static review, but do NOT dispatch extra reviewer agents unless the task explicitly configured them. Record `project-review-rules: <paths read>`, `project-review-rules: declared <path> unreadable`, or `project-review-rules: none declared or cited` in the worker result — an unreadable declared pack is a recorded gap, not a skip.
|
|
239
|
+
- **Declared architecture style selects the placement overlay.** Take `Architecture style` from the captured projection, or the legacy project-context projection, and record `architecture-style: <hexagonal|layered|none|undeclared>` beside `coding-conventions:`. A declared `hexagonal` selects H1–H6 even without layout signals and makes H5's otherwise-advisory concrete-adapter item binding. A declared `layered` selects no pack resource; its invariant is upper-to-lower dependency direction and variation points on layer boundaries. Cite changed reverse dependencies from their imports. Explicit `none` selects no overlay; only absent or `undeclared` style uses layout detection. An inferred hexagonal overlay retains each rule's criteria and severity, including H5's undeclared-style advisory exception. Apply policy precedence and shared grading; an established current blocking finding requires `FAIL`. `review_policy.py` selects the declared overlay and `_validate_verifier_fail_blocks_verdict` prevents a recorded `FAIL` from being dropped during synthesis; neither proves boundary interpretation.
|
|
213
240
|
- **Blocking checks (any hit → verdict `FAIL`, cited `path:line` + rule name, recommended fix recorded — the verifier does NOT apply it):**
|
|
214
241
|
- **Security (every changed file that reads input from outside the process or acts on its behalf — `clean-code.md` "Untrusted input and security"):** work that grows faster than the input — pairwise uniqueness, nested scans, a backtracking regex, input-driven recursion — reachable before a size/count bound has rejected oversized input (read the validation framework's configuration: class-validator without `stopAtFirstError` still runs `@ArrayUnique` after `@ArrayMaxSize` fails, and a byte-size body limit does not bound element count); input concatenated into SQL, a shell command, a file path, a server-side fetch target, a template or a regex; a new route / handler / resolver without the project's auth guard, or a lookup by an input-chosen id that never compares the caller with the owner; a secret, full token, password or personal data written to source, logs, an error message or a response; `eval`, dynamic code, or unsafe deserialization applied to input. Cite the input that triggers it and its effect — for unbounded work, the input size and the measured or derived cost.
|
|
215
242
|
- **New duplication / DRY:** two or more newly added or meaningfully modified blocks implement the same helper stack, transform, or domain rule. Literal copy-paste is always blocking; semantically equivalent transforms across services are blocking unless the approved plan explicitly justified keeping them separate. The comparison is not limited to this diff: a newly added block that is byte-identical to a block already in the repository — base code, or a copy an earlier stage landed — is the same blocking finding, cited at both the new `path:line` and the existing one, because `final-verification` grades that cross-stage copy as an Acceptance Blocker and a per-stage `clean` only defers it. Test helpers and test support code count. Recommend the shared module location.
|
|
216
243
|
- **Self-mocking:** a test for `Foo` stubs/spies a method on the `Foo` instance under test (`jest.spyOn(sut, ...)`, `spyOn(FooService.prototype, ...)` in `foo.*.spec.*`, `vi.mocked(sut)` + stub). Mocking injected collaborators is fine.
|
|
217
244
|
- **Interaction-only assertion:** a test whose only/primary assertion is `toHaveBeenCalled*` / `toHaveBeenCalledTimes` on an internal helper or a non-side-effecting collaborator, with no assertion on the returned value / resulting state / persisted row / emitted event.
|
|
218
245
|
- **Tautological delegation assertion:** a test asserts the SUT result equals a direct call to the same pure helper/collaborator that the SUT delegates to, instead of asserting an independent literal value or observable state.
|
|
219
|
-
- **Untruthful name:** a read-named function (`get*` / `find*` / `load*`) that
|
|
220
|
-
- **Wrong-result trace (every changed source file):** follow the paths this diff creates or alters to their end — error, partial, concurrent, selection — and name the input or state that produces a wrong result (`clean-code.md` §"Trace what this change can do wrong"). This one is an obligation, not a pattern: the defects that reach production are usually ordinary code with no name on this list. The bar is also the noise filter — a finding names the failing input; an alternative structure, a guard for a state no caller reaches, or a "consider extracting" is an improvement and verdicts `clean`. The failure modes the plan lists are the floor of this trace, not its ceiling: a verdict scoped to "the modeled failures" is not a verdict on the file. For every `try` whose `catch` / `finally` cleans up, check at each call inside it that can throw (a property write, a read, a call that starts other work) whether the thing to clean up is already registered at that point; when the diff moves or restructures existing code, compare that order with the base version and cite the base `path:line` when it changed. A failure the test fakes cannot produce (a throwing setter or read the fake does not model) is recorded as unverified with the failure named, never folded into `clean`. **The unit is the changed source file**: record `clean` or findings for each one, list every file
|
|
221
|
-
- **Business rules in an application service (only when the hexagonal overlay is loaded):** changed service code that
|
|
222
|
-
- **Hexagonal (only when the overlay is loaded):** business
|
|
246
|
+
- **Untruthful name:** a read-named function (`get*` / `find*` / `load*`) that performs caller-visible mutations its name does not disclose, or an undefined or misleading business term. Inspect the port contract and governing policy before judging a domain-oriented query name; `findValid*` / `findActive*` and complex SQL alone do not establish a violation.
|
|
247
|
+
- **Wrong-result trace (every changed source file):** follow the paths this diff creates or alters to their end — error, partial, concurrent, selection — and name the input or state that produces a wrong result (`clean-code.md` §"Trace what this change can do wrong"). This one is an obligation, not a pattern: the defects that reach production are usually ordinary code with no name on this list. The bar is also the noise filter — a finding names the failing input; an alternative structure, a guard for a state no caller reaches, or a "consider extracting" is an improvement and verdicts `clean`. The failure modes the plan lists are the floor of this trace, not its ceiling: a verdict scoped to "the modeled failures" is not a verdict on the file. For every `try` whose `catch` / `finally` cleans up, check at each call inside it that can throw (a property write, a read, a call that starts other work) whether the thing to clean up is already registered at that point; when the diff moves or restructures existing code, compare that order with the base version and cite the base `path:line` when it changed. A failure the test fakes cannot produce (a throwing setter or read the fake does not model) is recorded as unverified with the failure named, never folded into `clean`. **The unit is the changed source file**: record `clean` or findings for each one, list every excluded file and its reason under the shared census exclusion policy, and close the section with `general: <N> files — all verdicted, <M> excluded`. Configuration that controls executable behavior is reviewed under that policy rather than excluded by extension alone.
|
|
248
|
+
- **Business rules in an application service (only when the hexagonal overlay is loaded):** changed service code that implements a business decision instead of orchestrating a domain-owned one (`architectures/hexagonal.md` Rule H6). Inspect the implementation and governing rule; a private method's domain-oriented name alone is not evidence. Orchestration control flow, DTO mapping and calling a domain predicate are not violations. Apply shared grading when declaration or layout selects the overlay; a substantial embedded rule such as money, permissions or a state machine remains blocking.
|
|
249
|
+
- **Hexagonal (only when the overlay is loaded):** executable business decisions inside a port body; business policy invented or changed in an adapter rather than owned by the domain; misplaced domain objects or outward domain dependencies contrary to the applicable architecture. An adapter may translate domain-owned query specifications into efficient SQL, including compound predicates and joins. Complex SQL, a domain-oriented query name or post-fetch processing alone is not a violation; do not require `findAll` plus in-memory filtering. Inspect the governing policy, port contract and imports, and apply `overview.md` precedence and H1–H6 whether declaration or layout selected the overlay. Existing code conventions alone cannot waive an applicable boundary. Grade established current violations with the shared rubric; H5 alone retains its undeclared-style advisory exception.
|
|
223
250
|
- **gitignored file committed to the branch:** any path in the `git diff --name-only <base>...HEAD` enumeration that `.gitignore` excludes — enumerate them by piping that list through `git check-ignore --stdin --no-index`. A committed ignored file means the executor bulk-added (`git add .`/`-A`) or force-staged (`git add -f`) it, leaking build output, scratch files, or verification artifacts into the eventual PR. This explicitly includes `.okstra/` paths (and `.project-docs/` when the legacy symlink is present): `.okstra/**` is gitignored, so a committed okstra file (qa scripts, conformance results) is always this defect. Cite each path; recommend `git rm --cached <path>` to untrack it while keeping the file on disk. Conformance/qa evidence belongs in the carry sidecar / verifier result, never in git history.
|
|
224
251
|
- **Real-IO test in source tree:** a changed/added test under the project source test tree — `src/**`, `test/**`, `tests/**`, `**/__test__/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*` — that opens a **real** DB connection / DSN, makes a real `fetch` / `axios` / `http` request, or otherwise hits real external IO without mocking the injected collaborator (a live handle, not a stub/spy). Real-IO tests MUST live under `<task_root>/qa/scripts/` per the executor's *Real-IO test isolation* rule — a live-IO test in source silently breaks the project's CI suite and violates the artifact-home rule. Cite the test file + the real-IO line; recommend moving it to `<task_root>/qa/scripts/` (or declaring it as a Tier 3 conformance script). Mock-only unit tests in source are NOT a hit.
|
|
225
252
|
- **Proxy-based identity decision:** a move / ownership / re-parenting decision taken from a status field or flag while the source and destination identifiers were available and never compared. Cite the condition and the identifiers it should have compared, and show the opposite case the condition also reads true for.
|
|
@@ -231,10 +258,11 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
|
|
|
231
258
|
- **Positional mock-argument access:** `mock.calls[<n>][<m>]` (or the framework equivalent) used to inspect arguments instead of an intent-revealing `toHaveBeenCalledWith` / explicit-absence assertion. Detect with `rg 'mock\.calls'` over the changed test files.
|
|
232
259
|
- **Non-separating test data:** two scenarios whose setup values and assertions are identical, so a wrong implementation passes both; or new test tooling added in this diff (mock, state setter, repository branch) that no test calls.
|
|
233
260
|
- **Effect claimed under its own mock:** a test presented as covering an effect whose producing path is replaced by a mock inside that same test. The mock's presence in the harness is not evidence the branch behind it works.
|
|
234
|
-
- **Single-caller abstraction (KISS):** an abstraction layer this diff introduces — a helper module, a strategy / factory / builder, an indirection or wrapper layer, an interface or abstract base — that has exactly one caller after the change, where inlining it at that call site would be simpler. The rule is `overview.md` core principle 2: name the second caller now, or inline. Four exits are legitimate and each must **cite its evidence**: the approved plan declares it (a `testSeams[]` boundary or a variation-point extraction — cite the plan step); the project declares `architecture.style = hexagonal` and this is a port at the domain boundary (a port with one adapter is the normal shape, not a violation); it breaks a real import cycle (name both modules); or its single caller is the public API of a published package. Absent one of those, cite `path:line` and recommend the inlined shape.
|
|
261
|
+
- **Single-caller abstraction (KISS):** an abstraction layer this diff introduces — a helper module, a strategy / factory / builder, an indirection or wrapper layer, an interface or abstract base — that has exactly one caller after the change, where inlining it at that call site would be simpler. The rule is `overview.md` core principle 2: name the second caller now, or inline. Four exits are legitimate and each must **cite its evidence**: the approved plan declares it (a `testSeams[]` boundary or a variation-point extraction — cite the plan step); the project declares `architecture.style = hexagonal` and this is a port at the domain boundary (a port with one adapter is the normal shape, not a violation); it breaks a real import cycle (name both modules); or its single caller is the public API of a published package. Absent one of those, cite `path:line` and recommend the inlined shape. This targets reusable layers, not a local helper that names a cohesive step or separates mixed abstraction levels, nor a pre-existing abstraction this diff merely edits. Line count alone does not justify extraction.
|
|
235
262
|
- **File-size limit (every verifier, not only the stage QA owner):** run `okstra correction file-size --base <base>` from the worktree cwd and log it in the `Read-only command log`. Each `FILE-SIZE:<path>:501 <before>-><after>` line it prints is a blocking finding cited exactly as printed — a new file over 500 lines, or a file the diff took from 500 or fewer past 500. A file already over 500 at the stage base that the diff grows is not blocking; the command prints it as an advisory line. Recommended fix: move whole responsibilities into new modules or test files beside it. The command writes nothing and its result is the same for every verifier, so the finding converges and the lead sends it to a correction round. Each `FILE-SIZE-ADVISORY:<path>:301` line (the 300-line target: a new file over 300, a file the diff took past 300, or a file already over 300 the diff grew, including one already over 500) goes under the advisory findings below, not here. Do not judge size yourself: a file it does not print is not a finding (lockfiles, data, Markdown, fixtures, snapshots, generated files and languages without a coding preflight are exempt by `scripts/okstra_ctl/file_size_cap.py` `capped_path`).
|
|
236
263
|
- **Caller-less identifier (YAGNI / orphan):** an identifier this diff leaves with zero callers — either newly added and never called (a speculative parameter, an optional config object, a "future-proof" hook, an exported helper whose only caller is hypothetical), or pre-existing code orphaned because this diff removed its last caller. Grep the identifier across the whole repository rather than the diff alone; a hit inside its own declaration, its own test, or a commented-out line is not a caller. Two exits are legitimate and must be **stated with their evidence**, never assumed: an identifier the approved plan reserves for a named later stage (cite the plan step), and a contract point something other than project code calls (a framework entrypoint, an implemented interface method, a migration hook, the public API of a published package — cite the caller or the registration). Anything else is work no requirement asked for: recommend deleting it, or folding an added parameter back into its single call site. A caller-less identifier is the one YAGNI violation that survives a green pipeline unchanged, which is why it grades here rather than as a recommendation.
|
|
237
|
-
- **
|
|
264
|
+
- **Shared grading:** use the captured catalog and `clean-code.md` "Finding evidence and grading". A clear M1/M2 violation (misleading name, mixed responsibility, excessive complexity or mixed abstraction levels) can be `should-fix` / `now` and forces `FAIL` even when commands pass. More than 50 effective function lines prompts inspection; it does not establish a violation or force a split. Name the rule, source and design consequence; a preferred alternative alone is not a finding. Apply the same evidence test to state policy, unobserved error causes and missing resource-bound tests rather than automatically downgrading them. Restrictive plan placement returns a plan conflict, never permission to pass a current violation.
|
|
265
|
+
- **Nonblocking findings:** `nit`, justified `park`, and size-only target advisories may accompany `PASS`. An already oversized file's size advisory does not exempt its added responsibilities from S3/M2. Architecture-specific latitude follows the declared style and the applicable project rule; record its cited basis. Do not demand unrelated legacy cleanup.
|
|
238
266
|
- **Output.** Every finding — blocking or advisory — is a structured item in the verifier's worker result (`path:line`, rule, severity, suggested fix) so it carries into Phase 5.5 convergence and the final report. Each item, advisory items included, carries an item id as `prompts/profiles/_common-contract.md` "Cross-worker traceability" defines it for worker output. The lead cites a finding by that id, and `okstra convergence seed` refuses a cited id that does not occur in the result, so an unnumbered item cannot enter convergence and drops out of the report. This is a guideline: nothing parses a verifier result for missing ids. A blocking hit sets the verifier verdict to `FAIL` with the rule cited, using the same verdict machinery as the Discrepancy rule above. The Okstra lead MUST NOT silently downgrade a cited blocking finding to advisory during synthesis; an override requires a concrete cited reason, exactly as for the Discrepancy rule.
|
|
239
267
|
|
|
240
268
|
### Fix-run incremental scope (applies when the profile carries a "Fix-Run Carry" block)
|
package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html
CHANGED
|
@@ -26,6 +26,19 @@
|
|
|
26
26
|
{% for row in implementation.verifierResults %}<article class="summary-card tone-{{ row.verdict | lower }}"><p class="eyebrow">{{ row.verifier | inline_code }} · <span class="status status-{{ row.verdict | lower }}">{{ row.verdict }}</span></p>{% for label, text in ((t('tasks.implementation.independent-rerun'), row.get("independentValidationRerun")), (t('tasks.implementation.command-log'), row.get("readOnlyCommandLog"))) if text %}<details><summary><strong>{{ label }}</strong> {{ t('tasks.implementation.entry-count') | replace('{count}', text.strip().splitlines() | select | list | length | string) }}</summary><pre>{{ text }}</pre></details>{% endfor %}{% if row.get("executionEvidence") %}<p><strong>{{ t('tasks.implementation.execution-records') }}</strong></p><ul class="evidence-refs" data-report-field="implementation.verifierResults.executionEvidence">{% for ref in row.executionEvidence %}<li><code>{{ ref.checkRef }}</code> run {{ ref.checkRun }} · {% if ref.collection == "complete" %}{{ t('tasks.implementation.exit-code') }} {{ ref.exitCode if ref.exitCode is not none else ref.signal }}{% else %}<span class="status status-incomplete">{{ t('tasks.implementation.incomplete-collection') }}</span> {{ ref.defect | inline_code }}{% endif %} · <code>{{ ref.recordPath }}</code></li>{% endfor %}</ul>{% endif %}{% if row.get("discrepancy") %}<p class="evidence-refs">{{ t('tasks.implementation.discrepancy') }} {{ row.discrepancy | inline_code }}</p>{% endif %}{% if row.get("declinedFixRecommendations") %}<p>{{ row.declinedFixRecommendations | inline_code }}</p>{% endif %}</article>{% endfor %}
|
|
27
27
|
</section>
|
|
28
28
|
|
|
29
|
+
{% for verifier in implementation.verifierResults if verifier.get("designReview") %}
|
|
30
|
+
<section data-report-field="implementation.verifierResults.designReview">
|
|
31
|
+
<h2>{{ verifier.verifier | e }} · Design review</h2>
|
|
32
|
+
{% set review = verifier.designReview %}
|
|
33
|
+
<p>{{ review.collection | e }} · {{ review.get("coveredCells", 0) | e }}/{{ review.get("expectedCells", 0) | e }} cells · {{ review.verdict | e }}</p>
|
|
34
|
+
{% if review.get("reason") %}<p>{{ review.reason | e }}</p>{% endif %}
|
|
35
|
+
{% for finding in review.get("findings", []) %}<article><h3>{{ finding.id | e }} · {{ finding.rule | e }} · {{ finding.severity | e }} · {{ finding.timing | e }}</h3><p>{{ finding.source | e }}: {{ finding.consequence | e }}</p><p>{{ finding.fix | e }}</p><p>{{ finding.disposition | e }} · {{ finding.basis | e }}</p></article>{% endfor %}
|
|
36
|
+
{% for disposition in review.get("carry", []) %}<p>{{ disposition.finding | e }} · {{ disposition.disposition | e }} · {{ disposition.basis | e }}</p>{% endfor %}
|
|
37
|
+
{% for prior in review.get("history", []) %}{% for finding in prior.get("findings", []) %}<p>Earlier {{ prior.generationNumber | e }}:{{ finding.id | e }} · {{ finding.rule | e }} · {{ finding.severity | e }} · {{ finding.timing | e }} · {{ finding.consequence | e }}</p>{% endfor %}{% endfor %}
|
|
38
|
+
{% if review.get("missing") %}<pre>{{ review.missing | e }}</pre>{% endif %}
|
|
39
|
+
</section>
|
|
40
|
+
{% endfor %}
|
|
41
|
+
|
|
29
42
|
{% if implementation.get("leadFixes") %}<section data-report-section="lead-fixes" data-report-field="implementation.leadFixes">
|
|
30
43
|
<h2>{{ t('tasks.implementation.lead-fixes') }}</h2>
|
|
31
44
|
<p>{{ t('tasks.implementation.lead-fixes-intro') }}</p>
|
|
@@ -17,6 +17,31 @@
|
|
|
17
17
|
|
|
18
18
|
`implementation` executes an approved `implementation-planning` final report into actual code changes and local commits. Source edit is allowed only in this phase, but scope is limited to the approved plan and recorded out-of-plan justification.
|
|
19
19
|
|
|
20
|
+
### Independent design-review evidence
|
|
21
|
+
|
|
22
|
+
New approved-plan preparations use verification-input version 4.0. The frozen
|
|
23
|
+
policy, pre-execution base and generation head define every verifier's identical
|
|
24
|
+
file/function worklist. A missing cell/rule remains incomplete for that verifier;
|
|
25
|
+
another verifier or executor self-check cannot fill it. The existing Python AST
|
|
26
|
+
census includes named test helpers; other supported code languages require a
|
|
27
|
+
source-bound manual inventory before dispatch. Inventory completeness remains
|
|
28
|
+
lead judgment. `design_review.py` and generation capture check these contracts.
|
|
29
|
+
|
|
30
|
+
The shared catalog and grading reference classify clear naming/readability
|
|
31
|
+
violations without requiring runtime failure. `design_review_evidence.py`
|
|
32
|
+
authenticates the reserved invocation, latest attempt and sealed result bytes.
|
|
33
|
+
Report assembly derives the evidence and verdict rather than accepting a writer
|
|
34
|
+
summary; current blocking findings and incomplete accounting prevent acceptance.
|
|
35
|
+
`stage_done.py` and phase validation re-derive the same evidence. Final
|
|
36
|
+
verification checks the prepared source reports for consistency, without a
|
|
37
|
+
global style review. Existing input versions keep their resume contract.
|
|
38
|
+
|
|
39
|
+
Each correction generation re-inspects the full stage diff and dispositions
|
|
40
|
+
every earlier blocking finding in `Design Carry`. Old findings remain in the
|
|
41
|
+
machine-owned history, including nits and parked items. No rule judgments are
|
|
42
|
+
inherited without dependency evidence. Regression owners are
|
|
43
|
+
`tests/verification/test_design_review.py` and `tests/report/test_assembly.py`.
|
|
44
|
+
|
|
20
45
|
## 2. okstra-run wizard flow
|
|
21
46
|
|
|
22
47
|
```mermaid
|
|
@@ -428,6 +428,12 @@ def validate_verifier_execution_evidence(
|
|
|
428
428
|
attempt of the invocation bound to the newest generation, with the bytes and
|
|
429
429
|
observation it recorded; a `not-run` row is not read.
|
|
430
430
|
"""
|
|
431
|
+
from ...design_review_evidence import validate_design_review_report
|
|
432
|
+
|
|
433
|
+
try:
|
|
434
|
+
validate_design_review_report(data, project_root, manifest_path)
|
|
435
|
+
except (OSError, ValueError) as exc:
|
|
436
|
+
failures.append(f"design-review BLOCKING: {exc}")
|
|
431
437
|
try:
|
|
432
438
|
evidence = collect_report_evidence(project_root, manifest_path)
|
|
433
439
|
except ValueError as exc:
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
- In `candidate-comparison` mode, the lead merges overlapping candidates, then re-evaluates every merged candidate against the same criteria before ranking it.
|
|
26
26
|
- In `candidate-comparison` mode, display at most three merged candidates and record every rejected candidate with its rejection reason and cited evidence for audit.
|
|
27
27
|
- Map every displayed candidate or preselected direction to the stable brief end-state IDs it satisfies, preserves, or leaves unresolved.
|
|
28
|
-
- **Close the vote gaps before you conclude `blocked`.** Round 1 runs the designers in parallel, so each one votes only on the candidates it proposed and the merged set ends up with a different hole per analyser. A candidate that is otherwise sound then fails the every-analyser clause and drops out of the ranking — three such candidates blocked a run whose comparison had in fact converged (2026-09-10, dev-10629-4: IO-001, IO-002 and IO-003 each held two `feasible` votes and each was missing a different designer). Run `okstra option-votes gaps --task-manifest <taskManifestPath> --narrative <
|
|
28
|
+
- **Close the vote gaps before you conclude `blocked`.** Round 1 runs the designers in parallel, so each one votes only on the candidates it proposed and the merged set ends up with a different hole per analyser. A candidate that is otherwise sound then fails the every-analyser clause and drops out of the ranking — three such candidates blocked a run whose comparison had in fact converged (2026-09-10, dev-10629-4: IO-001, IO-002 and IO-003 each held two `feasible` votes and each was missing a different designer). Run `okstra option-votes gaps --run-manifest <current-run-manifest> --task-manifest <taskManifestPath> --narrative <reportNarrativePath>` before assembly. For each analyser it names, dispatch one vote-completion assignment asking for that analyser's own feasibility verdict, rationale, and counterevidence on the named candidate — no new candidate, so the run stays in `candidate-comparison` mode. The command reports no gap when a vote cannot settle the block (safety blockers, unresolved feasibility facts, too few feasible verdicts); that is the honest `blocked`.
|
|
29
29
|
- Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
|
|
30
30
|
- Classify every `unresolvedFeasibilityFacts` entry with `resolutionKind`: `user-decision` requires nonempty `clarificationRefs` naming the actual C-NNN records for that fact; `technical-verification` requires source review, design evidence, or experiments and does not require a user question. `deferred-gate` marks a fact that no technical-verification run can close because closing it needs something that phase forbids, such as a deployed environment (for example, a cold-start measurement of a deployed Lambda); it requires `gate`, naming where the fact closes (a brief `External Gates` entry, or final-verification user-owned external QA), and it does not make the candidate invalid. A fact that a probe, a source read, or a disposable local service can close is `technical-verification`, not `deferred-gate`. The selected direction snapshot carries every remaining fact of the chosen option as `deferredFeasibilityFacts`, so planning schedules its gate. Enforced by `blocking_feasibility_facts` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`. Preserve `fact`, `whyItMatters`, and `evidence`. Reuse answered questions and their recorded dispositions; never reopen one merely to save the report. An unrelated open question does not satisfy a missing reference. Historical unclassified entries remain readable, but blocked report reassembly requires the writer to classify them explicitly. Enforced by `validate_blocked_answer_channel` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`, called by report assembly and `validate-run.py`. Saving preserves `routing: blocked` and does not make a candidate valid. In `humanSummary.actions`, `verdictCard.nextStep`, and selection guidance, distinguish pending user decisions from remaining technical verification; after the pilot route is answered, carry the selected route and remove the old answer-waiting instruction.
|
|
31
31
|
- **A split vote ends in a user decision, not another run.** When no candidate is valid only because its votes split (at least one `feasible`, the others `uncertain` or `not-feasible`, no `safetyBlockers`), another option-selection or technical-verification run asks the same designers the same question and returns the same split (fontradar dev-11562: three runs, `feasible` against `uncertain` each time). Before you route `blocked` or `technical-verification` on such a candidate, open one approval decision for it with `okstra approval-decision open --ledger <approvalDecisionsPath> --candidate-ref <IO-NNN>` naming that candidate (classification `noncritical-dissent`): the recommended option is `accept-risk` (proceed with this direction and carry the dissent and the remaining facts into planning), the alternative is `request-revision` (keep the run blocked). Ask the user in-session; record the answer with `okstra approval-decision resolve`. On `accept-risk`, the writer sets `splitAcceptance.clarificationRef` on that candidate, which makes it valid with one `feasible` vote; it then follows the ordinary routing (`implementation-planning` for a validated preselected direction, `pending-direction-selection` in `candidate-comparison`). Leave the votes and facts on the row. The answer accepts that candidate only; no other candidate cites it. When the user is not present, publish the report `blocked` with that approval row open; the next run carries the answer. Enforced by `validate_split_acceptance` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`, called by report assembly and `validate-run.py`.
|
|
@@ -27,11 +27,9 @@ from collections.abc import Mapping
|
|
|
27
27
|
from pathlib import Path
|
|
28
28
|
from typing import Any
|
|
29
29
|
|
|
30
|
-
from okstra_ctl.final_report_schema import load_schema_version
|
|
31
30
|
from okstra_ctl.phases.implementation_option_selection.validation import VoteGap, vote_gaps
|
|
32
31
|
from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
|
|
33
|
-
from okstra_ctl.
|
|
34
|
-
from okstra_ctl.report_narrative import parse_narrative_structure
|
|
32
|
+
from okstra_ctl.report_narrative import load_writer_input
|
|
35
33
|
|
|
36
34
|
|
|
37
35
|
class OptionVotesError(ValueError):
|
|
@@ -45,7 +43,9 @@ def _record_from_report(path: Path) -> dict[str, Any]:
|
|
|
45
43
|
raise OptionVotesError(f"report record is unreadable: {exc}") from exc
|
|
46
44
|
|
|
47
45
|
|
|
48
|
-
def _record_from_narrative(
|
|
46
|
+
def _record_from_narrative(
|
|
47
|
+
path: Path, *, run_manifest: Path | None = None,
|
|
48
|
+
) -> dict[str, Any]:
|
|
49
49
|
"""작성자 서사를 레코드 모양으로 읽는다.
|
|
50
50
|
|
|
51
51
|
값 결함은 무시한다 — 교정 원장이 고칠 자리이고, 표 구멍을 세는 데에는
|
|
@@ -53,12 +53,11 @@ def _record_from_narrative(path: Path) -> dict[str, Any]:
|
|
|
53
53
|
아직 교정 중인 run 은 이 명령을 쓸 수 없다.
|
|
54
54
|
"""
|
|
55
55
|
try:
|
|
56
|
-
|
|
57
|
-
|
|
56
|
+
return load_writer_input(
|
|
57
|
+
path, run_manifest=run_manifest, structure_only=True,
|
|
58
|
+
)
|
|
59
|
+
except (OSError, UnicodeError, ValueError) as exc:
|
|
58
60
|
raise OptionVotesError(f"narrative is unreadable: {exc}") from exc
|
|
59
|
-
schema = load_schema_version(CURRENT_REPORT_SCHEMA_VERSION)
|
|
60
|
-
record, _defects = parse_narrative_structure(markdown, schema)
|
|
61
|
-
return record
|
|
62
61
|
|
|
63
62
|
|
|
64
63
|
def participating_analysers(manifest_path: Path) -> tuple[str, ...]:
|
|
@@ -131,7 +130,7 @@ def _gaps(args: argparse.Namespace) -> int:
|
|
|
131
130
|
record = (
|
|
132
131
|
_record_from_report(args.report)
|
|
133
132
|
if args.report
|
|
134
|
-
else _record_from_narrative(args.narrative)
|
|
133
|
+
else _record_from_narrative(args.narrative, run_manifest=args.run_manifest)
|
|
135
134
|
)
|
|
136
135
|
gaps = vote_gaps(
|
|
137
136
|
_selection(record), participating_analysers(args.task_manifest)
|
|
@@ -176,7 +175,8 @@ def _parser() -> argparse.ArgumentParser:
|
|
|
176
175
|
help="a published final-report `.data.json`")
|
|
177
176
|
gaps_parser.add_argument(
|
|
178
177
|
"--narrative", type=Path,
|
|
179
|
-
help="the report writer's
|
|
178
|
+
help="the report writer's declared input, before assembly")
|
|
179
|
+
gaps_parser.add_argument("--run-manifest", type=Path)
|
|
180
180
|
gaps_parser.add_argument("--json", action="store_true")
|
|
181
181
|
return parser
|
|
182
182
|
|
|
@@ -69,8 +69,7 @@ from okstra_ctl.plan_review_context import render_review_context
|
|
|
69
69
|
from okstra_ctl.stage_ledger import build_stage_ledger
|
|
70
70
|
from okstra_ctl.claim_reproduction import NOT_RUNNABLE, reproduce
|
|
71
71
|
from okstra_ctl.file_size_cap import headroom_text, planned_file_headroom
|
|
72
|
-
from okstra_ctl.
|
|
73
|
-
from okstra_ctl.report_narrative import parse_narrative
|
|
72
|
+
from okstra_ctl.report_narrative import load_writer_input
|
|
74
73
|
from okstra_ctl.report_assembly import validate_plan_draft
|
|
75
74
|
from okstra_ctl.error_log_write import record_runtime_failure
|
|
76
75
|
from okstra_ctl.user_response import parse_user_response_entries
|
|
@@ -194,9 +193,11 @@ def _parser() -> argparse.ArgumentParser:
|
|
|
194
193
|
commands = parser.add_subparsers(dest="command", required=True)
|
|
195
194
|
extract = commands.add_parser("extract")
|
|
196
195
|
_add_plan_source(extract)
|
|
196
|
+
extract.add_argument("--run-manifest", type=Path)
|
|
197
197
|
extract.add_argument("--output", type=Path, required=True)
|
|
198
198
|
validate = commands.add_parser("validate")
|
|
199
199
|
_add_plan_source(validate)
|
|
200
|
+
validate.add_argument("--run-manifest", type=Path)
|
|
200
201
|
validate.add_argument("--items", type=Path, required=True)
|
|
201
202
|
prepare = commands.add_parser("prepare")
|
|
202
203
|
_add_plan_source(prepare)
|
|
@@ -425,13 +426,13 @@ def _plan_source(args: argparse.Namespace) -> dict[str, Any]:
|
|
|
425
426
|
if args.data is not None:
|
|
426
427
|
return _load_json_object(args.data)
|
|
427
428
|
try:
|
|
428
|
-
|
|
429
|
+
return load_writer_input(
|
|
430
|
+
args.narrative, run_manifest=getattr(args, "run_manifest", None),
|
|
431
|
+
)
|
|
429
432
|
except (OSError, UnicodeError) as exc:
|
|
430
433
|
raise PlanItemContractError(
|
|
431
434
|
f"cannot read report narrative {args.narrative}: {exc}"
|
|
432
435
|
) from exc
|
|
433
|
-
try:
|
|
434
|
-
return parse_narrative(markdown, load_schema_version("3.0"))
|
|
435
436
|
except ValueError as exc:
|
|
436
437
|
raise PlanItemContractError(f"invalid report narrative: {exc}") from exc
|
|
437
438
|
|
|
@@ -1049,6 +1050,10 @@ def _render_file_size_headroom(rows: object) -> str:
|
|
|
1049
1050
|
return ""
|
|
1050
1051
|
lines = [
|
|
1051
1052
|
"\n## File-size headroom\n",
|
|
1053
|
+
"\nA negative headroom identifies an already oversized file, not permission to add "
|
|
1054
|
+
"unrelated responsibilities. Apply S3/M2 to the proposed placement. If the plan's "
|
|
1055
|
+
"file restrictions prevent a conforming change, return a plan conflict with the "
|
|
1056
|
+
"proposed module/test location and the acceptance behavior it preserves.\n",
|
|
1052
1057
|
"Existing files this plan writes, measured before any stage runs. Information "
|
|
1053
1058
|
"only: it is not a verdict criterion.\n",
|
|
1054
1059
|
]
|
|
@@ -1187,12 +1192,14 @@ def validate_current_review(run_manifest: Path) -> PreparedPlanReview:
|
|
|
1187
1192
|
name = authority.payload.get("reportNarrativePath")
|
|
1188
1193
|
if not isinstance(name, str) or not name:
|
|
1189
1194
|
raise PlanItemContractError("reportNarrativePath is missing")
|
|
1190
|
-
narrative =
|
|
1191
|
-
if not narrative.is_relative_to(authority.run_dir):
|
|
1195
|
+
narrative = authority.project_root / name
|
|
1196
|
+
if not narrative.resolve(strict=True).is_relative_to(authority.run_dir):
|
|
1192
1197
|
raise PlanItemContractError("plan narrative must stay inside the current run")
|
|
1193
1198
|
items_path = _prepared_items_path(run_manifest, require_regular=True)
|
|
1194
1199
|
prepared = _load_json_object(items_path)
|
|
1195
|
-
source = _plan_source(argparse.Namespace(
|
|
1200
|
+
source = _plan_source(argparse.Namespace(
|
|
1201
|
+
data=None, narrative=narrative, run_manifest=run_manifest,
|
|
1202
|
+
))
|
|
1196
1203
|
items = _envelope(source)["items"]
|
|
1197
1204
|
if prepared.get("items") != items:
|
|
1198
1205
|
raise PlanItemContractError("prepared plan items do not match the current narrative")
|
|
@@ -1220,7 +1227,7 @@ def finish_verification_round(
|
|
|
1220
1227
|
verified = subprocess.run(
|
|
1221
1228
|
[sys.executable, str(assets.joinpath(*RUN_VALIDATOR_RELATIVE)),
|
|
1222
1229
|
"--section", "plan-body", "--narrative", str(review.narrative),
|
|
1223
|
-
"--state", str(review.state)],
|
|
1230
|
+
"--state", str(review.state), "--run-manifest", str(review.manifest)],
|
|
1224
1231
|
capture_output=True, text=True, check=False, timeout=60,
|
|
1225
1232
|
)
|
|
1226
1233
|
if verified.returncode:
|
|
@@ -8,12 +8,9 @@ rules live in `prompts/profiles/`.
|
|
|
8
8
|
### Step 5.1 (implementation-planning only): user-confirmed TDD bypass offer
|
|
9
9
|
|
|
10
10
|
Every plan stage must open with a `RED:` step whose outcome is FAIL and reach a
|
|
11
|
-
later `GREEN:` step (validator S10c). `tddExemption` waives that
|
|
12
|
-
|
|
13
|
-
stage that
|
|
14
|
-
got through by filing the nearest category. That is the failure this flag
|
|
15
|
-
exists to remove: **a closed reason list with no escape makes the plan
|
|
16
|
-
misdescribe itself.**
|
|
11
|
+
later `GREEN:` step (validator S10c). `tddExemption` waives that for
|
|
12
|
+
`doc-only`, `config-only`, `pure-rename`, or a user-granted `user-bypass`. A
|
|
13
|
+
stage that fits none of these is not filed under the nearest category.
|
|
17
14
|
|
|
18
15
|
`render-bundle` accepts an optional `--tdd-bypass "<stage>:<reason>"` flag
|
|
19
16
|
(implementation-planning only). It records a **user-acknowledged** bypass into
|
|
@@ -10,6 +10,8 @@ Use the absolute common-contract paths in the lead prompt's `Okstra Runtime Reso
|
|
|
10
10
|
|
|
11
11
|
This contract defines a **second, independent** verification round that fires only for `task-type = implementation-planning`. The round verifies the *consolidated plan* that the report-writer worker has authored, not the worker findings that were already reconciled earlier.
|
|
12
12
|
|
|
13
|
+
Take every authoring input path below from the current run manifest's `reportNarrativePath`. Its declared `reportAuthoringFormat=json-v1` selects standard JSON with ordinary Markdown inside description strings; an absent field retains `markdown-v1` and its line grammar. Pass that same run manifest to `plan-items prepare`, `seed`, `extract`, `validate`, `validate-prepared`, `plan-verify`, and `incremental-carry` so each consumer selects the declared format. Keep the actual `.json` or `.md` extension when preserving a correction attempt. The final reader's Markdown and HTML remain derived outputs.
|
|
14
|
+
|
|
13
15
|
## Lifecycle position (BLOCKING)
|
|
14
16
|
|
|
15
17
|
Plan-body verification runs **after** finding convergence and **after** the report-writer draft is written. Sequence inside a single implementation-planning run:
|
|
@@ -17,7 +19,7 @@ Plan-body verification runs **after** finding convergence and **after** the repo
|
|
|
17
19
|
```
|
|
18
20
|
Phase 4 workers produce independent analyses (Findings F-001…)
|
|
19
21
|
→ Phase 5.5 FINDING convergence (`prompts/lead/convergence.md`, sections "Convergence Algorithm" through "Convergence State Artifact")
|
|
20
|
-
→ Phase 6 report-writer authors
|
|
22
|
+
→ Phase 6 report-writer authors the manifest-declared input (consolidated Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback)
|
|
21
23
|
→ okstra plan-items prepare + prompt + validate-prepared creates and projects the deterministic P-* queue
|
|
22
24
|
→ PLAN-BODY VERIFICATION ROUND ← this contract
|
|
23
25
|
→ final render/validation
|
|
@@ -64,9 +66,9 @@ Default values are emitted into the manifest by `scripts/okstra_ctl/render.py` (
|
|
|
64
66
|
From the report-writer's draft of `## 5.4 Implementation Plan Deliverables`, the lead creates the verification queue only through this sequence (see also `templates/reports/final-report-v2.template.md` §5.5.9):
|
|
65
67
|
|
|
66
68
|
```text
|
|
67
|
-
okstra plan-items prepare --narrative <
|
|
69
|
+
okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>
|
|
68
70
|
→ place `okstra plan-items prompt --run-manifest <run-manifest>` output verbatim in every verifier prompt
|
|
69
|
-
→ okstra plan-items validate-prepared --narrative <
|
|
71
|
+
→ okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>
|
|
70
72
|
```
|
|
71
73
|
|
|
72
74
|
The persisted `items[]` are the sole queue. The lead MUST NOT freely summarise,
|
|
@@ -413,11 +415,11 @@ round before any host or provider process starts.
|
|
|
413
415
|
|
|
414
416
|
For contract 3.0, `prepare` checks the selected-direction draft with the same semantic validator as publication before writing the queue. Correct all reported references, coverage rows and planned commands through the writer correction procedure, then retry in this run. **Enforced:** `report_assembly.validate_plan_draft` and `plan_items_cli._prepare`; the retired Python suite previously checked that invalid coverage creates no prepared queue.
|
|
415
417
|
|
|
416
|
-
1. Lead runs `okstra plan-items prepare --narrative <
|
|
418
|
+
1. Lead runs `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, places the fixed output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then runs `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. A `File-size headroom` line that prepare prints, and that `okstra plan-items prompt` carries under `## File-size headroom`, is a report only: it names an existing file the plan writes, its lines left before the 500-line implementation limit and the stages that write it. It does not block, open a correction or count as a verdict. After a self-fix rewrite, and after `okstra incremental-carry` on a re-run, pass `--state <plan-body-verification.json>` on prepare and validate-prepared; validate-prepared needs the same `--state` the last prepare used, or it refuses with `prepared dispatch queue does not match` or `prepared review evidence changed`. The runtime reuses a verdict only when its body, complete declared evidence closure, shared analysis packet, plan metadata, reviewer assignments and review contract have the same fingerprint. A missing or uncertain dependency declaration, unresolved reference, non-result or executable fact probe stays in the re-verification queue. Detailed verdicts and their original rounds remain unchanged for reused items. File dependencies cover whole files; step items also include preceding steps; plan-wide and preparation items include all plan items. Python resolves the one convergence-owned state path from that run identity. Dispatch only after exact-match validation succeeds. `observed` / `deferred` stages remain omitted. An empty queue opens no worker dispatch and creates no verification round. **Enforced:** `implementation_planning.authoring._queue_for`, `plan_item_evidence.review_fingerprint`, `_validate_prepared` and the retired Python suite. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
|
|
417
419
|
|
|
418
|
-
**Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <
|
|
420
|
+
**Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <reportNarrativePath> --state <plan-body-verification.json> --run-manifest <run-manifest.json>`. `apply-verdicts` in step 8 refuses a verdict whose item has no `planBodyVerification.planItems[]` row. The report writer never owns that state, so the deterministic seed is the only creator of its rows. The seed is idempotent by id and never touches existing verdicts, so it is safe to re-run between rounds and after a self-fix re-extraction. It does refresh `contentHash` from the current extract. Skipping it makes step 8 fail with `plan-body state has no row for [...]`.
|
|
419
421
|
|
|
420
|
-
**On a re-run, add `--prior-state <the previous run's plan-body-verification-<task-type>-<seq>.json>`.** An incremental re-run then runs `okstra incremental-carry
|
|
422
|
+
**On a re-run, add `--prior-state <the previous run's plan-body-verification-<task-type>-<seq>.json>`.** An incremental re-run then runs `okstra incremental-carry --run-manifest <current-run-manifest> --cur-narrative <reportNarrativePath> ...` and repeats prepare, prompt and validate-prepared with `--state` before dispatch (launch prompt "Incremental re-verification" step 7). A newly seeded item inherits verdicts only when its body and verified evidence fingerprint match the prepared snapshot for the same task. Reused rows carry `carriedForwardFromSeq`; their full verdicts are preserved. Legacy body-only records re-enter verification. A matching id alone never carries: `P-*` ids are positional. The flag requires `--state` and refuses another task's state. **Enforced:** `implementation_planning.authoring._carry_prior_run_verdicts` and `plan_item_evidence.reusable_item_ids`.
|
|
421
423
|
|
|
422
424
|
**`--run-manifest` is what scopes the gate to the stage you are starting.** Seed uses it to overlay disk `done` / `active` onto `planBodyVerification.stageLedger`. The current plan's depends-on fills `ready` / `blocked` when no prior plan exists, so a first run does not treat every stage as in-scope. **Enforced:** `okstra_ctl.plan_items.planning_stage_ledger`.
|
|
423
425
|
2. For each analyser worker in the roster, use `okstra plan-items prompt` output verbatim as the instruction body in the materialization sequence above. Read §"Re-verification rounds (round 2+)" before preparing a later round; read §"Plan-body reverify prompt" only when diagnosing a prompt-contract failure.
|
|
@@ -446,10 +448,10 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
|
|
|
446
448
|
- any advisory `dissent-isolated` / `needs-reverify` present, no `majority-disagree` → `passed-with-dissent`
|
|
447
449
|
- all items `full-consensus` → `passed`
|
|
448
450
|
|
|
449
|
-
**Score the gate with `okstra plan-verify`, never by hand (BLOCKING).** Once this round's verdicts are in the
|
|
451
|
+
**Score the gate with `okstra plan-verify`, never by hand (BLOCKING).** Once this round's verdicts are recorded in the convergence-owned plan-body state, lead runs
|
|
450
452
|
|
|
451
453
|
```
|
|
452
|
-
okstra plan-verify --
|
|
454
|
+
okstra plan-verify --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --state <plan-body-verification.json>
|
|
453
455
|
```
|
|
454
456
|
|
|
455
457
|
and records what it returns: `gate.recomputed` is the round's gate value, `gate.blockedBy` its `gateBlockedBy` causes, `gate.blockingItems` the items that block. The same call runs every plan-body check a round can be judged on alone — provenance, fixability, subject substance, self-fix grouping, round recording, clarification matching, state-file rounds — and exits 2 with `failures[]` when the round is not contract-clean. **A round is not complete while that exit code is non-zero.**
|
|
@@ -485,10 +487,10 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
|
|
|
485
487
|
- **Group the targets by cause before instructing (BLOCKING).** Blocked items are usually several derivatives of one defect. Lead partitions this round's targets into cause groups and instructs each group as **"remove this cause"**, naming the derivatives it accounts for. The convergence command owns the persisted group and correction fields; the lead does not edit JSON state.
|
|
486
488
|
- lead instructs report-writer to rewrite the items in each cause group (NOT a full draft regeneration): one `rewrite` entry per item in a corrections ledger, whose `rule` states the cause group's required outcome; procedure in `prompts/lead/report-writer.md` §"Corrective report-writer dispatch (ledger required)".
|
|
487
489
|
- missing or weak `P-Prep-*` contracts are repaired by adding kind-specific inline detail or an AI-prepared PREP item with a concrete proposal. Facts that require user or external authority remain `blocked` and keep their request material; never invent those facts during self-fix.
|
|
488
|
-
- **Drop plan items whose element the round deleted.** A self-fix rewrite may remove a plan element (a validation check, a rollback row). `P-*` ids are positional, so a deletion shifts every later row and silently re-points surviving verdicts at their neighbours — and a verdict recorded against a removed element keeps blocking a gate while being unfindable in the plan, so reading the plan never reveals the cause. After each round, re-extract plan items with `okstra plan-items extract
|
|
490
|
+
- **Drop plan items whose element the round deleted.** A self-fix rewrite may remove a plan element (a validation check, a rollback row). `P-*` ids are positional, so a deletion shifts every later row and silently re-points surviving verdicts at their neighbours — and a verdict recorded against a removed element keeps blocking a gate while being unfindable in the plan, so reading the plan never reveals the cause. After each round, re-extract plan items with `okstra plan-items extract --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --output <extract-path>` and re-verify any item whose `subject` no longer matches; never carry the old vote forward across a shift. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_verdicts_match_current_subjects` (re-pointing) and `_validate_plan_item_extraction_completeness` (dangling ids).
|
|
489
491
|
- **Classify each cause group before instructing it (BLOCKING).** A group is either an *authoring* defect — the plan says something wrong, incomplete, or self-contradictory, which self-fix owns — or a *citation* defect, where the plan points at an analysis artifact incorrectly. Only the first is self-fix work. For the second the finding already exists and already went through convergence, so the fix is to re-cite the converged artifact; instructing report-writer to re-derive the fact means the author reads the source material and produces a **finding that never went through convergence**, which the plan then carries as if it had. That is the role boundary the lead contract draws ("keep analysis, execution, verification, and report authoring responsibilities distinct; return defects to the role that owns them"), and report-writer is authoring-only by its own contract. `P-Req-*` items with breakage kind `f` are where this goes wrong most often: the question is usually whether a coverage row points correctly at something already measured, not whether the measurement is right. State the classification in the group's instruction so the author knows which of the two it is being asked to do.
|
|
490
492
|
- **A verdict older than the last self-fix is not a verdict unless the item's content is unchanged (BLOCKING).** A verdict cast in round 1 judged the text before the only automatic rewrite. Once that rewrite runs, a changed item's judgement is about a plan that no longer exists. `--round <N>` on `apply-verdicts` stamps each row and copies `contentHash` onto `verifiedContentHash`. `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_verdict_rounds_outlive_self_fix` fails an in-scope item whose verdict round is at or before `selfFixRoundsApplied` **and** whose `contentHash` does not match `verifiedContentHash`. Matching hashes keep the prior verdict — that is what avoids a sweep round over unchanged stages. Deferred and observed items are out of the gate and do not need a post-self-fix verdict. **Enforced:** `_validate_verdict_rounds_outlive_self_fix`.
|
|
491
|
-
- Lead re-runs plan-body verification, then records each worker Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker>=<result.md> --round <N>`. Score the result with `okstra plan-verify --
|
|
493
|
+
- Lead re-runs plan-body verification, then records each worker Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker>=<result.md> --round <N>`. Score the result with `okstra plan-verify --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --state <plan-body-verification.json>`, then call `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N>`. These commands fail on an assigned item the worker left unanswered, on a verdict for an item outside the queue, and on a duplicate worker result. `apply-verdicts` without `--append` replaces every recorded row of the queued items, so it also refuses — before writing — when a row belongs to a round that `complete-round` never closed, naming the round to close first; the votes of a closed round live in `planItems[].rounds`. Skipping `complete-round` between rounds and applying the next one lost 19 items' round-1 votes (2026-09-09). `--discard-open-rounds` is only for re-applying the lost rounds from their result files in order: it also restores `dispatchQueue` to the items those result files answer, because the persisted queue is the latest round's and a verdict for an earlier, wider queue is otherwise refused as outside it (round 1 = 26 items, critic tie = 8, round 3 = 19 on that same run — only the 19 survived). Re-apply each lost round with the flag, `complete-round` it, then the next. **Enforced:** `okstra_ctl.plan_items_cli._reject_uncompleted_round_loss` and `_restore_queue_from_results`.
|
|
492
494
|
- For a self-fix, record the correction through the typed convergence command rather than writing `selfFixNote` or `selfFixGroups` JSON. A resolved item does not create a clarification.
|
|
493
495
|
- **Each round is a worker batch.** Before dispatching round N ≥ 2, reclaim the previous round's completed verifiers exactly as at any other batch boundary (`prompts/lead/okstra-lead-contract.md` "Run-scoped worker-resource lifecycle") and emit `PROGRESS: phase-batch-cleanup panes=<n>`, then announce the round with `PROGRESS: phase-5.5.9-plan-verify round=<N> items=<count>`. Saying a round will "reuse" the previous verifiers and then dispatching under fresh names leaves every prior round holding its panes — five rounds of that is what exhausts the pane budget and blocks the next dispatch. **Enforced:** `validators/validate_session_conformance.py` `_check_plan_verify_cleanup_checkpoints` requires both lines once the state file records two or more rounds.
|
|
494
496
|
- **Round completion.** A round is complete only after `okstra plan-verify` exits 0 and `okstra plan-items complete-round` succeeds. A round left with a non-zero exit carries its defect into the next round's inputs. Exit 0 with a non-empty `advisories[]` is a complete round: those findings are recorded, not round-blocking (step 5, §"`failures[]` carries only the blocking findings"). Report assembly and rendering occur only after the convergence state is terminal. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_plan_body_state_rounds` requires one stored round per round number and a corresponding item vote.
|
|
@@ -63,7 +63,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
63
63
|
- **Follow established patterns**: in existing codebases, conform to current conventions. Targeted cleanup of a file you are already modifying is acceptable; unrelated refactors are not.
|
|
64
64
|
- **Variation-point extraction (OCP)**: when the same behavior is served by two or more resources / implementations — stated in the brief, or foreseeable from a sibling task or the code you inspected — the plan MUST record it in `variationPointAnalysis` and make an evidence-backed `extractionDecision` that preserves the chosen direction's architecture boundaries. Reject a realization that branches on resource identity inside a service (one `if` / `switch` arm per implementation): adding the next implementation then means editing that same call site again, which is the closed-for-extension shape this principle exists to catch. This does not contradict YAGNI below: YAGNI drops *speculative* variation (a second implementation nobody named), while a behavior with two implementations already on the table is a present fact, not a forecast. **Enforced:** the `variationPointAnalysis` bullet under `Required deliverable shape` names the schema / validator / `P-Var-*` enforcement points.
|
|
65
65
|
- **YAGNI ruthlessly**: drop features, abstractions, and configuration knobs that do not serve the stated requirement. The test is a *present* caller, not a plausible one — an abstraction whose only justification is a requirement nobody has stated is this rule's target, while a behavior with two implementations already on the table belongs to `Variation-point extraction` above. **Enforced:** the §5.5.9 plan-body verification round raises a hidden direction expansion on selected-direction `P-Dir-1`, and retains legacy `P-Opt-*` `DISAGREE(e)` semantics. One phase later the `implementation` verifier's Static design gate fails the stage on a caller-less identifier.
|
|
66
|
-
- **Project review-rule preflight**:
|
|
66
|
+
- **Project review-rule preflight**: use the Frozen Review Policy when verification inputs supplies one; legacy inputs retain the union of declared packs and exact brief-cited paths. Apply `clean-code.md` "Finding evidence and grading" and the shared catalog. Plan conforming names, function responsibilities, module placement and behavioral tests before code exists. A file restriction or test-preservation instruction that conflicts with a rule returns a plan conflict naming the proposed location and preserved acceptance behavior; it does not waive the rule. Do not run the PR-review workflow or search host skill catalogs here. Semantic conformance is judged by plan-body verification; freezing and input validity are checked by verification-input preparation.
|
|
67
67
|
- Expected output emphasis:
|
|
68
68
|
- feasible realization of the selected direction or legacy choice
|
|
69
69
|
- dependency and risk visibility
|
|
@@ -86,7 +86,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
86
86
|
- §5.5.9 plan-body verification runs with an **adversarial posture** (`scripts/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md` §"Adversarial plan-body posture"): verifiers open and confirm every cited path / command and put the burden of proof on the plan. The gate threshold is majority-based for kinds `b`/`c`/`e`, but a single `DISAGREE` blocks on its own for the concrete, safety-critical kind `a` (path/symbol mismatch) — and `f` on `P-Req-*` items. `P-Var-*` items are excepted from the kind-`a` exception: a variation-point defect takes a majority. Rollback ordering (`d`) is advisory and never blocks the gate — a rollback is executed by a human, not by okstra's workers or verifiers. A majority also needs ≥2 participating votes, so a lone dissent whose peer returned a non-result does not block on a majority-gated kind (see that contract's §"Adversarial plan-body posture").
|
|
87
87
|
- **Incremental re-verification scope (clarification re-runs):** when the lead's `okstra incremental-scope` decision is `mode == "incremental"` (procedure in `prompts/launch.template.md` §"Clarification Response Carried In"), workers re-analyze ONLY the stages listed in `reverify_stages` (the downstream closure of the impacted stages). Workers MUST NOT re-open, re-score, or re-judge any stage in `carry_stages` — those stages' prior plan-item verdicts are carried forward verbatim, and a worker never overwrites a carried verdict with its own judgement. When the decision is `mode == "full"` (the default), every stage is re-analyzed as usual.
|
|
88
88
|
- **Single incremental-scope decision:** the lead calls `okstra incremental-scope` once the inputs are complete, passing the answered `C-NNN` ids through `--answered-clarifications`, changed design-preparation IDs through `--prep-items`, and any lead-resolved stage numbers through `--impacted`; the CLI unions all three before applying the existing dependency closure and cutoff. The clarification ids are resolved to stages by the CLI from the prior report's own `planItems[].clarificationId` and `blocked C-NNN` coverage links — the lead does not map answers to stage numbers. An answer that changes the selected planning payload, Stage Map, or execution approach is not a local impact: pass `--full-reason`, which is the only structural path that still forces `mode == "full"`. A clarification id that traces to no stage returns `mode == "unresolved"` — ask the user for stage numbers and call again with `--impacted`; do not treat it as full and do not silently drop the id. **When this run only ADDS stages** — every prior stage is `done` and none of them is being re-opened — there are no stage numbers to give: pass `--carry-all-reason` instead. Pinning any prior stage as impacted makes `incremental-carry` demand plan-item verdicts from the current snapshot, which no longer holds them (a `done` stage's plan items are `observed`, so they are never dispatched or scored in this run), so that path has no answer that works. The stage's own row is still declared in the narrative — that is the numbering rule above, not a re-verification. `--carry-all-reason` still applies the base-ref check: if the branch moved, the decision degrades to `full` because the prior stages are no longer "as written". Unknown PREP IDs or invalid `stageRefs` still return an explicit full decision instead of being guessed. When the wizard pin is `auto` and the CLI returns `mode == "incremental"`, keep it — do not upgrade to full. When the user pinned a scope at the wizard (`REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` in `prompts/launch.template.md` §"Clarification Response Carried In" step 0), that pin is an input to this same call — `full` supplies the `--full-reason`, `carry-all` supplies the `--carry-all-reason`, and pinned stage numbers join `--impacted` — never a bypass of the CLI's closure and cutoff.
|
|
89
|
-
- **Stage-aware carry:** for an incremental decision, `okstra incremental-scope` writes the decision to the record this run's manifest names in `incrementalDecisionPath`. The report writer's duty to copy each `carry_stages` stage row unchanged is not stated here — it is generated into that writer's own authoring contract from the same record, with this run's stage numbers in it (`okstra_ctl.report_synthesis_packet.ReportSynthesisPacket._carry_instructions`). After plan-item seeding, run `okstra incremental-carry --cur-narrative
|
|
89
|
+
- **Stage-aware carry:** for an incremental decision, `okstra incremental-scope` writes the decision to the record this run's manifest names in `incrementalDecisionPath`. The report writer's duty to copy each `carry_stages` stage row unchanged is not stated here — it is generated into that writer's own authoring contract from the same record, with this run's stage numbers in it (`okstra_ctl.report_synthesis_packet.ReportSynthesisPacket._carry_instructions`). After plan-item seeding, run `okstra incremental-carry --run-manifest <current-run-manifest> --cur-narrative <reportNarrativePath> --state ... --out-state ...` against that record. The helper rejects a changed or missing carried stage and copies prior `P-Step-*` / `P-Prep-*` verdicts for `carry_stages`, plus unchanged `P-Val-*` / `P-Req-*` / `P-Rb-*` rows whose extract `contentHash` still matches. It rewrites `dispatchQueue` and the sibling `plan-items-*.json` so the next prompt does not re-score a carried checklist row. Overlap, omissions, and canonical conflicts return `CarryError`. On that error, discard the partial state and run full re-verification.
|
|
90
90
|
{{INCLUDE:_coverage-critic.md}}
|
|
91
91
|
- Non-goals:
|
|
92
92
|
- code-level micro-optimization unless it changes the implementation approach
|
|
@@ -115,8 +115,8 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
115
115
|
- **`user-bypass` — the stage that is honestly none of the three.** Some stages have no failing-before state to write and no category that describes them (measured 2026-09-10: a stage whose product change was already committed and conformance-proved under a previous run of the same stage, so the only truthful reason was "this stage reconciles that stage's QA declaration"). Do **not** file the closest of the three; that makes the plan misdescribe itself and S10e passes on a reason that is not true. Declare `tddExemption: user-bypass — <the user's own words>` and stop: the value holds only while `<task-root>/qa/tdd-bypass.json` records the user's grant for that stage number. **You cannot write that record.** Ask the user, in your report's clarification row or directly, to re-run prepare with `--tdd-bypass "<stage>:<reason>"`; their reason is stored verbatim and the record shows the stage as bypassed by the user rather than as one of the three canned categories. **Enforced (S10e):** `collect_data_validation_errors` takes the granted stage numbers from `okstra_ctl.tdd_bypass.granted_stages`; a stage naming the token with no grant fails exactly as an arbitrary reason does, and the failure message carries the flag that produces a passing value.
|
|
116
116
|
- `stageMap[].dependsOn` must form a DAG (no self-dependency, no unknown stage, no cycle), each row's `stepCount` must equal its stage's actual `stepwiseExecution` row count, and two `(none)`-dependency stages must not name the same file in their `exitContract` — they run as concurrent implementation runs in separate worktrees. **Enforced (S8/S4/S9):** same function.
|
|
117
117
|
- Legacy candidate-comparison-only deliverable:
|
|
118
|
-
- The report writer records the plan body in
|
|
119
|
-
- **
|
|
118
|
+
- The report writer records the plan body under `implementationPlanning` in the input at the run manifest's `reportNarrativePath`, using its declared `reportAuthoringFormat`. `json-v1` uses exact JSON schema keys and native values, with ordinary Markdown allowed inside description strings. An absent field retains the `markdown-v1` line grammar. Report assembly adds machine-owned `designPreparation`, `designSurfaceCoverage`, and `planBodyVerification`, then validates the completed `data.json` against the frozen final-report schema.
|
|
119
|
+
- **Legacy Markdown field labels under `Implementation Planning`:** `Coverage Summary`, `Cross Project Dependencies`, `Decision Drafts`, `Dependency Migration Risk`, `Direction Invalidation`, `Direction Realization`, `Incremental Decision`, `Option Candidates`, `Outcome`, `Planning Contract`, `Recommended Option`, `Requirement Coverage`, `Rollback Strategy`, `Routing`, `Selected Direction Ref`, `Skipped ADR Candidates`, `Stage Map`, `Stages`, `Stepwise Execution`, `Supersession Ledger`, `Tradeoff Matrix`, `User Narrative`, `Validation Checklist`, `Variation Point Analysis`. For `json-v1`, use the exact keys in the synthesis packet's writer-owned schema instead, such as `implementationPlanning.requirementCoverage`. The `## 5.5.<i>` headings, the `step | action | ...` tables, and the `Slice value:` / `Test case (...):` lines described below are the shape of the **rendered report a reader sees**. JSON carries that content as structured values; only `markdown-v1` uses `- **Field**` / `- Item <N>` / `> value` rows. `designPreparation` and `planBodyVerification` belong to report assembly and are rejected in either format.
|
|
120
120
|
- Legacy candidate-comparison requires at least two implementation options. **Each option must include**:
|
|
121
121
|
- **File Structure**: an explicit list of files to create / modify / delete with each file's responsibility (one-line each). Use the form `Create: path — responsibility` / `Modify: path:line-range — change summary` / `Delete: path — reason`. Write every `path` in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...` / a trailing `/…`); an abbreviated path does not resolve and is rejected by plan-body verification as a kind-b path mismatch.
|
|
122
122
|
- **Two-tier change description.** Each `fileStructure` row carries `summary` **and** optional `details`, and they are not interchangeable:
|
|
@@ -208,7 +208,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
208
208
|
- Selected-direction plans omit `implementation-option:` because `selectedDirectionRef` already fixes the direction; the legacy-only selector rule is owned by the legacy deliverable section above.
|
|
209
209
|
- **the frontmatter `approved: false` line is rendered unconditionally; if the plan-body verification gate (§5.5.9) returns `blocked-by-disagreement` or `aborted-non-result`, the writer MUST keep `approved: false` and the validator refuses any report that ships with `approved: true` under such a gate result.**
|
|
210
210
|
- every ambiguity flagged during pre-planning that the user must resolve before approval registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (the unified table is the single home for these — the "no separate `Open Questions` block" rule is in the shared `_common-contract.md` clarification policy)
|
|
211
|
-
- **Exact plan-item queue (BLOCKING).** Run `okstra plan-items prepare --narrative <
|
|
211
|
+
- **Exact plan-item queue (BLOCKING).** Run `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, place `okstra plan-items prompt --run-manifest <run-manifest>` output verbatim in the verifier prompt, then run `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. Python resolves the one convergence-owned state path from that run identity. Do not freely summarise, select, omit, reorder, or renumber the queue. Prompt headings use the compact subject and include the lossless payload. For every item, ask:
|
|
212
212
|
|
|
213
213
|
```text
|
|
214
214
|
What concrete false-positive input, failure ordering, or omitted dependency
|
|
@@ -284,7 +284,7 @@ Lead's responsibilities in this sub-step (in order):
|
|
|
284
284
|
|
|
285
285
|
For a new `implementation-planning` run, the fixed order is initial verification → one planner self-fix → targeted re-verification → lead decision or immediate user confirmation. The initial verification is round 1 and the targeted re-verification is round 2. A second automatic self-fix is a contract violation. When `okstra plan-items prepare` reports `"gating": false` (one-stage `no-design-inputs` plan), skip the self-fix loop and the sweep batch: extraction and round 1 still run, then go to the user gate. Two-or-more stages, a PREP item, or non-empty `designPreparation.items` keep `gating: true` and the full order.
|
|
286
286
|
|
|
287
|
-
1. Build the queue with `okstra plan-items prepare --narrative <
|
|
287
|
+
1. Build the queue with `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, place the output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then run `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. Python resolves the one convergence-owned state path from that run identity. The lead MUST NOT summarise, select, omit, reorder, or renumber the queue. Each prompt uses the compact subject plus the lossless payload, and asks every item:
|
|
288
288
|
|
|
289
289
|
```text
|
|
290
290
|
What concrete false-positive input, failure ordering, or omitted dependency
|