okstra 0.228.2 → 0.230.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +179 -13
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +16 -21
  12. package/package.json +1 -2
  13. package/runtime/BUILD.json +2 -2
  14. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  15. package/runtime/bin/okstra-provider-exec.py +53 -4
  16. package/runtime/prompts/duties/code-reviewer.json +5 -2
  17. package/runtime/prompts/launch.template.md +5 -5
  18. package/runtime/prompts/lead/convergence.md +4 -4
  19. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  20. package/runtime/prompts/lead/phase-routing.md +1 -1
  21. package/runtime/prompts/lead/report-writer.md +3 -3
  22. package/runtime/prompts/lead/team-contract.md +3 -3
  23. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  24. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  25. package/runtime/python/okstra_ctl/cmux.py +4 -2
  26. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  27. package/runtime/python/okstra_ctl/code_review_coverage.py +18 -5
  28. package/runtime/python/okstra_ctl/code_review_scope.py +11 -7
  29. package/runtime/python/okstra_ctl/code_review_target.py +79 -25
  30. package/runtime/python/okstra_ctl/conformance.py +61 -0
  31. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  32. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  33. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  34. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  35. package/runtime/python/okstra_ctl/execution_mutation_audit.py +100 -2
  36. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  37. package/runtime/python/okstra_ctl/ids.py +1 -41
  38. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  39. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  40. package/runtime/python/okstra_ctl/locks.py +28 -1
  41. package/runtime/python/okstra_ctl/model_io/renderers.py +17 -1
  42. package/runtime/python/okstra_ctl/paths.py +84 -31
  43. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  44. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  45. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  46. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  47. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  48. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  50. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  51. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  53. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  55. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  57. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  58. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  59. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  62. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  63. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  66. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  67. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  68. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  69. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  70. package/runtime/python/okstra_ctl/process_group.py +26 -3
  71. package/runtime/python/okstra_ctl/qa_commands.py +7 -2
  72. package/runtime/python/okstra_ctl/qa_procedures.py +60 -17
  73. package/runtime/python/okstra_ctl/recap.py +1 -2
  74. package/runtime/python/okstra_ctl/render.py +10 -2
  75. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  76. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  77. package/runtime/python/okstra_ctl/run.py +24 -20
  78. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  79. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  80. package/runtime/python/okstra_ctl/verification_conformance.py +182 -0
  81. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  82. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  83. package/runtime/python/okstra_ctl/verification_generation.py +248 -0
  84. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  85. package/runtime/python/okstra_ctl/verification_input_types.py +23 -2
  86. package/runtime/python/okstra_ctl/verification_inputs.py +161 -23
  87. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  88. package/runtime/python/okstra_ctl/verification_target.py +20 -5
  89. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  90. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  91. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  92. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  93. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  94. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  95. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  96. package/runtime/skills/okstra-code-review/SKILL.md +84 -48
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +10 -4
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +7 -4
  99. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  100. package/runtime/skills/okstra-run/SKILL.md +6 -6
  101. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  102. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  103. package/runtime/validators/validate-run.py +118 -52
  104. package/docs/cli.md +0 -1060
  105. package/docs/container.md +0 -100
  106. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  107. package/docs/performance-improvement-plan-v2.md +0 -369
  108. package/runtime/python/okstra_ctl/container.py +0 -702
  109. package/runtime/python/okstra_ctl/rollup.py +0 -241
  110. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  111. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  112. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  113. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  114. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  115. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  116. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  117. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  118. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  119. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  120. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  121. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  122. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  123. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  124. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -33,7 +33,7 @@ are collected and convergence finished. Phase 1-5 do not need it.
33
33
  - **Pure code changes** (no persisted state, no infra mutation): a reachable revert SHA is sufficient. Record the exact `git revert <SHA>` command that would undo the change, and confirm `git rev-parse <SHA>` resolves.
34
34
  - **Feature-flag-gated changes**: prefer confirming the off-switch path was exercised in this run's validation evidence (i.e. one of the validation commands ran with the flag off and succeeded). If the off-path was not exercised here, record the row as `advisory — human-run` rather than treating it as a blocking requirement.
35
35
  - **Schema migrations, config-format changes, or any change with persisted state**: record the exact rollback command and, when the migration tool offers a dry-run mode (`--dry-run`, `--plan`, equivalent), its captured exit code / stdout. The rollback itself is a **human-run operation**, not an okstra worker or verifier step — so an unavailable dry-run is documented as such (advisory) and does NOT block the run, does NOT produce a `contract-violated` outcome, and does NOT route back to `implementation-planning`. The deliverable here is recording the revert path clearly enough that a human can act on it.
36
- - **Manual user test draft**: when this run produces a user-observable change (UI / API / CLI / artifact), write `target / environment / steps / expected result` per change into §5.7.9 (data field `implementation.manualUserTest`, `applicable=true` with `items`). Treat effective `manual-user-test` PREP content only as a seed: reconcile it with the approved plan's `Acceptance:` and this run's actual diff before writing the final steps. Environment line: if the project has a `docker-compose.yml`, use `/okstra-container-build` (which runs `okstra container up <task-id>`) then connect to the published port; otherwise the project's run command (e.g. `npm start`). When there is no user-observable change, set `applicable=false` and give a one-line `exemptionReason` instead of items. These are the steps a human (or `final-verification`) re-runs by hand, NOT the automated validation commands in `Validation evidence`; planning PREP is never a second final-verification manual-test source.
36
+ - **Manual user test draft**: when this run produces a user-observable change (UI / API / CLI / artifact), write `target / environment / steps / expected result` per change into §5.7.9 (data field `implementation.manualUserTest`, `applicable=true` with `items`). Treat effective `manual-user-test` PREP content only as a seed: reconcile it with the approved plan's `Acceptance:` and this run's actual diff before writing the final steps. Environment line: use the project's documented run command (e.g. `npm start`). When there is no user-observable change, set `applicable=false` and give a one-line `exemptionReason` instead of items. These are the steps a human (or `final-verification`) re-runs by hand, NOT the automated validation commands in `Validation evidence`; planning PREP is never a second final-verification manual-test source.
37
37
  - **Design preparation handoff**: `implementation.manualUserTest` remains the only manual-test handoff to final-verification. For each effective non-`manual-user-test` item whose `reviewAt.phase` is `final-verification` and whose question remains unresolved after inspecting the actual diff, add one common `missingInformation` row. Set `source` to `design-prep:<PREP-ID>:<assessment-fingerprint>`, put `ifStillOpen` and the unresolved question in `item`, and put the guardrails plus risk in `risk`. Do not introduce an implementation-only PREP schema.
38
38
  - **External QA advisory handoff:** for every external Tier 3 result that did
39
39
  not PASS, preserve the exact command and observed result in validation
@@ -118,7 +118,7 @@ Changing a test's expected value is allowed here when the finding shows the orac
118
118
  - **A run that ends with no verifier result still closes.** When the stage ends before any verifier returned a verdict — the executor stopped without a change and the user chose not to verify, or every dispatched verifier ended without a result — append the `failed` row as above, record each roster verifier `not-run` with its reason (`okstra worker-state transition --team-state <path> --worker <worker-id> --status not-run --reason <text>`; a worker the dispatch skipped already carries one), and write the convergence state with `okstra convergence skip --run-manifest <path> --reason <text>` before dispatching the report writer. Without that state the report-writer packet refuses with `convergence … required source is missing`. The command refuses while any analyser, verifier, or critic attempt returned a result or is still running; such a run converges normally. In the report, write each verifier's `verifierResults[]` row as `verdict: not-run`, and state the reason under `Stage sidecar evidence` as `withheld`.
119
119
  - On a non-`FAIL` verdict, for this run's single stage: save the executor's `### Stage Carry Evidence` JSON (after a passing lead minor fix, with the head, files, and note that §"Lead minor fix" adds; after a correction round, the last round's executor block) to a file under this run's `state/`, then run `okstra stage-done <impl-task-key> --stage <N> --carry <that file> --report <this run's final-report path>`. It writes the sidecar to the flat `runs/implementation/carry/stage-<N>.json` (the readers glob `carry/stage-*.json`: `okstra_ctl.stage_map`, `okstra_ctl.consumers.backfill_done_from_carry`, and validate-run's `RunRef.carry`), refuses to replace another head's sidecar of a stage that was never settled, and for a stage reopened after a `done` row (see "Reopening a settled stage" below) moves the previous sidecar unchanged to `carry/superseded/stage-<N>-from-<task-type>-<seq>.json` first. Name the `carryPath` and any `supersededCarryPath` it prints in `Stage sidecar evidence`. A reopened stage whose run ends `FAIL` writes nothing and leaves the old file where it is.
120
120
  - The same `okstra stage-done` call appends the `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` with `completed_at`, `carry_path`, `report_path` (relative to the report's run directory) and the carry's head, through `append_consumer` — so the consumers lock applies and this stage's worktree-registry occupancy is released. Never call `append_consumer` from python. `report_path` lets `final-verification` cite each stage's originating report when assembling its Source Implementation Report list.
121
- - **Automatic stage worktree cleanup:** after the report passes finalization, `report-finalize` reclaims this completed stage's clean worktree. It compares the report's final commit with the completion ledger and branch tip, preserves active or unfinished stages and dirty or nested worktrees, and keeps the branch and registry base for dependency rebases and later re-entry. Never remove the directory by hand before finalization. A later implementation or final-verification entry restores it from the preserved branch. After finalization, use the main project root or absolute artifact paths: this run's stage cwd may no longer exist. Enforcement: `report_finalize._teardown_stage_worktrees`, `stage_targets.teardown_completed_stage_worktrees`, and the cleanup/restoration tests in `tests/worktree/test_stage_rebase.py`.
121
+ - **Automatic stage worktree cleanup:** after the report passes finalization, `report-finalize` reclaims this completed stage's clean worktree. It compares the report's final commit with the completion ledger and branch tip, preserves active or unfinished stages and dirty or nested worktrees, and keeps the branch and registry base for dependency rebases and later re-entry. Never remove the directory by hand before finalization. A later implementation or final-verification entry restores it from the preserved branch. After finalization, use the main project root or absolute artifact paths: this run's stage cwd may no longer exist. Enforcement: `report_finalize._teardown_stage_worktrees`, `stage_targets.teardown_completed_stage_worktrees`, and the cleanup/restoration tests in the retired Python suite.
122
122
  - **Reopening a settled stage.** Appending a `status:"failed"` row after a `done` one withdraws that stage: `--stage N` accepts it again, its dependents stop resolving a base from the withdrawn head, and whole-task final-verification blocks until it is settled again. Write it with `okstra stage-reopen <task-key> --stage <N> --reason "<why>" [--evidence <report>]`, which records the reason and the report that found the defect, and re-run the stage rather than repairing the tree outside okstra — a stage reverted outside the ledger leaves the recorded `head_commit` and the carry sidecar naming a tree that no longer exists, and the next stage branches from it.
123
123
  - The verifier round, Phase 5.5 convergence, and this Phase 6 report run **once per run** over this stage's diff — NOT per step.
124
124
  - Record this stage's new contents in the final report's `Stage sidecar evidence` deliverable section: the sidecar by path with its one-line summary, and the new consumers row quoted by itself.
@@ -11,7 +11,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
11
11
 
12
12
  Follow the `**Verification inputs:**` declaration-source rule when that header is present. References to project `qaCommands` in this sidecar mean the baseline selected by that rule. The legacy lookup uses the existing plan and project baseline only where no frozen declaration replaces them.
13
13
 
14
- - **Moving dependency bases:** never run `git merge <predecessor>` or merge an old origin branch into this stage to update its base. Runtime preparation rebases downstream stages in dependency order through `okstra_ctl.stage_rebase`; a predecessor moving during execution requires stopping and re-entering preparation after the current stage claim is released. Do not rewrite another active stage or repair registry/ledger SHAs by hand. Enforcement of preparation ordering and conflict recovery is covered by `tests/worktree/test_stage_rebase.py`.
14
+ - **Moving dependency bases:** never run `git merge <predecessor>` or merge an old origin branch into this stage to update its base. Runtime preparation rebases downstream stages in dependency order through `okstra_ctl.stage_rebase`; a predecessor moving during execution requires stopping and re-entering preparation after the current stage claim is released. Do not rewrite another active stage or repair registry/ledger SHAs by hand. Enforcement of preparation ordering and conflict recovery is covered by the former Python suite; that regression check is now retired.
15
15
  - The `Executor` (bound in `implementation.md` thin core) is the **only worker permitted to mutate project files**. All other workers run read-only. A `runner=native-session` executor uses the selected host adapter's native edit and command primitives. A `runner=cli-wrapper` executor mutates files inside its provider CLI's auto-edit mode. The safety rules in this sidecar apply identically to both runners.
16
16
  - When the thin core's Task worktree block resolves status to `created` or `reused`, the Executor MUST run every Edit / Write / build / test / commit command with the worktree path as cwd. Treat it as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. Do NOT `cd` out of the worktree to reach files. If a file outside the worktree is genuinely needed, treat it as a planning gap: record it in `Out-of-plan edits` and continue.
17
17
  - **How to set the working directory**: every command and native edit MUST target `{{EXECUTOR_WORKTREE_PATH}}`, never the lead session's original project directory. The selected runtime adapter owns the exact native command syntax. Provider CLI wrappers inject the worktree at the CLI layer. For tools that accept an explicit working-directory flag (`git -C <path>`, `cargo --manifest-path`, `pytest --rootdir`), prefer that form.
@@ -58,7 +58,7 @@ Launch every Tier 1 command through the worktree lock:
58
58
  okstra worktree-lock --worktree <target.cwd> --command '<target.command>'
59
59
  ```
60
60
 
61
- The verifiers of a stage share one worktree and run at the same time, and each re-runs every Tier 1 command. A Tier 1 command that starts servers on fixed ports (a dev server on 3000 plus a fixture API on 8899 behind one `playwright test` line, fontsninja-v3-site dev-11126 stage 1) collides with the same command from another verifier: each kills or attaches to the other's servers, and the exit codes stop describing the code. The lock is keyed by the worktree, so each verifier still runs the command itself, only one at a time. The wrapper is the launcher, not the command: record the declared `target.command` as the command line, and the wrapper's exit code and stdout/stderr tail as that command's — the wrapper passes both through unchanged and adds only stderr lines prefixed `okstra worktree-lock:`. A `waiting` notice means another verifier held the lock; a `running unlocked` warning means the lock file could not be created, so record that warning beside the result. This is a guideline: nothing checks the command log for the launcher. The lock behaviour (no overlap on one worktree, no blocking across worktrees, output and exit-code pass-through, lock file outside the worktree) is covered by `tests/worktree/test_worktree_exec_lock.py`.
61
+ The verifiers of a stage share one worktree and run at the same time, and each re-runs every Tier 1 command. A Tier 1 command that starts servers on fixed ports (a dev server on 3000 plus a fixture API on 8899 behind one `playwright test` line, fontsninja-v3-site dev-11126 stage 1) collides with the same command from another verifier: each kills or attaches to the other's servers, and the exit codes stop describing the code. The lock is keyed by the worktree, so each verifier still runs the command itself, only one at a time. The wrapper is the launcher, not the command: record the declared `target.command` as the command line, and the wrapper's exit code and stdout/stderr tail as that command's — the wrapper passes both through unchanged and adds only stderr lines prefixed `okstra worktree-lock:`. A `waiting` notice means another verifier held the lock; a `running unlocked` warning means the lock file could not be created, so record that warning beside the result. This is a guideline: nothing checks the command log for the launcher. The lock behaviour (no overlap on one worktree, no blocking across worktrees, output and exit-code pass-through, lock file outside the worktree) is covered by the former Python suite; that regression check is now retired.
62
62
 
63
63
  ### Stage QA owner
64
64
 
@@ -85,9 +85,9 @@ Enforcement: `scripts/okstra_ctl/conformance.py` (`decide_conformance_gate`)
85
85
  performs the core advisory classification/reduction;
86
86
  `validators/validate-run.py` (`_validate_conformance`) routes that status to
87
87
  warnings instead of failures; and
88
- `tests/contract/test_okstra_ctl_conformance.py` (`test_external_non_pass_is_advisory`),
89
- `tests/contract/test_validate_run_conformance.py` (`test_external_non_pass_returns_warning_not_failure`),
90
- and `tests/contract/test_final_report_contracts.py` (`test_external_qa_advisory_renders_without_downgrading_accepted_verdict`)
88
+ the retired Python suite (`test_external_non_pass_is_advisory`),
89
+ the retired Python suite (`test_external_non_pass_returns_warning_not_failure`),
90
+ and the retired Python suite (`test_external_qa_advisory_renders_without_downgrading_accepted_verdict`)
91
91
  lock the core, gate, and accepted-report behavior respectively.
92
92
 
93
93
  An `io`-only non-PASS remains BLOCKING. Manifest/schema/source-mutation defects
@@ -52,7 +52,7 @@ taskType: "{{FM_TASK_TYPE}}"
52
52
 
53
53
  > The executor MUST NOT modify items listed here, even when an edit looks "trivial" or "while I'm in this file". Excluded items that block plan execution are reported back as a recommended follow-up task and the run halts for re-planning rather than silently expanding scope. This section is enforced together with `Forbidden In This Run` below.
54
54
 
55
- **Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
55
+ **Enforced (delivery only):** the retired Python suite pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
56
56
 
57
57
  **Enforced (declared edits only):** `_validate_out_of_plan_edits_are_real` in `validators/validate-run.py` fails an `Out-of-plan edits` row naming a file that is absent from `diffSummary`. The other direction — a file changed outside the approved plan and never declared — needs the plan's own file list resolved through `approvedPlanReference.planFile`, and is not built.
58
58
 
@@ -140,7 +140,7 @@ frozen scalar fields. Quoted strings preserve command and procedure characters.
140
140
  the read boundary. Snapshot references
141
141
  are not command-execution evidence; stage scope, checklist timing and independent
142
142
  QA ownership remain in force. This is a worker guideline, not an execution-log
143
- validator. `tests/contract/test_docs_runtime_contract.py::test_qa_phase_sources_follow_frozen_input_headers`
143
+ validator. the retired Python suite
144
144
  checks instruction/spec alignment, and the header and recovery tests cover the
145
145
  generated reference contract.
146
146
 
@@ -186,9 +186,9 @@ Stage selection is `auto` or a number. If `--stage` comes from another task-type
186
186
 
187
187
  The stage worktree base is decided by dependency shape. An independent stage uses the task-key worktree HEAD fixed at first implementation entry as its anchor, and a single-dependency stage branches from the predecessor stage's done `head_commit`. A multi-dependency stage branches from a commit holding exactly its predecessors: the predecessor commit that already contains the others, or else an integration branch merging them (`<work-category-namespace>/<task-id-segment>-g<n1>-<n2>`). okstra creates that branch itself, so a predecessor that has not been merged into the task branch no longer blocks the stage; release-handoff later reuses the same branch as that stage's PR base.
188
188
 
189
- When a predecessor advances, implementation entry synchronizes existing completed stage branches in dependency order through `okstra_ctl.stage_rebase.synchronize_stage_stack`. Each downstream stage is rebased with `git rebase --onto <new-base> <recorded-old-base>`; merging a moving predecessor into that stage is not an update strategy. Re-entering an unfinished stage also rebases its existing worktree when the computed base changes. Old heads are preserved under `refs/okstra/rebase-backups/`, registry bases and completion records are updated, and previous verification no longer qualifies. Conflicts abort the current rebase and stop the chain; active runs and dirty worktrees are not rewritten. A completed stage whose predecessor was reopened, and so has no done row, is left unchanged; the first synchronization after that predecessor is done again rebases it. Tests: `tests/worktree/test_stage_rebase.py`.
189
+ When a predecessor advances, implementation entry synchronizes existing completed stage branches in dependency order through `okstra_ctl.stage_rebase.synchronize_stage_stack`. Each downstream stage is rebased with `git rebase --onto <new-base> <recorded-old-base>`; merging a moving predecessor into that stage is not an update strategy. Re-entering an unfinished stage also rebases its existing worktree when the computed base changes. Old heads are preserved under `refs/okstra/rebase-backups/`, registry bases and completion records are updated, and previous verification no longer qualifies. Conflicts abort the current rebase and stop the chain; active runs and dirty worktrees are not rewritten. A completed stage whose predecessor was reopened, and so has no done row, is left unchanged; the first synchronization after that predecessor is done again rebases it. Tests: the retired Python suite.
190
190
 
191
- Successful implementation report finalization automatically removes that stage's clean worktree after its `done` record is persisted. The report's last commit, the completion ledger, and the current branch tip must agree for cleanup (`stage_integrate.reclaim_completed_stage`). Failed, active, dirty, nested, or moved stages are preserved with a reason in the finalization step result. Cleanup retains the branch and registry base; implementation re-entry and final-verification restore the worktree from that branch. The task worktree and other stages are outside this scoped cleanup. Tests: `tests/worktree/test_stage_rebase.py` and `tests/report/test_report_finalize.py`.
191
+ Successful implementation report finalization automatically removes that stage's clean worktree after its `done` record is persisted. The report's last commit, the completion ledger, and the current branch tip must agree for cleanup (`stage_integrate.reclaim_completed_stage`). Failed, active, dirty, nested, or moved stages are preserved with a reason in the finalization step result. Cleanup retains the branch and registry base; implementation re-entry and final-verification restore the worktree from that branch. The task worktree and other stages are outside this scoped cleanup. Tests: the retired Python suite and the retired Python suite.
192
192
 
193
193
  ## 6. Deliverables
194
194
 
@@ -255,4 +255,4 @@ This phase does not declare final acceptance. It says only ready for final-verif
255
255
  |---|---|---|
256
256
  | I-1 | An empty independent rerun record fails validation. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_verifier_reran_independently` |
257
257
  | I-2 | A verifier cannot report a discrepancy with a PASS verdict. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_verifier_discrepancy_is_not_passed` |
258
- | I-3 | Frozen legacy instruction pointers resolve within the selected installation without rewriting the frozen profile. | `scripts/okstra_ctl/phases/implementation/tests/test_assets.py::test_frozen_sidecar_reference_reads_the_owned_installation` |
258
+ | I-3 | Frozen legacy instruction pointers resolve within the selected installation without rewriting the frozen profile. | unenforced |
@@ -8,8 +8,8 @@ This directory owns candidate evaluation, vote completion, comparison projection
8
8
  |---|---|---|
9
9
  | IOS-1 | Candidate scores, coverage, votes and ranking are recomputed | `scripts/okstra_ctl/phases/implementation_option_selection/validation.py::validate_implementation_option_selection` |
10
10
  | IOS-2 | Blocked facts retain their user decision or technical evidence channel | `scripts/okstra_ctl/phases/implementation_option_selection/validation.py::validate_blocked_answer_channel` |
11
- | IOS-3 | A valid candidate needs two `feasible` votes, or the single vote when the user selected one designer | `scripts/okstra_ctl/phases/implementation_option_selection/validation.py::required_feasible_votes`; `scripts/okstra_ctl/phases/implementation_option_selection/tests/test_implementation_options.py::test_a_single_designer_vote_validates_its_candidate` |
12
- | IOS-4 | Candidate fingerprints deduplicate equivalent mechanisms | `scripts/okstra_ctl/phases/implementation_option_selection/tests/test_implementation_options.py::test_duplicate_candidates_share_a_fingerprint` |
11
+ | IOS-3 | A valid candidate needs two `feasible` votes, or the single vote when the user selected one designer | `scripts/okstra_ctl/phases/implementation_option_selection/validation.py::required_feasible_votes` |
12
+ | IOS-4 | Candidate fingerprints deduplicate equivalent mechanisms | unenforced |
13
13
 
14
14
  Report schemas remain in `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json`, under `implementationOptionSelection`. Next-phase decisions belong to `prompts/lead/phase-routing.md`.
15
15
 
@@ -368,7 +368,7 @@ assignment. Keep the selected critic's existing model assignment.
368
368
  accepts the planning critic's verification audience; materialization resolves
369
369
  the declared assignment and reports the correct critic reference when the
370
370
  invented `reverify/critic-worker` reference is used.
371
- `tests/run/test_agent_prompt_cli.py` verifies the declared critic's reservation
371
+ the retired Python suite verifies the declared critic's reservation
372
372
  and dispatch identity plus this recovery diagnostic.
373
373
  That kind, not `reverify-r<N>`, is what this round takes: the verification
374
374
  prompt contract requires the renderer signature of the queue's canonical renderer,
@@ -411,9 +411,9 @@ CLI-wrapper calls follow the planned execution surface after
411
411
  consume only `modelExecutionValue`. A missing or invalid invocation contract blocks the
412
412
  round before any host or provider process starts.
413
413
 
414
- 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`; `tests/report/test_report_assembly.py` checks that invalid coverage creates no prepared queue.
414
+ 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
415
 
416
- 1. Lead runs `okstra plan-items prepare --narrative <report-writer-narrative.md> --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 <report-writer-narrative.md> --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, pass `--state <plan-body-verification.json>` on prepare and validate-prepared. 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 `tests/run/test_plan_items.py`. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
416
+ 1. Lead runs `okstra plan-items prepare --narrative <report-writer-narrative.md> --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 <report-writer-narrative.md> --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, pass `--state <plan-body-verification.json>` on prepare and validate-prepared. 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
417
 
418
418
  **Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <report-writer-narrative.md> --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
419
 
@@ -421,12 +421,12 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
421
421
 
422
422
  **`--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
423
  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.
424
- 3. Dispatch uses the same wrapper infrastructure as finding convergence, so the `--role-slug` is the same canonical `<role>-worker` that convergence uses — not a round-specific slug. Result file path: `runs/<task-type>/worker-results/<role>-worker-plan-verify-r<N>-implementation-planning-<seq>.md` (e.g. `codex-worker-plan-verify-r1-implementation-planning-003.md`). **`<seq>` is the report's sequence** — the one in this run's `final-report-<task-type>-<seq>` filename, NOT the `workerResults` sequence the initial analysis results carry. The two are equal in most runs and diverge in some (`reports: 004` alongside `workerResults: 005` is a real case). Provenance no longer globs by either seq: it resolves the expected filenames from this run's team-state `workerDispatches[]` rows — the paths the dispatches actually recorded — and falls back to the seq glob only when no team-state is readable, saying so in its finding. The `-worker-` token is load-bearing twice over: §"Plan-body reverify prompt" requires the same anchor headers as convergence, whose `**Audit sidecar path:**` is derived by `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()` inserting `-audit-` after that token — a slug without it makes the header underivable and the helper raises. Record each `planItems[].verdicts[].worker` as the same `<role>-worker` string, because provenance compares it to this filename's prefix. **Enforced:** `tests/contract/test_reverify_dispatch_anchors.py` derives the sidecar from the documented name and re-extracts the prefix the provenance resolver uses.
424
+ 3. Dispatch uses the same wrapper infrastructure as finding convergence, so the `--role-slug` is the same canonical `<role>-worker` that convergence uses — not a round-specific slug. Result file path: `runs/<task-type>/worker-results/<role>-worker-plan-verify-r<N>-implementation-planning-<seq>.md` (e.g. `codex-worker-plan-verify-r1-implementation-planning-003.md`). **`<seq>` is the report's sequence** — the one in this run's `final-report-<task-type>-<seq>` filename, NOT the `workerResults` sequence the initial analysis results carry. The two are equal in most runs and diverge in some (`reports: 004` alongside `workerResults: 005` is a real case). Provenance no longer globs by either seq: it resolves the expected filenames from this run's team-state `workerDispatches[]` rows — the paths the dispatches actually recorded — and falls back to the seq glob only when no team-state is readable, saying so in its finding. The `-worker-` token is load-bearing twice over: §"Plan-body reverify prompt" requires the same anchor headers as convergence, whose `**Audit sidecar path:**` is derived by `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()` inserting `-audit-` after that token — a slug without it makes the header underivable and the helper raises. Record each `planItems[].verdicts[].worker` as the same `<role>-worker` string, because provenance compares it to this filename's prefix. **Enforced:** the retired Python suite derives the sidecar from the documented name and re-extracts the prefix the provenance resolver uses.
425
425
  **Verdict provenance.** Every verdict recorded in `planItems[].verdicts[]` MUST trace back to a dispatch that actually returned a result file. The whole gate — classification, self-fix eligibility, promotion, `gateBlockedBy` — is computed from these votes, so an unbacked vote lets the round be skipped while the gate still reads `passed`. **Enforced (advisory):** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_plan_body_verdict_provenance` reports any `verdicts[].worker` with no recorded reverify dispatch whose result file exists; the finding is not in the blocking allowlist, so it surfaces as an advisory rather than failing the run — record it, never dismiss it. Recording a `verification-error` for a dispatch that produced no result is the correct way to represent a failed worker — inventing an `AGREE` is a contract violation, and renaming a result file to make provenance match destroys the link the check reads.
426
426
 
427
- 4. After all dispatches return, first read `planVerification` in the `worker-dispatch`, `team await --json`, or `agent-prompt link-result --json` response. When its `status` is `completed`, the runtime has already parsed all accepted verifier results, run the plan-body contract validator, and recorded the round. Use its `gateResult`, `verification` (including advisories), and `nextDispatch`; skip the separate collect/apply/plan-verify/complete/next-dispatch calls and continue with the decisions and self-fix procedure below. `pending` means the complete prepared verifier roster has not returned. `failed` stops automatic completion and returns the error; preserve the result files and repair the named defect. `needs-lead`, or a response without this field, uses the manual procedure below. In particular, self-fix re-verification retains the lead-owned cause groups and completion metadata. **Enforced:** `phases/implementation_planning/round_completion.py` and the automatic-round and execution-boundary tests in `tests/run/test_plan_items.py`.
427
+ 4. After all dispatches return, first read `planVerification` in the `worker-dispatch`, `team await --json`, or `agent-prompt link-result --json` response. When its `status` is `completed`, the runtime has already parsed all accepted verifier results, run the plan-body contract validator, and recorded the round. Use its `gateResult`, `verification` (including advisories), and `nextDispatch`; skip the separate collect/apply/plan-verify/complete/next-dispatch calls and continue with the decisions and self-fix procedure below. `pending` means the complete prepared verifier roster has not returned. `failed` stops automatic completion and returns the error; preserve the result files and repair the named defect. `needs-lead`, or a response without this field, uses the manual procedure below. In particular, self-fix re-verification retains the lead-owned cause groups and completion metadata. **Enforced:** `phases/implementation_planning/round_completion.py` and the automatic-round and execution-boundary tests in the retired Python suite.
428
428
 
429
- A critic correction sharing the analysers' round also returns `needs-lead`; retain the original round queue and use the manual `--append` procedure. The automatic-round tests in `tests/run/test_plan_items.py` enforce this boundary.
429
+ A critic correction sharing the analysers' round also returns `needs-lead`; retain the original round queue and use the manual `--append` procedure. The automatic-round tests in the retired Python suite enforce this boundary.
430
430
 
431
431
  In the manual procedure, lead aggregates verdicts per `P-*` item across workers and classifies each:
432
432
 
@@ -437,7 +437,7 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
437
437
  - `dissent-isolated` — only one worker `DISAGREE`s, others `AGREE`. On a blocking kind (`b` / `c` / `e`, and kind `a` on `P-Var-*`) this is scored `majority-disagree` and **blocks approval**. Advisory-only `DISAGREE(d)` and `P-Rb-*` stay recorded dissent and do not block. (Distinct from finding-convergence `worker-unique`, which means the *opposite*: only one worker AGREEs.)
438
438
  - `majority-disagree` — a *majority* of analysers `DISAGREE` (majority needs ≥2 participating non-error votes; rollback-ordering `DISAGREE(d)` votes are advisory and excluded from the tally), OR any blocking-kind dissent with ≥2 participating votes (a minority `DISAGREE` is not outvoted), OR an unresolved single-vote-blocking kind fires: one reproduced `DISAGREE(a)` on any item other than a `P-Var-*` one, or one reproduced `DISAGREE(f)` on a `P-Req-*` item (see §"Single-vote-blocking kinds"). This classification **blocks approval**. A valid critic correction is scored before these blocking rules, whether or not the analysers split evenly.
439
439
  - `needs-reverify` — one of two shapes the round could not settle.
440
- - **An even split on a blocking kind.** A panel splitting evenly (1-AGREE / 1-DISAGREE, 2-2, …) needs a critic decision. An unresolved single-vote-blocking kind remains `majority-disagree`; other unresolved splits are `needs-reverify`. Do **not** re-run the original two. Dispatch `critic-worker` immediately on those items only (`okstra plan-items prepare --tie-vote ...`, then `okstra plan-items prompt ...`). The prompt carries the analyser split and no other plan items. Read the answer with `okstra plan-items collect-verdicts --items <the --tie-vote plan-items artifact> --result critic-worker=<path> --output <envelope>` — `--items` takes that artifact, whose `dispatchQueue` is the tie items, so pointing the next step at the raw result is refused against this round's full queue. Record the critic vote as `verdicts[].worker = critic-worker` with `okstra plan-items apply-verdicts --state <plan-body-verification.json> --round <N> --append --items <the --tie-vote plan-items artifact> --result critic-worker=<path>` — `--items` persists the exact partial `dispatchQueue` used by verdict validation and `complete-round`. Earlier verdicts and completed-round history outside that queue remain unchanged. If a previous version saved the critic votes but left the full queue in state, the ordinary `okstra plan-items complete-round --state <state> --run-manifest <manifest> --round <N>` automatically reads this run's canonical prepared queue. It uses that queue when all votes recorded for this round are included, preserving a wider recorded batch when a later prepared queue excludes its votes. An explicit `--items <prepared artifact>` remains available for selecting an artifact. Enforced by `plan_items_cli._round_inputs` and `tests/run/test_plan_items.py` completion coverage. Do not fabricate new-round votes for already agreed items. Without it the result is checked against the whole persisted round queue and refused for every item the critic was never given (measured 2026-09-10: a 7-item tie round refused against 44 items), and the only way through was `--verdicts`, which the CLI's own help calls a historical envelope. Critic `AGREE` / `SUPPLEMENT` settles the split to `has-dissent`, including an earlier `DISAGREE(a)` or `DISAGREE(f)` on `P-Req-*`. This decision corrects the disputed judgement before single-vote blocking is evaluated; it does not delete the original dissent. Critic `DISAGREE` on a blocking kind is `majority-disagree`. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_unresolved_tie_was_reverified` fails an in-scope item that carries an even split on a blocking kind and has neither a `critic-worker` vote nor a `blocks: approval` clarification row, `_classify_plan_item_gate` scores the tie shape and fails a settled classification the votes do not support, and `okstra_ctl.plan_items.next_dispatch` returns kind `critic-tie` for exactly these items, so the tie round is the queue the CLI hands you rather than one you assemble. **With no critic on the roster the split is a user decision, not another round.** `okstra plan-items next-dispatch --state <plan-body-verification.json> --run-manifest <current-run-manifest.json>` answers `user-decision` (not `critic-tie`) when the run's `invocationAssignments` carries no `critic/*` entry, and its `itemIds` are the tie items. For each of them do what step 8 does for a surviving `majority-disagree`: `okstra approval-decision open` with `approvalContext.classification` set to `correctness-critical` when `_is_correctness_critical` is true, or `noncritical-dissent` otherwise, plus the matching `## 1. Clarification Items` row at `Blocks=approval`. Dispatch no further verification for those items. The `Blocks=approval` row is what withholds approval until the user disposes, exactly as for any other approval row; the gate retains unresolved single-vote blockers as `majority-disagree` and folds other `needs-reverify` items into `passed-with-dissent`, so the round closes on the gate it actually scored. A tie left with neither a critic vote nor a decision row surfaces as recorded dissent plus an `advisories[]` entry, not a round-blocking failure. **Enforced:** `okstra_ctl.plan_items.critic_is_rostered` reads the roster and `next_dispatch` returns the kind; `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_unresolved_tie_was_reverified` reads a `blocks: approval` row linked to the item as the settlement and emits its advisory only when neither settlement is recorded.
440
+ - **An even split on a blocking kind.** A panel splitting evenly (1-AGREE / 1-DISAGREE, 2-2, …) needs a critic decision. An unresolved single-vote-blocking kind remains `majority-disagree`; other unresolved splits are `needs-reverify`. Do **not** re-run the original two. Dispatch `critic-worker` immediately on those items only (`okstra plan-items prepare --tie-vote ...`, then `okstra plan-items prompt ...`). The prompt carries the analyser split and no other plan items. Read the answer with `okstra plan-items collect-verdicts --items <the --tie-vote plan-items artifact> --result critic-worker=<path> --output <envelope>` — `--items` takes that artifact, whose `dispatchQueue` is the tie items, so pointing the next step at the raw result is refused against this round's full queue. Record the critic vote as `verdicts[].worker = critic-worker` with `okstra plan-items apply-verdicts --state <plan-body-verification.json> --round <N> --append --items <the --tie-vote plan-items artifact> --result critic-worker=<path>` — `--items` persists the exact partial `dispatchQueue` used by verdict validation and `complete-round`. Earlier verdicts and completed-round history outside that queue remain unchanged. If a previous version saved the critic votes but left the full queue in state, the ordinary `okstra plan-items complete-round --state <state> --run-manifest <manifest> --round <N>` automatically reads this run's canonical prepared queue. It uses that queue when all votes recorded for this round are included, preserving a wider recorded batch when a later prepared queue excludes its votes. An explicit `--items <prepared artifact>` remains available for selecting an artifact. Enforced by `plan_items_cli._round_inputs` and the retired Python suite completion coverage. Do not fabricate new-round votes for already agreed items. Without it the result is checked against the whole persisted round queue and refused for every item the critic was never given (measured 2026-09-10: a 7-item tie round refused against 44 items), and the only way through was `--verdicts`, which the CLI's own help calls a historical envelope. Critic `AGREE` / `SUPPLEMENT` settles the split to `has-dissent`, including an earlier `DISAGREE(a)` or `DISAGREE(f)` on `P-Req-*`. This decision corrects the disputed judgement before single-vote blocking is evaluated; it does not delete the original dissent. Critic `DISAGREE` on a blocking kind is `majority-disagree`. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_unresolved_tie_was_reverified` fails an in-scope item that carries an even split on a blocking kind and has neither a `critic-worker` vote nor a `blocks: approval` clarification row, `_classify_plan_item_gate` scores the tie shape and fails a settled classification the votes do not support, and `okstra_ctl.plan_items.next_dispatch` returns kind `critic-tie` for exactly these items, so the tie round is the queue the CLI hands you rather than one you assemble. **With no critic on the roster the split is a user decision, not another round.** `okstra plan-items next-dispatch --state <plan-body-verification.json> --run-manifest <current-run-manifest.json>` answers `user-decision` (not `critic-tie`) when the run's `invocationAssignments` carries no `critic/*` entry, and its `itemIds` are the tie items. For each of them do what step 8 does for a surviving `majority-disagree`: `okstra approval-decision open` with `approvalContext.classification` set to `correctness-critical` when `_is_correctness_critical` is true, or `noncritical-dissent` otherwise, plus the matching `## 1. Clarification Items` row at `Blocks=approval`. Dispatch no further verification for those items. The `Blocks=approval` row is what withholds approval until the user disposes, exactly as for any other approval row; the gate retains unresolved single-vote blockers as `majority-disagree` and folds other `needs-reverify` items into `passed-with-dissent`, so the round closes on the gate it actually scored. A tie left with neither a critic vote nor a decision row surfaces as recorded dissent plus an `advisories[]` entry, not a round-blocking failure. **Enforced:** `okstra_ctl.plan_items.critic_is_rostered` reads the roster and `next_dispatch` returns the kind; `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_unresolved_tie_was_reverified` reads a `blocks: approval` row linked to the item as the settlement and emits its advisory only when neither settlement is recorded.
441
441
  - **A lone dissent nobody cross-verified** — a single-vote-blocking kind fired but the item has **fewer than 2 participating non-error votes**, i.e. the lone dissent was never cross-verified because its peer returned `verification-error`. A single-vote-blocking kind means "one *confirmed* DISAGREE is enough"; an unconfirmed one is not, and on a `P-Var-*` item none fires at all — its kind `a` never blocks on one vote and takes a majority like `b` / `e`. This does **not** block approval — blocking on it would make a worker failure produce a stricter gate than a healthy roster, the same paradox the ≥2-vote majority rule already rules out. The item is re-dispatched in the next round (step 7); if it survives the round budget it is promoted per step 8 with a Statement that says verification never completed. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_classify_plan_item_gate` returns `needs-reverify` for this shape and `_recompute_plan_body_gate` folds it into `passed-with-dissent`.
442
442
  - `contested` only meaningful when `maxRounds > 1`; at default `maxRounds=1`, fold any unresolved item into `partial-consensus`.
443
443
  5. Gate result resolution:
@@ -492,7 +492,7 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
492
492
  - 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
493
  - **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
494
  - **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.
495
- - **Loop termination.** The convergence command owns the round count and stop reason; the lead never edits either field in the state file. Both are recorded by `okstra plan-items complete-round`, and its two self-fix flags are not interchangeable. `--self-fix-group` is a claim that this round rewrote something, so it sets `selfFixGroups` and `selfFixRoundsApplied` and **requires** `--self-fix-stop-reason` — there is no default, because the value that used to fill in (`all-resolved`) is the one value step 8 reads as "nothing was left unresolved", which then forbids promoting the items the round did leave unresolved. `--self-fix-stop-reason` on its own is how a round that rewrote nothing records that the loop stops there; it writes `selfFixStopReason` and touches neither `selfFixGroups` nor `selfFixRoundsApplied`, because `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_self_fix_grouping` requires the highest `selfFixGroups[].round` to equal `selfFixRoundsApplied` — a round number raised without a group has no value that passes. That stop-only call is refused while a planner-fixable majority `DISAGREE` remains and no self-fix rewrite is recorded, because validate-run requires at least one rewrite before such an item may be promoted; the fix is the rewrite, recorded with `--self-fix-group`. **Enforced:** `okstra_ctl.plan_items_cli._reject_unbacked_self_fix_stop` runs validate-run's `_validate_self_fix_before_clarification` before writing; `tests/run/test_plan_items.py::test_complete_round_refuses_a_stop_reason_with_no_rewrite_behind_it`. A user-directed correction does not consume the automatic self-fix limit, and a verification failure after that correction does not restart the automatic loop:
495
+ - **Loop termination.** The convergence command owns the round count and stop reason; the lead never edits either field in the state file. Both are recorded by `okstra plan-items complete-round`, and its two self-fix flags are not interchangeable. `--self-fix-group` is a claim that this round rewrote something, so it sets `selfFixGroups` and `selfFixRoundsApplied` and **requires** `--self-fix-stop-reason` — there is no default, because the value that used to fill in (`all-resolved`) is the one value step 8 reads as "nothing was left unresolved", which then forbids promoting the items the round did leave unresolved. `--self-fix-stop-reason` on its own is how a round that rewrote nothing records that the loop stops there; it writes `selfFixStopReason` and touches neither `selfFixGroups` nor `selfFixRoundsApplied`, because `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_self_fix_grouping` requires the highest `selfFixGroups[].round` to equal `selfFixRoundsApplied` — a round number raised without a group has no value that passes. That stop-only call is refused while a planner-fixable majority `DISAGREE` remains and no self-fix rewrite is recorded, because validate-run requires at least one rewrite before such an item may be promoted; the fix is the rewrite, recorded with `--self-fix-group`. **Enforced:** `okstra_ctl.plan_items_cli._reject_unbacked_self_fix_stop` runs validate-run's `_validate_self_fix_before_clarification` before writing; the retired Python suite. A user-directed correction does not consume the automatic self-fix limit, and a verification failure after that correction does not restart the automatic loop:
496
496
  - `all-resolved` — no planner-fixable `majority-disagree` item remains. Exit.
497
497
  - `no-progress` — the round resolved **zero** planner-fixable items relative to the previous round. Exit even with budget left: the same rewrite would repeat. Newly *introduced* defects count against progress, so a rewrite that trades one defect for another stops the loop rather than churning. A round that re-targets only what the previous round left unresolved is this same conclusion reached one dispatch earlier — exit on it under this reason rather than paying for the round that proves it. **Enforced (advisory):** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_detect_self_fix_recurrence` warns on that shape and names this stop reason.
498
498
  - `max-rounds-reached` — the single automatic rewrite has been used. Exit to step 8. Count distinct `selfFixGroups[].round` values; `selfFixRoundsApplied` is the last verification round number, not the rewrite count. Extra verification batches before the rewrite do not increase the self-fix budget.
@@ -712,7 +712,7 @@ their text without adding foreign items to the plan-verification queue.
712
712
 
713
713
  Enforcement: `render_review_context` in `okstra_ctl.plan_review_context` selects
714
714
  the context; `test_plan_review_context_preserves_facts_and_falls_back_for_unknown_dependencies`
715
- in `tests/run/test_plan_items.py` checks retained facts and conservative fallback.
715
+ in the retired Python suite previously checked retained facts and conservative fallback.
716
716
 
717
717
  Carrying the packet does not license re-analysis. It is there so the verifier
718
718
  can resolve a plan item back to the requirement it claims to satisfy; the
@@ -721,7 +721,7 @@ not revisit the requirements themselves.
721
721
 
722
722
  **Enforced:** only by the renderer — `_render_inputs` in
723
723
  `scripts/okstra_ctl/phases/implementation_planning/authoring.py`, asserted by
724
- `_assert_input_paths` in `tests/run/test_plan_items.py`. No dispatch check counts
724
+ `_assert_input_paths` in the retired Python suite. No dispatch check counts
725
725
  the packet line for this round: the `Primary analysis packet` count in
726
726
  `scripts/okstra_ctl/worker_prompt_contract.py` `_validate_prompt_for_plan` runs
727
727
  only for the `analysis` audience, and a plan-verify dispatch is a
@@ -911,4 +911,4 @@ An item with no recorded vote carrying a round number gets no block, and an enve
911
911
 
912
912
  The two spellings are different anchors for different artifacts: `**Prior round dissent**` is the block `prompt` puts in the prompt, `**Prior dissent**` is the line the worker puts in its result. `scripts/okstra_ctl/verdict_blocks.py` parses the result line into the verdict block when it is present and leaves it empty when it is not, so an omitted answer line is still silent — the prompt is what is now guaranteed, not the response.
913
913
 
914
- The analyser round limit is enforced by `plan_items_cli._validate_advisory_round` at verdict application and completion. It does not limit critic correction rounds or require an even split. `apply-verdicts --append` can update the critic’s current verdict in a later round while preserving analyser votes and completed round history. Normal invocation identity and result-provenance checks still apply. `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_critic_gate_class` applies valid critic corrections before analyser voting rules. `tests/run/test_plan_items.py` covers second and third critic rounds on tied and majority-dissent items; `tests/contract/test_plan_body_verification.py` covers critic correction of both agreement and disagreement.
914
+ The analyser round limit is enforced by `plan_items_cli._validate_advisory_round` at verdict application and completion. It does not limit critic correction rounds or require an even split. `apply-verdicts --append` can update the critic’s current verdict in a later round while preserving analyser votes and completed round history. Normal invocation identity and result-provenance checks still apply. `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_critic_gate_class` applies valid critic corrections before analyser voting rules. the retired Python suite covers second and third critic rounds on tied and majority-dissent items; the retired Python suite covers critic correction of both agreement and disagreement.
@@ -1677,6 +1677,9 @@ def _manifest_seq_for_report(report_path: Path, category: str) -> set[str]:
1677
1677
  배정한다(`paths.next_run_seq`). 같은 run dir 로 재실행하면 카테고리마다
1678
1678
  다른 속도로 올라가 reports 017 / state 025 같은 분기가 실제로 생긴다.
1679
1679
  매니페스트의 `runSequencesByCategory` 만이 그 분기를 한 런으로 묶는 기록이다.
1680
+ The divergence above describes runs prepared before `compute_run_paths`
1681
+ gave every category one seq; newer runs share one seq across categories,
1682
+ and this mapping still resolves the older ones.
1680
1683
  """
1681
1684
  seq = _report_run_seq(report_path)
1682
1685
  manifests_dir = report_path.parent.parent / "manifests"
@@ -2985,6 +2988,16 @@ def _validate_planning_conformance_declared(
2985
2988
  )
2986
2989
 
2987
2990
  failures.extend(stage_validation_executability_errors(ip))
2991
+ from okstra_ctl.stage_command_commits import stage_command_commit_errors_from_task_state
2992
+
2993
+ failures.extend(stage_command_commit_errors_from_task_state(data_path, data))
2994
+ failures.extend(_surface_declaration_failures(data, surface_patterns, implemented))
2995
+
2996
+
2997
+ def _surface_declaration_failures(
2998
+ data: dict, surface_patterns: object, implemented: frozenset[int],
2999
+ ) -> list[str]:
3000
+ failures: list[str] = []
2988
3001
  for conflict in exempt_stage_surface_conflicts(data, surface_patterns):
2989
3002
  if conflict["stage"] in implemented:
2990
3003
  continue
@@ -3013,6 +3026,7 @@ def _validate_planning_conformance_declared(
3013
3026
  "the wider set after the work is done, where the approved plan can "
3014
3027
  "no longer be corrected."
3015
3028
  )
3029
+ return failures
3016
3030
 
3017
3031
 
3018
3032
  def _is_activity_contract_v1_planning(run_manifest: dict) -> bool:
@@ -2,7 +2,7 @@
2
2
 
3
3
  Keep `commandOrObservation` executable when the checklist calls for a command. Put explanations and existing-helper citations in the checklist's `check` text, outside the command. Do not append prose after a semicolon. The plan-item renderer separates legacy `existing helper: <file>:<lines>` suffixes, and `verification-target` supplies the same executable command to every verifier.
4
4
 
5
- Validation commands are executable inputs: preserve their newlines, quotes, and code bodies. Use frozen dependency installation (`npm ci`, `pnpm install --frozen-lockfile`, or the package manager's equivalent). Name QA scripts with absolute task-artifact paths when a command runs from a stage worktree; `.okstra/tasks/...` relative to that worktree does not point to the project task. `stage_validation_executability_errors` enforces command restrictions at planning validation, implementation entry, and report preflight, including advisory plan-body runs.
5
+ Validation commands are executable inputs: preserve their newlines, quotes, and code bodies. Use frozen dependency installation (`npm ci`, `pnpm install --frozen-lockfile`, or the package manager's equivalent). Name QA scripts with absolute task-artifact paths when a command runs from a stage worktree; `.okstra/tasks/...` relative to that worktree does not point to the project task. `stage_validation_executability_errors` enforces command restrictions at planning validation, implementation entry, and report preflight, including advisory plan-body runs. A commit a stage-gating command names must be in that stage's worktree, which holds only the implementation anchor and the stages in its `dependsOn` closure; comparing against another branch's head fails before any edit. `stage_command_commit_errors` rejects such a row at planning validation and implementation entry.
6
6
 
7
7
  Plan for the actual worktree layout before approval. Shared documentation directories can be links to the main checkout. Choose a build command compatible with those links (for example, an installed Next.js version may provide `next build --webpack`); verify the available option rather than assuming it. Do not plan for a verifier to move links or repair its environment. Compare negative-case assertions with the brief and the script body: a requirement to cache existing assets does not establish that missing assets should be cached. Record any changed expectation in a new plan revision; preserve the earlier approved plan.
8
8
 
@@ -48,7 +48,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
48
48
  - Every stage number in the ledger is taken. This report declares every one of them — rows run `1..N` with no gap — and a new stage takes the next number after the highest one listed; numbers are never reused or reordered. A report that declares only its new stages satisfies neither rule and is refused twice over. **Enforced:** `okstra_ctl.stage_map._validate_stage_numbers` rejects the gap in every published plan it parses, so `okstra prepare` refuses the implementation run (`okstra_ctl.run._parse_stage_map_into_ctx`) and the Stage Ledger of every later run reads as `unreadable`; `validators/validate-implementation-plan-stages.py` check **S2** reports the same defect at authoring time. To drop a stage that has not started — `ready` or `blocked` in the ledger — keep its row and body in place in both `stageMap[]` and `stages[]` and set that `stageMap[]` row's `status` to `cancelled`; its number stays taken, and stage selection, whole-task final-verification, integration and release-handoff skip it. A `done` or `active` stage is never cancelled: to change finished work, keep that stage and add a correction stage numbered after the highest one. No remaining stage may depend on a cancelled one — point it at the stage that replaces it. **Enforced:** `validators/validate-implementation-plan-stages.py` check **S14** rejects a cancelled stage the ledger records `done` or `active` and a dependency on a cancelled stage.
49
49
  - The ledger answers two questions from two sources, and the block names both. `sourcePlan` is the plan the completed stages were actually built against; `latestPlan` is the plan the `stages` list came from and is therefore the numbering authority. When they differ, the completed work followed the former and the highest taken number comes from the latter.
50
50
  - A `planDivergence` entry means one of two things: the two plans disagree about a stage that is already `done` — the same number naming different work, or a completed stage the latest plan no longer declares — or the plan the completed stages were built against could not be read at all, so that comparison never ran. Both block the same way: do not pick one of the two plans yourself; register it as a `Blocks=approval` clarification row and assign no new stage number until it is resolved. Completed stages built against an *earlier* plan are not a divergence — that is the normal shape of an amended plan and the ledger folds it silently.
51
- - The block is absent ONLY on a task's first planning run. Its absence then means there is no prior plan, not that no stage is done. When the ledger could not be read, the packet names the source and reason. Continue planning to repair unambiguous dependency notation in the new report, retaining every stage number and title and every completed stage body. Record the original and corrected values with their source. Do not overwrite the prior report or select an older plan. Assign no new stage number until the corrected Stage Map validates; unresolved dependency meaning remains a blocker. The preparation behavior is covered by `tests/run/test_stage_ledger_prepare.py`; preservation of author intent remains a review guideline.
51
+ - The block is absent ONLY on a task's first planning run. Its absence then means there is no prior plan, not that no stage is done. When the ledger could not be read, the packet names the source and reason. Continue planning to repair unambiguous dependency notation in the new report, retaining every stage number and title and every completed stage body. Record the original and corrected values with their source. Do not overwrite the prior report or select an older plan. Assign no new stage number until the corrected Stage Map validates; unresolved dependency meaning remains a blocker. The preparation behavior is covered by the retired Python suite; preservation of author intent remains a review guideline.
52
52
  - **Prior Planning Run (read before re-deriving anything):** on a re-run the packet carries a `## Prior Planning Run` block with the previous planning run's clarification rows, its Stage Map one line per stage, the findings its convergence left `contested` / `worker-unique`, and the path to the report itself. It is context, not an approved plan — the previous run did not reach approval. Use it so a stage you are not changing keeps the wording it already had and a settled question is not re-opened under a new `P-*` number; where the brief, the directive, or a clarification answer disagrees with it, they win. The block is absent on a first planning run and on a clarification re-run, which receives the same rows through `## Clarification Carry-In Extract` instead. **Enforced:** `okstra_ctl.prior_planning.build_prior_planning_summary` assembles it and `okstra_ctl.analysis_packet._prior_planning_block` renders it; nothing checks that a worker read it.
53
53
  - Primary focus areas:
54
54
  - requirement gaps
@@ -272,7 +272,7 @@ Follow the conditional reading table for later rounds and validation failures.
272
272
  The command keeps the filename in the read trace used by
273
273
  `validators/validate_session_conformance.py` `_ENTRY_GUARD_READS`.
274
274
  The bounded output is checked by
275
- `tests/contract/test_contract_examples_execute.py::test_plan_body_common_read_keeps_gate_rules`.
275
+ the retired Python suite.
276
276
 
277
277
  Distinct from Phase 5.5 finding convergence:
278
278
 
@@ -293,7 +293,7 @@ For a new `implementation-planning` run, the fixed order is initial verification
293
293
 
294
294
  An `AGREE` response records the considered counterexample and exclusion reason in its note; unverified external material is `verification-error`, not `DISAGREE`.
295
295
  2. Dispatch a single plan-body reverify round to every analyser worker in the run's roster. `Report writer worker` is NOT a participant in this round.
296
- Read `planVerification` in the dispatch, await, or native result-link response. `status=completed` means the runtime has already applied the accepted results, checked the plan-body contract, and completed the round. Use its gate, advisories, and next dispatch and skip steps 3–4. `pending` waits for the remaining verifiers; `failed` stops for the returned defect; `needs-lead` retains the manual path, including self-fix cause-group recording. Enforcement: `phases/implementation_planning/round_completion.py` and automatic-round integration tests in `tests/run/test_plan_items.py`.
296
+ Read `planVerification` in the dispatch, await, or native result-link response. `status=completed` means the runtime has already applied the accepted results, checked the plan-body contract, and completed the round. Use its gate, advisories, and next dispatch and skip steps 3–4. `pending` waits for the remaining verifiers; `failed` stops for the returned defect; `needs-lead` retains the manual path, including self-fix cause-group recording. Enforcement: `phases/implementation_planning/round_completion.py` and automatic-round integration tests in the retired Python suite.
297
297
  3. Record each verifier Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker-id>=<result.md> --round <N>`. Python validates every submitted `P-*` identifier against the current convergence state and overwrites only that round's verdicts. Then resolve the gate result to one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`.
298
298
  4. After `okstra plan-verify` succeeds, run `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N>`. Python reads the current worker assignments, atomically appends the convergence-owned history, and updates its nested final projection. This state is the only plan-verification input report assembly reads.
299
299
  5. Record every *in-scope execution* `majority-disagree` decision through `okstra approval-decision`; record its plan and clarification links only on activities. Do not promote `observed` / `deferred` / `record` items, and do not append `clarificationItems[]` directly.
@@ -53,7 +53,7 @@ taskType: "{{FM_TASK_TYPE}}"
53
53
 
54
54
  > Analysers MUST NOT expand option candidates, file lists, or step plans into items listed here. If an analyser believes an excluded item must be addressed to satisfy the requirement, it is reported as a recommended follow-up task in the final report — never silently folded into a candidate option. If this section is left empty, analysers treat any change beyond what `Requirement Summary` explicitly demands as out of scope by default.
55
55
 
56
- **Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
56
+ **Enforced (delivery only):** the retired Python suite pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
57
57
 
58
58
  ## Planning Concerns
59
59
 
@@ -192,7 +192,7 @@ Phase-local tests exercise planning guidance and input selection. Shared tests r
192
192
  | ID | Guarantee | Enforcement |
193
193
  |---|---|---|
194
194
  | P-1 | Direction realization preserves the selected mechanism, boundaries, planning invariants and user constraints. | `scripts/okstra_ctl/phases/implementation_planning/validation.py::_direction_realization_errors` |
195
- | P-2 | Phase packages do not import other phases or the common run assembler. | `tests/contract/test_phase_catalog.py::test_a_phase_package_does_not_import_another_phase_or_the_assembler` |
195
+ | P-2 | Phase packages do not import other phases or the common run assembler. | unenforced |
196
196
  | P-3 | Each planned stage traces to an explicitly enumerated requirement coverage citation. | `scripts/okstra_ctl/phases/implementation_planning/validation.py::_validate_stage_has_requirement` |
197
197
  | P-4 | Requirement sources resolve through admissible provenance and match declared brief references. | `scripts/okstra_ctl/phases/implementation_planning/validation.py::_validate_requirement_provenance` |
198
198
  | P-5 | Detector snapshot evidence matches a fresh detection over the plan and rejects duplicate stage/kind rows. | `scripts/okstra_ctl/phases/implementation_planning/report.py::project_design` |
@@ -4,7 +4,7 @@
4
4
 
5
5
  | ID | Guarantee | Enforcement |
6
6
  |---|---|---|
7
- | PA-1 | Project analysis rejects analysis-target and evidence-input arguments before run artifacts are written | `scripts/okstra_ctl/phases/project_analysis/entry.py::validate_project_analysis_inputs`; `tests/run/test_analysis_prepare_inputs.py::test_project_analysis_rejects_target_and_evidence_before_context` |
7
+ | PA-1 | Project analysis rejects analysis-target and evidence-input arguments before run artifacts are written | `scripts/okstra_ctl/phases/project_analysis/entry.py::validate_project_analysis_inputs` |
8
8
  | PA-2 | Feature-index entry points stay inside the declared analysis scope | `scripts/okstra_ctl/phases/project_analysis/validation.py::validate_project_semantics` |
9
9
  | PA-3 | Interface and workflow component references name declared components when components are present | `scripts/okstra_ctl/phases/project_analysis/validation.py::_validate_component_references` |
10
10
  | PA-4 | Source-commit and evidence-input snapshots remain common analysis contracts | `validators/validate_analysis_report.py::validate_analysis_snapshot` |
@@ -30,4 +30,4 @@ The profile supplies no lifecycle destination selection rule. Common `next_phase
30
30
 
31
31
  ## Tests
32
32
 
33
- `tests/test_project_analysis_validation.py` checks declared and unknown interface/workflow component references, empty-component behavior and scoped feature entry points. Existing `tests/contract/test_validate_run_analysis.py` exercises the full common analysis validator, and `tests/run/test_analysis_prepare_inputs.py` checks rejection before preparation writes a run context. Common report rendering tests cover the phase body through the public router.
33
+ `tests/test_project_analysis_validation.py` checks declared and unknown interface/workflow component references, empty-component behavior and scoped feature entry points. Existing the retired Python suite exercises the full common analysis validator, and the retired Python suite previously checked rejection before preparation writes a run context. Common report rendering tests cover the phase body through the public router.
@@ -18,6 +18,12 @@ from .operations import (
18
18
  )
19
19
 
20
20
 
21
+ def handoff_input_path(project_root: Path, task_group: str, task_id: str) -> Path:
22
+ from okstra_ctl.paths import task_dir
23
+
24
+ return task_dir(project_root, task_group, task_id) / "release-handoff-input.md"
25
+
26
+
21
27
  def _collect_handoff_source_report_rows(
22
28
  rows: list, nums: list,
23
29
  ) -> list:
@@ -124,7 +130,6 @@ def materialize_handoff_input(
124
130
  okstra_ctl.handoff 의 SSOT 판정을 prepare 에서도 그대로 강제한다.
125
131
  반환: ctx 에 올릴 {"HANDOFF_STAGES": ...}."""
126
132
  from okstra_ctl.consumers import read_consumers
127
- from okstra_ctl.paths import task_dir
128
133
  from okstra_ctl.render import render_template_with_ctx
129
134
  from okstra_ctl.run_context import _now_task_date
130
135
 
@@ -160,8 +165,7 @@ def materialize_handoff_input(
160
165
  raise PrepareError(
161
166
  f"release-handoff input template missing: {template}.{install_hint}"
162
167
  )
163
- out = (task_dir(project_root, inp.task_group, inp.task_id)
164
- / "release-handoff-input.md")
168
+ out = handoff_input_path(project_root, inp.task_group, inp.task_id)
165
169
  out.parent.mkdir(parents=True, exist_ok=True)
166
170
  render_template_with_ctx(str(template), str(out), {
167
171
  "TASK_KEY": f"{inp.project_id}:{inp.task_group}:{inp.task_id}",
@@ -86,7 +86,7 @@ The user picks ONE release base for the whole run. Each stage's own PR base is t
86
86
 
87
87
  > The lead MUST NOT extend handoff actions into items listed here. If an excluded item should ship in this PR, edit this section before the run starts — do not silently fold it in.
88
88
 
89
- **Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
89
+ **Enforced (delivery only):** the retired Python suite pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
90
90
 
91
91
  ## Questions for Lead Drafting
92
92
 
@@ -9,9 +9,9 @@ Report shapes remain in `schemas/final-report-v2.0.schema.json` and `schemas/fin
9
9
  | ID | Guarantee | Enforcement |
10
10
  |---|---|---|
11
11
  | RH-1 | A PR carries a release-ready stage's recorded commit and dependency base | `scripts/okstra_ctl/phases/release_handoff/operations.py::pr_plan` |
12
- | RH-2 | Diverged origin branches are rejected without force-pushing | `scripts/okstra_ctl/phases/release_handoff/tests/test_handoff_pr_plan.py::test_pr_plan_refuses_a_branch_it_cannot_deliver` |
13
- | RH-3 | An actively reserved stage is not handed to the main worktree | `scripts/okstra_ctl/phases/release_handoff/tests/test_local_checkout_occupancy.py::test_an_active_stage_row_is_refused` |
14
- | RH-4 | Missing optional report fields do not prevent rendering | `scripts/okstra_ctl/phases/release_handoff/tests/test_release_handoff_optional_keys.py::test_the_shape_a_skipped_run_writes_renders_end_to_end` |
12
+ | RH-2 | Diverged origin branches are rejected without force-pushing | unenforced |
13
+ | RH-3 | An actively reserved stage is not handed to the main worktree | unenforced |
14
+ | RH-4 | Missing optional report fields do not prevent rendering | unenforced |
15
15
 
16
16
  ## Index
17
17
 
@@ -29,7 +29,7 @@ Report shapes remain in `schemas/final-report-v2.0.schema.json` and `schemas/fin
29
29
 
30
30
  `release-handoff` is the terminal phase that pushes already-committed implementation stages with a release-ready verdict, or hands them off as pull requests. **One stage is one PR.** The PR head is that stage's stack branch; the base comes from its `depends-on` — the release base for a stage with no live dependency, the predecessor's branch for a stage with one (a stacked PR), and a branch merging the predecessors for a stage with several.
31
31
 
32
- When a predecessor advances, `okstra_ctl.stage_rebase.synchronize_stage_stack` rebases downstream stages in dependency order rather than merging the predecessor into them. It records the new bases and completion commits, preserving prior heads under `refs/okstra/rebase-backups/`. Implementation entry and verification target acquisition use the same operation. PR planning stops after a stack change and requires fresh final-verification; the new completion rows invalidate earlier verification through `consumers.verified_accepted_stages`. Dirty or active stages, rewritten unproven predecessors, and rebase conflicts stop synchronization. A completed stage whose predecessor was reopened, and so has no done row, is left unchanged; the first synchronization after that predecessor is done again rebases it. The tests in `tests/worktree/test_stage_rebase.py` cover ordering, preservation, and verification invalidation. Origin divergence remains a delivery error, never a reason to merge old origin history into the rebased branch.
32
+ When a predecessor advances, `okstra_ctl.stage_rebase.synchronize_stage_stack` rebases downstream stages in dependency order rather than merging the predecessor into them. It records the new bases and completion commits, preserving prior heads under `refs/okstra/rebase-backups/`. Implementation entry and verification target acquisition use the same operation. PR planning stops after a stack change and requires fresh final-verification; the new completion rows invalidate earlier verification through `consumers.verified_accepted_stages`. Dirty or active stages, rewritten unproven predecessors, and rebase conflicts stop synchronization. A completed stage whose predecessor was reopened, and so has no done row, is left unchanged; the first synchronization after that predecessor is done again rebases it. The tests in the retired Python suite cover ordering, preservation, and verification invalidation. Origin divergence remains a delivery error, never a reason to merge old origin history into the rebased branch.
33
33
 
34
34
  Because the PRs are a stack, they must be merged in dependency order with a merge commit or a rebase-merge. A squash replaces the commits the next PR's base points at, so the stack breaks — every PR body states this, and the lead never merges.
35
35
 
@@ -26,7 +26,7 @@ Both `report_assembly.py` and `validators/validate-run.py` call this validation
26
26
 
27
27
  ## Tests
28
28
 
29
- `tests/test_technical_verification.py` covers input ownership, unsafe/unclassified sources, source preservation, exclusive snapshot creation, fact completeness, failed or missing commands, logs, sequence and symlink boundaries, full preparation and schema-v2/v3 report rendering. `tests/report/test_report_assembly.py::test_technical_assembly_requires_evidence_before_replacing_record` checks publication preserves an existing record when evidence fails.
29
+ `tests/test_technical_verification.py` covers input ownership, unsafe/unclassified sources, source preservation, exclusive snapshot creation, fact completeness, failed or missing commands, logs, sequence and symlink boundaries, full preparation and schema-v2/v3 report rendering. the retired Python suite previously checked publication preserves an existing record when evidence fails.
30
30
 
31
31
  ## Guarantees
32
32
 
@@ -78,10 +78,33 @@ def group_rss_bytes(pgid: int) -> int:
78
78
  return total_kb * 1024
79
79
 
80
80
 
81
- def kill_group(pgid: int) -> bool:
82
- """그룹에 남은 프로세스를 SIGKILL 한다. 보낼 대상이 있었으면 True."""
81
+ def live_group_members(pgid: int) -> int | None:
82
+ """Members of group `pgid` that are not zombies; None when ps fails.
83
+
84
+ Signal 0 cannot answer this: it fails with EPERM both for a zombie-only
85
+ group on macOS and for a live member running under other credentials.
86
+ """
87
+ try:
88
+ output = subprocess.run(
89
+ ["ps", "-A", "-o", "pgid=,stat="],
90
+ capture_output=True, text=True, check=True,
91
+ ).stdout
92
+ except (OSError, subprocess.CalledProcessError):
93
+ return None
94
+ return sum(
95
+ 1 for row in output.splitlines()
96
+ if (fields := row.split()) and len(fields) == 2
97
+ and fields[0] == str(pgid) and not fields[1].startswith("Z")
98
+ )
99
+
100
+
101
+ def kill_group(pgid: int, signum: int = signal.SIGKILL) -> bool:
102
+ """그룹에 남은 프로세스를 SIGKILL 한다. 보낼 대상이 있었으면 True.
103
+
104
+ `signum` sends another signal, such as the SIGTERM of an interruption.
105
+ """
83
106
  try:
84
- os.killpg(pgid, signal.SIGKILL)
107
+ os.killpg(pgid, signum)
85
108
  except ProcessLookupError:
86
109
  return False
87
110
  except PermissionError:
@@ -27,7 +27,12 @@ from typing import Iterable, Mapping
27
27
  # `test` 와 분리한다. implementation verifier / final-verification 의 DB 실제실행 게이트가
28
28
  # diff 가 DB 를 건드릴 때 이 카테고리(또는 plan validation 의 db 스텝)를 요구한다.
29
29
  ALLOWED_CATEGORIES: tuple[str, ...] = ("lint", "format", "typecheck", "test", "db-test")
30
- QA_COMMAND_EXECUTING_TASK_TYPES = ("implementation", "final-verification")
30
+ QA_VERIFIER_AUDIENCE_BY_TASK_TYPE = {
31
+ "implementation": "implementation-verifier",
32
+ "final-verification": "acceptance-verifier",
33
+ }
34
+ QA_COMMAND_EXECUTING_TASK_TYPES = tuple(QA_VERIFIER_AUDIENCE_BY_TASK_TYPE)
35
+ QA_SOURCE_DIGEST_PATTERN = re.compile(r"sha256:[0-9a-f]{64}")
31
36
  QA_RELATIVE_PATH_DESCRIPTION = (
32
37
  "non-blank relative POSIX path with at least one component after normalization, "
33
38
  "without traversal or backslashes"
@@ -286,7 +291,7 @@ def qa_metadata_errors(entry: Mapping[str, object], seen_ids: set[str]) -> list[
286
291
  errors.append("resourceKeys must be non-secret resource identifiers")
287
292
  digest = entry.get("sourceBaselineDigest")
288
293
  if digest is not None and (
289
- not isinstance(digest, str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", digest)
294
+ not isinstance(digest, str) or not QA_SOURCE_DIGEST_PATTERN.fullmatch(digest)
290
295
  ):
291
296
  errors.append("sourceBaselineDigest must be a sha256 digest")
292
297
  return errors