okstra 0.229.0 → 0.230.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +105 -16
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +11 -18
  12. package/package.json +1 -2
  13. package/runtime/BUILD.json +2 -2
  14. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  15. package/runtime/prompts/launch.template.md +5 -5
  16. package/runtime/prompts/lead/convergence.md +4 -4
  17. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  18. package/runtime/prompts/lead/phase-routing.md +1 -1
  19. package/runtime/prompts/lead/report-writer.md +3 -3
  20. package/runtime/prompts/lead/team-contract.md +3 -3
  21. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  22. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  23. package/runtime/python/okstra_ctl/cmux.py +4 -2
  24. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  25. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  26. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  27. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  28. package/runtime/python/okstra_ctl/conformance.py +30 -0
  29. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  30. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  31. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  32. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  33. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  34. package/runtime/python/okstra_ctl/ids.py +1 -41
  35. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  36. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  37. package/runtime/python/okstra_ctl/locks.py +28 -1
  38. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  39. package/runtime/python/okstra_ctl/paths.py +75 -33
  40. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  41. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  42. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  43. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  44. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  45. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  46. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  47. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  48. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  49. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  50. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  51. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  52. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  53. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  54. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  55. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  56. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  57. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  58. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  59. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  63. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  64. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  66. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  67. package/runtime/python/okstra_ctl/process_group.py +26 -3
  68. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  69. package/runtime/python/okstra_ctl/recap.py +1 -2
  70. package/runtime/python/okstra_ctl/render.py +10 -2
  71. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  72. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  73. package/runtime/python/okstra_ctl/run.py +24 -20
  74. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  75. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  76. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  77. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  78. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  79. package/runtime/python/okstra_ctl/verification_generation.py +22 -12
  80. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  81. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  82. package/runtime/python/okstra_ctl/verification_inputs.py +73 -2
  83. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  84. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  85. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  86. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  87. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  88. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  89. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  90. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  91. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  92. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  93. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  94. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  95. package/runtime/skills/okstra-run/SKILL.md +6 -6
  96. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  97. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  98. package/runtime/validators/validate-run.py +110 -19
  99. package/docs/cli.md +0 -1060
  100. package/docs/container.md +0 -100
  101. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  102. package/docs/performance-improvement-plan-v2.md +0 -369
  103. package/runtime/python/okstra_ctl/container.py +0 -702
  104. package/runtime/python/okstra_ctl/rollup.py +0 -241
  105. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  106. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  107. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  108. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  109. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  110. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  111. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  112. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  113. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  114. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  115. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  116. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  117. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  118. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  119. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -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,11 @@ 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)
31
35
  QA_SOURCE_DIGEST_PATTERN = re.compile(r"sha256:[0-9a-f]{64}")
32
36
  QA_RELATIVE_PATH_DESCRIPTION = (
33
37
  "non-blank relative POSIX path with at least one component after normalization, "
@@ -212,8 +212,7 @@ def assemble_group_recap(project_root: Path, task_group: str) -> dict:
212
212
  브리프 디렉터리가 목록과 순서를, 카탈로그(task-manifest)가 실제 phase·상태를,
213
213
  그룹 문서의 Task Memory 영역이 결론(headline·decisions·watch out·follow-ups)을
214
214
  준다. 어느 하나만으로는 틀린다 — 카탈로그는 미시작 브리프를 모르고, 메모리는
215
- 2026-09-07 이전에 끝난 task 를 모른다. 숫자 집계(CPU·에러)는 rollup 의 것이라
216
- 여기서 세지 않는다.
215
+ 2026-09-07 이전에 끝난 task 를 모른다.
217
216
  """
218
217
  context_file = group_context.group_context_file(project_root, task_group)
219
218
  text = context_file.read_text(encoding="utf-8") if context_file.is_file() else ""
@@ -17,7 +17,7 @@ session id 등) 를 덧붙여 전달한다.
17
17
 
18
18
  from __future__ import annotations
19
19
 
20
- from .phases.catalog import profile_sidecar
20
+ from .phases.catalog import INPUT_DOCUMENT_TASK_TYPES, profile_sidecar
21
21
 
22
22
  import hashlib
23
23
  import json
@@ -1405,6 +1405,14 @@ def _derive_latest_pointers(existing: dict, ctx: dict, current_report_relative:
1405
1405
  }
1406
1406
 
1407
1407
 
1408
+ def _registered_task_brief(existing: dict, ctx: dict) -> str:
1409
+ # Downstream runs carry the manifest value in as their brief, so an input
1410
+ # document prepare generated must not replace the task's requirement brief.
1411
+ if ctx.get("TASK_TYPE") in INPUT_DOCUMENT_TASK_TYPES:
1412
+ return existing.get("taskBriefPath", "")
1413
+ return ctx.get("BRIEF_RELATIVE_PATH", "")
1414
+
1415
+
1408
1416
  def render_task_manifest(manifest_path: str, ctx: dict) -> None:
1409
1417
  path = Path(manifest_path)
1410
1418
  existing = {}
@@ -1484,7 +1492,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
1484
1492
  "workStatusNote": existing.get("workStatusNote", ""),
1485
1493
  "latestWorkRecordPath": existing.get("latestWorkRecordPath", ""),
1486
1494
  "registrationSource": existing.get("registrationSource", ""),
1487
- "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
1495
+ "taskBriefPath": _registered_task_brief(existing, ctx),
1488
1496
  "recommendedWorkers": reviewers,
1489
1497
  "relatedTasks": related_tasks,
1490
1498
  "currentStatus": ctx.get("CURRENT_TASK_STATUS", ""),
@@ -1325,7 +1325,7 @@ def closeout_command(result: Mapping[str, Any]) -> dict[str, str]:
1325
1325
  }
1326
1326
  pointer = result.get("nextRecommendedPhase")
1327
1327
  if not isinstance(pointer, Mapping):
1328
- return {"command": "/okstra-inspect status", "note": "no pointer recorded"}
1328
+ return {"command": "okstra task-show <task-key>", "note": "no pointer recorded; replace <task-key> with the full task key"}
1329
1329
  status = str(pointer.get("status") or "").strip()
1330
1330
  phase = str(pointer.get("phase") or "").strip()
1331
1331
  rationale = str(pointer.get("rationale") or "").strip()
@@ -1345,14 +1345,14 @@ def closeout_command(result: Mapping[str, Any]) -> dict[str, str]:
1345
1345
  "command": "",
1346
1346
  "note": "the lifecycle ends here — say the task is finished, name any "
1347
1347
  "follow-up tasks this run registered, and do not send the user "
1348
- "to /okstra-inspect",
1348
+ "to a separate status workflow",
1349
1349
  }
1350
1350
  if status in (STATUS_BLOCKED, STATUS_PENDING) and rationale:
1351
1351
  return {
1352
1352
  "command": "",
1353
1353
  "note": "quote the rationale above and issue the command it names",
1354
1354
  }
1355
- return {"command": "/okstra-inspect status", "note": ""}
1355
+ return {"command": "okstra task-show <task-key>", "note": "replace <task-key> with the full task key"}
1356
1356
 
1357
1357
 
1358
1358
  def _next_phase_summary_lines(result: Mapping[str, Any]) -> list[str]:
@@ -15,6 +15,7 @@ from okstra_token_usage.blocks import accounting_workers
15
15
 
16
16
  from .analysis_packet import reference_source_extracts
17
17
  from .correction_round import correction_convergence_states
18
+ from .dispatch_state import UNSUCCESSFUL_WORKER_STATUSES
18
19
  from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
19
20
  from .phases.implementation_option_selection.authoring import (
20
21
  requirement_instructions as selection_requirement_instructions,
@@ -849,6 +850,10 @@ def _source_specs(
849
850
  for worker in workers:
850
851
  if not isinstance(worker, Mapping) or worker.get("workerId") == "report-writer":
851
852
  continue
853
+ # Such a worker settled no result, whatever file it left; a run closed with
854
+ # no verifier result still owes the writer a report.
855
+ if worker.get("status") in UNSUCCESSFUL_WORKER_STATUSES:
856
+ continue
852
857
  path = _string(worker.get("resultPath"))
853
858
  if path:
854
859
  worker_id = _string(worker.get("workerId")) or "unknown"
@@ -47,7 +47,7 @@ from typing import Mapping, Sequence
47
47
 
48
48
  from okstra_project import project_json_path, upsert_project_json
49
49
  from okstra_project.slug import slugify
50
- from .phases.catalog import host_rules
50
+ from .phases.catalog import INPUT_DOCUMENT_TASK_TYPES, host_rules
51
51
  from .phases.implementation_planning.entry import (
52
52
  _resolve_planning_input_path,
53
53
  _validate_planning_entry_inputs,
@@ -97,6 +97,7 @@ from .implementation_direction import (
97
97
  )
98
98
  from .qa_commands import (
99
99
  QA_COMMAND_EXECUTING_TASK_TYPES,
100
+ QA_VERIFIER_AUDIENCE_BY_TASK_TYPE,
100
101
  format_errors as _format_qa_errors,
101
102
  validate_qa_commands,
102
103
  )
@@ -442,9 +443,13 @@ def _validate_approved_plan_conformance(path: Path) -> None:
442
443
  data_path, data = loaded
443
444
  from .implementation_direction import stage_validation_executability_errors
444
445
 
445
- command_errors = stage_validation_executability_errors(
446
- data.get("implementationPlanning") or {}
447
- )
446
+ from .stage_command_commits import stage_command_commit_errors_from_task_state
447
+
448
+ planning = data.get("implementationPlanning") or {}
449
+ command_errors = [
450
+ *stage_validation_executability_errors(planning),
451
+ *stage_command_commit_errors_from_task_state(data_path, data),
452
+ ]
448
453
  if command_errors:
449
454
  raise PrepareError(
450
455
  f"approved plan command preflight failed: {data_path}\n"
@@ -453,10 +458,9 @@ def _validate_approved_plan_conformance(path: Path) -> None:
453
458
  bad = malformed_conformance_stages(data)
454
459
  if not bad:
455
460
  return
456
- planning = data.get("implementationPlanning") if isinstance(data, dict) else None
457
461
  declared_by_stage = {
458
462
  stage.get("stage"): stage.get("conformanceTests")
459
- for stage in (planning or {}).get("stages") or []
463
+ for stage in planning.get("stages") or []
460
464
  if isinstance(stage, dict)
461
465
  }
462
466
  # 한 stage 씩 고치고 다시 막히는 왕복을 피하려면 전부 나열해야 한다 —
@@ -820,7 +824,10 @@ def _published_run_seqs(run_dir: Path, task_type_segment: str) -> dict[str, str]
820
824
  매니페스트의 `runSequencesByCategory` 가 같은 런의 나머지 카테고리 seq 를
821
825
  묶는 유일한 기록이다. 재실행이 카테고리별로 다른 속도로 올라가므로
822
826
  (`paths.next_run_seq` 가 디렉터리마다 따로 스캔한다) 이 대응 없이는 "리포트
823
- 017 의 worker-results 는 몇 번인가" 에 답할 방법이 없다.
827
+ 017 의 worker-results 는 몇 번인가" 에 답할 방법이 없다. The divergence
828
+ above describes runs prepared before `compute_run_paths` gave every
829
+ category one seq; newer runs share one seq across categories, and this
830
+ mapping still resolves the older ones.
824
831
  """
825
832
  reports = run_dir / "reports"
826
833
  manifests = run_dir / "manifests"
@@ -1428,7 +1435,7 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
1428
1435
  f"got {inp.task_type}"
1429
1436
  )
1430
1437
  validate_discussion_start(project_root, inp)
1431
- if inp.task_type in ("release-handoff", "discussion"):
1438
+ if inp.task_type in INPUT_DOCUMENT_TASK_TYPES:
1432
1439
  # brief 는 entry phase 의 입력물 — release-handoff 는 검증 보고서를
1433
1440
  # 인용하는 input 문서를 prepare 가 직접 생성해 brief 자리에 채운다
1434
1441
  # (materialize_handoff_input, 이 검증 직후 실행). discussion 은 시작
@@ -1567,11 +1574,6 @@ def _validate_selected_implementation_plan(
1567
1574
  expected_task_root,
1568
1575
  "selected direction snapshot",
1569
1576
  )
1570
- brief_path = validate_task_artifact_path(
1571
- expected_task_root / "instruction-set" / "task-brief.md",
1572
- expected_task_root,
1573
- "selected direction task brief",
1574
- )
1575
1577
  except DirectionSelectionError as exc:
1576
1578
  raise PrepareError(f"selected-direction plan input is invalid: {exc}") from exc
1577
1579
 
@@ -1582,7 +1584,9 @@ def _validate_selected_implementation_plan(
1582
1584
  "selected-direction plan header.taskKey must match the implementation "
1583
1585
  f"task: expected {expected_task_key!r}, got {actual_task_key!r}"
1584
1586
  )
1585
- failures = validate_selected_direction_plan(data, brief_path, snapshot_path)
1587
+ # instruction-set/task-brief.md holds whatever brief the task's last run used
1588
+ # (a release-handoff run leaves its input there), so read this run's brief.
1589
+ failures = validate_selected_direction_plan(data, Path(inp.brief_path), snapshot_path)
1586
1590
  if failures:
1587
1591
  raise PrepareError(
1588
1592
  "selected-direction plan failed implementation entry validation:\n - "
@@ -3809,10 +3813,10 @@ def _allowed_agent_audiences(
3809
3813
  audiences.add("reverification-worker")
3810
3814
  if any(item.worker_id == "report-writer" for item in models.worker_assignments):
3811
3815
  audiences.add("report-writer")
3812
- if inp.task_type == "implementation":
3813
- audiences.update({"implementation-executor", "implementation-verifier"})
3814
- elif inp.task_type == "final-verification":
3815
- audiences.add("acceptance-verifier")
3816
+ if inp.task_type in QA_VERIFIER_AUDIENCE_BY_TASK_TYPE:
3817
+ audiences.add(QA_VERIFIER_AUDIENCE_BY_TASK_TYPE[inp.task_type])
3818
+ if inp.task_type == "implementation":
3819
+ audiences.add("implementation-executor")
3816
3820
  else:
3817
3821
  # Same map the prompt policy resolves the duty from. Allowing a
3818
3822
  # different audience here than the one the policy will ask for makes
@@ -4210,7 +4214,7 @@ def _prepare_user_authorization(inp: PrepareInputs) -> dict:
4210
4214
  "user authorization scope does not match --preselected-direction; confirm the changed scope"
4211
4215
  )
4212
4216
  for key, path in (
4213
- ("task-brief", "" if inp.task_type in ("release-handoff", "discussion") else inp.brief_path),
4217
+ ("task-brief", "" if inp.task_type in INPUT_DOCUMENT_TASK_TYPES else inp.brief_path),
4214
4218
  ("approved-plan", inp.approved_plan_path),
4215
4219
  ("clarification-response", inp.clarification_response_path),
4216
4220
  ("selected-direction", inp.selected_direction_path),
@@ -4277,7 +4281,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
4277
4281
  task_index_template = assets.task_index_template
4278
4282
  final_report_template = assets.final_report_template
4279
4283
  ctx_stage_map = _validate_prepare_inputs(project_root, inp)
4280
- if inp.task_type not in ("release-handoff", "discussion"):
4284
+ if inp.task_type not in INPUT_DOCUMENT_TASK_TYPES:
4281
4285
  _validate_task_brief_preflight(
4282
4286
  project_root,
4283
4287
  inp.brief_path,