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
@@ -26,7 +26,7 @@ This document is the operating contract and phase index. Detailed procedures liv
26
26
  | `plan-body-verification` (the absolute path in **Okstra Runtime Resources**) | Phase 6 plan-body verification sub-step (implementation-planning only) — plan-item extraction, verdict semantics, gate resolution, state schema. Read only the common procedure at that sub-step, using the bounded read below |
27
27
  | [report-writer](./report-writer.md) | Phase 6 final-report authorship, dispatch template, resume-safe dispatch, shared-graph integrity check, Phase 7 token-usage collector |
28
28
 
29
- Read-side inspection (`/okstra-inspect`) and scheduling (`/okstra-schedule-gen`) are user-invoked skills, not lead support contracts — the lead does not consult them during a run.
29
+ Scheduling (`/okstra-schedule-gen`) is a user-invoked skill, not a lead support contract — the lead does not consult it during a run.
30
30
 
31
31
  ## Quick Reference
32
32
 
@@ -46,12 +46,13 @@ Read-side inspection (`/okstra-inspect`) and scheduling (`/okstra-schedule-gen`)
46
46
 
47
47
  ## Command map
48
48
 
49
- Every `okstra` command the lead documents cite, grouped by phase, each spelled with every argument its parser requires. Replace each `<placeholder>` with the value the named artifact gives; do not guess a flag that is not listed — run `okstra <command> --help` instead. The table locates a command; the Procedure column names the section that owns when and how to run it, and that section wins where the two differ. **Enforced:** `tests/contract/test_lead_command_map.py` checks every row, and every `okstra` example in the lead documents, against the CLI's own argument parser.
49
+ Every `okstra` command the lead documents cite, grouped by phase, each spelled with every argument its parser requires. Replace each `<placeholder>` with the value the named artifact gives; do not guess a flag that is not listed — run `okstra <command> --help` instead. The table locates a command; the Procedure column names the section that owns when and how to run it, and that section wins where the two differ. **Enforced:** the retired Python suite previously checked every row, and every `okstra` example in the lead documents, against the CLI's own argument parser.
50
50
 
51
51
  ### Phase 1 — intake and re-run scope
52
52
 
53
53
  | Command | Use when | Procedure |
54
54
  |---|---|---|
55
+ | `okstra task-show <task-key>` | Inspect the task when no next-phase command can be derived | launch prompt "User closeout" |
55
56
  | `okstra model-io project-context --project-root <dir>` | Resolve the task key, task manifest, and latest run manifest; add `--task-ref <id-or-key>` for an explicit task | `context-loader` "Step 1" |
56
57
  | `okstra model-io run-input --run-manifest <path>` | Read run identity, worker roster, model assignments, and artifact paths instead of opening the run manifest | `context-loader` "Step 3" |
57
58
  | `okstra model-io active-context-input --project-root <dir> --run-manifest <path>` | Read the prior executor base ref for an incremental re-run | launch prompt "Incremental re-verification" |
@@ -217,7 +218,7 @@ This gate applies before every initial dispatch, retry, re-verification, critic,
217
218
 
218
219
  For a corrective dispatch, name every known defect in one instruction with its current value and exact replacement or required outcome. Do not spend one worker round per defect that was already visible before dispatch. For the report writer that instruction is a corrections ledger checked by `okstra agent-prompt check-corrections` before dispatch and applied without a writer round when it holds only `replace` / `remove` entries — see [report-writer](./report-writer.md) "Corrective report-writer dispatch (ledger required)".
219
220
 
220
- **Enforcement:** `tests/contract/test_agent_spawn_surface_census.py` requires this gate to remain in the lead contract and requires every worker-dispatch support contract to point back to it. Semantic correctness remains a lead-side pre-dispatch check because no generic validator can decide whether free-form task instructions accurately represent the cited project evidence.
221
+ **Enforcement:** the retired Python suite previously required this gate to remain in the lead contract and requires every worker-dispatch support contract to point back to it. Semantic correctness remains a lead-side pre-dispatch check because no generic validator can decide whether free-form task instructions accurately represent the cited project evidence.
221
222
 
222
223
  ## Lifecycle Phase Boundaries (BLOCKING)
223
224
 
@@ -260,7 +261,7 @@ Follow the launch prompt's operation-level progress guidance: name the actual pr
260
261
 
261
262
  A single okstra run frequently spans 30–120 minutes with multi-minute silent windows while workers run; without progress signals the user cannot distinguish "still working" from "hung". Lead MUST emit a single short progress line at each checkpoint below — plain user-facing text in a separate brief message (not buried inside a tool call), one line per checkpoint, format: `PROGRESS: <phase-id> <verb-phrase>`. Emit the line raw — the literal `PROGRESS:` token must begin the line. Do NOT wrap it in inline-code backticks (`` `PROGRESS: ...` ``) or a ```` ``` ```` code fence; markdown wrapping is what the post-hoc conformance validator scrapes around, and raw emit keeps the signal unambiguous.
262
263
 
263
- Record each checkpoint with `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>`, then emit the `progressLine` it prints as the user-facing line. The command resolves `leadEventsPath` from the run manifest and writes the checkpoint there — on a host whose adapter declares `sessionAccounting: artifact-only` that ledger is the only place the post-hoc validator can read it, so a conversation line alone leaves no trace and the run is reported as missing the checkpoint. Pass `--worker <role>` on the per-worker checkpoints (it rewrites a phase-specific functional label into the roster role team-state records), `--field NAME=VALUE` for the remaining `key=value` tokens in the order the line carries them, and `--detail <text>` where the line ends in a verb phrase; the wording listed below is the default for the fixed-prose checkpoints. The default follows what happened: a second `phase-1-intake` call in the same run renders `complete`, and `phase-6-synthesis` in a task type whose profile has no report-writer role renders `authoring final report`. **Enforced:** `_default_detail` in `scripts/okstra_ctl/lead_progress.py`, `tests/contract/test_lead_progress_cli.py`.
264
+ Record each checkpoint with `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>`, then emit the `progressLine` it prints as the user-facing line. The command resolves `leadEventsPath` from the run manifest and writes the checkpoint there — on a host whose adapter declares `sessionAccounting: artifact-only` that ledger is the only place the post-hoc validator can read it, so a conversation line alone leaves no trace and the run is reported as missing the checkpoint. Pass `--worker <role>` on the per-worker checkpoints (it rewrites a phase-specific functional label into the roster role team-state records), `--field NAME=VALUE` for the remaining `key=value` tokens in the order the line carries them, and `--detail <text>` where the line ends in a verb phrase; the wording listed below is the default for the fixed-prose checkpoints. The default follows what happened: a second `phase-1-intake` call in the same run renders `complete`, and `phase-6-synthesis` in a task type whose profile has no report-writer role renders `authoring final report`. **Enforced:** `_default_detail` in `scripts/okstra_ctl/lead_progress.py`, the retired Python suite.
264
265
 
265
266
  Some checkpoints are recorded by the command that performs the step, because that command holds the fact the line states:
266
267
 
@@ -270,7 +271,7 @@ Some checkpoints are recorded by the command that performs the step, because tha
270
271
  - The team commands record nothing on any other `terminalBackend`: a run that dispatches with `okstra team dispatch` and waits with `okstra team await` there appends the team commands' checkpoints itself. `okstra worker-dispatch` still records its own, as listed above.
271
272
  - `okstra report-finalize` without `--only` records `phase-7-persist` before its first step, so `validate-run` reads it.
272
273
 
273
- Emit the `PROGRESS:` lines those commands print (the trailing text lines of `team await` and `team reclaim`, or `progressLines` in the JSON the others print) verbatim, and do not call `lead-progress append` for them — each extra call is one more lead turn over the whole context. Everything else still goes through `lead-progress append`: every other checkpoint; `phase-3-team-create` when the lead itself recorded the marker (the concurrent-run `skipped (concurrent-run)` variant); and `phase-4-dispatch`, `phase-5-collect` and `phase-6-synthesis` for a worker dispatched through a host-native primitive (`record-dispatch` / `link-result`). `phase-5-collect` from a command does not replace the lead's own acceptance check (`okstra worker-audit-check`). On an activity-contract-v1 run the command that records a worker's `phase-4-dispatch` / `phase-5-collect` also appends that worker's `worker-dispatched` / `worker-completed` activity and puts its `ACTIVITY:` line right after the `PROGRESS:` line in what it prints; emit both verbatim and do not append those two activities again. The lead appends them only for a worker whose checkpoint it records itself (host-native primitive, or a `team` command on another backend). **Enforced:** `scripts/okstra_ctl/dispatch_checkpoints.py`, `record_checkpoint` in `scripts/okstra_ctl/lead_progress.py`, `tests/run/test_team_cmux_backend.py`, `tests/run/test_okstra_ctl_dispatcher.py`, `tests/report/test_report_finalize.py`.
274
+ Emit the `PROGRESS:` lines those commands print (the trailing text lines of `team await` and `team reclaim`, or `progressLines` in the JSON the others print) verbatim, and do not call `lead-progress append` for them — each extra call is one more lead turn over the whole context. Everything else still goes through `lead-progress append`: every other checkpoint; `phase-3-team-create` when the lead itself recorded the marker (the concurrent-run `skipped (concurrent-run)` variant); and `phase-4-dispatch`, `phase-5-collect` and `phase-6-synthesis` for a worker dispatched through a host-native primitive (`record-dispatch` / `link-result`). `phase-5-collect` from a command does not replace the lead's own acceptance check (`okstra worker-audit-check`). On an activity-contract-v1 run the command that records a worker's `phase-4-dispatch` / `phase-5-collect` also appends that worker's `worker-dispatched` / `worker-completed` activity and puts its `ACTIVITY:` line right after the `PROGRESS:` line in what it prints; emit both verbatim and do not append those two activities again. The lead appends them only for a worker whose checkpoint it records itself (host-native primitive, or a `team` command on another backend). **Enforced:** `scripts/okstra_ctl/dispatch_checkpoints.py`, `record_checkpoint` in `scripts/okstra_ctl/lead_progress.py`, the retired Python suite, the retired Python suite, the retired Python suite.
274
275
 
275
276
  For an `implementation-planning` run whose run manifest declares `activityContractVersion: 1`, record every required activity boundary with `okstra agent-activity append` against the manifest-provided `leadEventsPath`. Model-facing calls pass prose through `--summary-file <md>` and a command through `--command`, `--command-cwd`, `--command-exit-code`, and `--command-output-file <md>`; do not construct `--command-record` JSON. The ordering is fixed: the structured append succeeds first, the matching `PROGRESS:` line is emitted second, and the immediately following `ACTIVITY:` line projects the same structured fields into the conversation language. Do not reconstruct structured activity from conversation text. If the append fails, do not present that activity boundary as completed.
276
277
 
@@ -283,7 +284,7 @@ ACTIVITY: id=A-001 agent=codex-worker summary="Verify Stage Map paths and comman
283
284
 
284
285
  Use the exact CLI projection: `id`, `agent`, quoted `summary`, comma-joined `items` (`<none>` when empty), `result` (`<none>` when empty), and `outcome`. Only prose inside `summary` is localized to the conversation language; a row an okstra command writes itself (the `worker-dispatched` / `worker-completed` rows above, `lead-correction-applied`) carries a fixed English summary and is exempt. Required kinds are `worker-dispatched`, `worker-completed`, `verification-round-completed`, `self-fix-applied`, `user-decision-required`, and `user-decision-evaluated`.
285
286
 
286
- **Enforcement:** `tests/contract/test_host_orchestration_rules.py` keeps this instruction on every lead path. `validators/validate_session_conformance.py` `_check_activity_contract` checks the structured event log and does not treat an `ACTIVITY:` conversation line as evidence.
287
+ **Enforcement:** the retired Python suite previously kept this instruction on every lead path. `validators/validate_session_conformance.py` `_check_activity_contract` checks the structured event log and does not treat an `ACTIVITY:` conversation line as evidence.
287
288
 
288
289
  Required checkpoints:
289
290
 
@@ -435,7 +436,7 @@ After context-loader completes, read **only the compact intake files below** in
435
436
  - [convergence](./convergence.md) — read the common procedure with the bounded command below before the first `PROGRESS: phase-5.5-convergence` line of any run that runs a convergence round.
436
437
  - `plan-body-verification` (the absolute path in **Okstra Runtime Resources**) — read the common procedure with the bounded command in the Phase 6 sub-step before the first `PROGRESS: phase-5.5.9-plan-verify` line.
437
438
 
438
- For a run frozen before the phase-package migration, a missing `prompts/lead/plan-body-verification.md` pointer resolves within the asset root containing this lead contract. Identify its unique `okstra_ctl` package at `scripts/okstra_ctl`, `python/okstra_ctl`, or `lib/python/okstra_ctl` by `__init__.py`, then read `phases/implementation_planning/instructions/plan-body-verification.md` inside that package at the original Phase 6 sub-step. Preserve the bounded read and the `phase-5.5.9-plan-verify` checkpoint order below. If the package is ambiguous or the resource is missing, stop and report it; do not search another installation or rewrite frozen profiles, manifests, prompts or run context. The mapping is checked by `scripts/okstra_ctl/phases/implementation_planning/tests/test_instruction_assets.py`; the existing entry guard checks read timing by the unchanged basename.
439
+ For a run frozen before the phase-package migration, a missing `prompts/lead/plan-body-verification.md` pointer resolves within the asset root containing this lead contract. Identify its unique `okstra_ctl` package at `scripts/okstra_ctl`, `python/okstra_ctl`, or `lib/python/okstra_ctl` by `__init__.py`, then read `phases/implementation_planning/instructions/plan-body-verification.md` inside that package at the original Phase 6 sub-step. Preserve the bounded read and the `phase-5.5.9-plan-verify` checkpoint order below. If the package is ambiguous or the resource is missing, stop and report it; do not search another installation or rewrite frozen profiles, manifests, prompts or run context. The mapping is checked by the retired Python suite; the existing entry guard checks read timing by the unchanged basename.
439
440
 
440
441
  Both stay out of the Phase 1 baseline for the token reason above, and neither is optional at its round: together they carry more than half of this contract family's MUST clauses, so a round dispatched without the read is a round run from memory. **Enforced:** `validators/validate_session_conformance.py` `_ENTRY_GUARD_READS` requires each read — a `Read` call or a shell command naming the file — inside this run's window and before that checkpoint. The requirement is conditioned on the checkpoint actually appearing, so a run that holds no such round is never asked for it.
441
442
 
@@ -448,7 +449,7 @@ output identifies when those sections are needed:
448
449
  awk '/^### Adversarial Re-verification Prompt$/ {skip=1} /^## Convergence State Artifact$/ {skip=0} /^## Coverage critic pass$/ {skip=1} /^## Output$/ {skip=0} !skip {print}' '<convergence-contract-path>'
449
450
  ```
450
451
 
451
- `tests/contract/test_contract_examples_execute.py::test_convergence_common_read_keeps_protocol`
452
+ the retired Python suite
452
453
  checks the emitted common procedure. The same entry-guard read trace applies.
453
454
 
454
455
  **Lazy reading discipline (do NOT read at Phase 1):**
@@ -465,7 +466,7 @@ checks the emitted common procedure. The same entry-guard read trace applies.
465
466
 
466
467
  The `implementation` profile's thin core (`scripts/okstra_ctl/phases/implementation/profile.md`) is intentionally minimal so the Phase 1 baseline stays small. Three sidecar files carry the bulk of the rules and MUST be read at the listed phase — do NOT pre-load them at Phase 1. The sidecar list and each one's `Read at` phase live in that profile's "Lazy section pointers" table, which arrives in the Phase 1 intake via `analysis-profile.md`, so it is already in context whenever this discipline applies.
467
468
 
468
- For a run frozen before the phase-package migration, resolve a missing `prompts/profiles/_implementation-*.md` pointer within the asset root containing this lead contract. That root has one `okstra_ctl` package at `scripts/okstra_ctl`, `python/okstra_ctl`, or `lib/python/okstra_ctl`, identified by its `__init__.py`. Read `phases/implementation/instructions/<same-basename>` inside that package at the original `Read at` phase. If no unique package or requested file exists, stop and report the missing resource. Keep the frozen `analysis-profile.md` unchanged and do not search another installation. New runs carry resolved instruction paths. The path mapping is checked by `scripts/okstra_ctl/phases/implementation/tests/test_assets.py`; the entry guard below checks the recorded read timing.
469
+ For a run frozen before the phase-package migration, resolve a missing `prompts/profiles/_implementation-*.md` pointer within the asset root containing this lead contract. That root has one `okstra_ctl` package at `scripts/okstra_ctl`, `python/okstra_ctl`, or `lib/python/okstra_ctl`, identified by its `__init__.py`. Read `phases/implementation/instructions/<same-basename>` inside that package at the original `Read at` phase. If no unique package or requested file exists, stop and report the missing resource. Keep the frozen `analysis-profile.md` unchanged and do not search another installation. New runs carry resolved instruction paths. The path mapping is checked by the retired Python suite; the entry guard below checks the recorded read timing.
469
470
 
470
471
  **Entry guard (BLOCKING).** Before transitioning into Phase 5 or Phase 6 for an `implementation` run, lead MUST load the sidecar(s) whose `Read at` (per that table) matches the entering phase — either a single `Read` tool call, or a shell command naming that file (`cat`, `sed -n`), since some hosts steer file reads to the shell. If lead enters the phase without that load recorded in the selected adapter's conformance evidence/event source, phase entry is refused — lead writes a `contract-violation` to the run-level errors log with `--message "implementation-sidecar-not-loaded"` and stops. Re-entry requires the sidecar Read first. **Enforcement:** the Phase 7 validator (`validate_session_conformance.py`) verifies post-hoc that all three sidecar loads exist in the selected adapter's declared source within this run's window, and that they precede the `phase-6-synthesis` / `phase-7-persist` checkpoints respectively.
471
472
 
@@ -637,16 +638,16 @@ Pick the next action from this table; the first matching row wins:
637
638
 
638
639
  - Open `blocks: approval` rows, or a `blocked-by-disagreement` gate whose approval rows carry no progress disposition (`okstra_ctl.run._blocking_gate_survives_user_decision`) → `/okstra-user-response` (name the `C-NNN` ids). Do not start implementation until those answers exist. An `accept-risk` / `select` / `answer` already recorded is not an open blocker. A report published with those rows open is not a failed run — the answers are the missing input, and a planning re-run without them reproduces the same block.
639
640
 
640
- After `implementation-planning`, once finalization succeeds, stop on the approval row above. No open approval blocker → `/okstra-run` → `implementation` (asks `approve_plan_confirm`) or `--approve`. Do not propose another planning run. Do not say `/okstra-inspect`. A blocking `validate-run` failure follows the recovery row first; a `validate-run` advisory is named in one line and nothing else — it did not fail the run.
641
+ After `implementation-planning`, once finalization succeeds, stop on the approval row above. No open approval blocker → `/okstra-run` → `implementation` (asks `approve_plan_confirm`) or `--approve`. Do not propose another planning run. A blocking `validate-run` failure follows the recovery row first; a `validate-run` advisory is named in one line and nothing else — it did not fail the run.
641
642
 
642
643
  For every other task type:
643
644
 
644
645
  - Pointer `status: ready` → `/okstra-run` for that `phase`. Quote the pointer's `rationale` — that sentence is this run's report saying why that phase comes next, and it is the analysis the user asked for.
645
- - Pointer `status: terminal` → the lifecycle ends here. Say the task is finished and quote the pointer's `rationale`. Do not propose a run and do not send the user to `/okstra-inspect`: the decision is already made, so there is nothing to inspect. If this run registered follow-up tasks, name them and the command that starts one.
646
+ - Pointer `status: terminal` → the lifecycle ends here. Say the task is finished and quote the pointer's `rationale`. Do not propose a run; the decision is already made. If this run registered follow-up tasks, name them and the command that starts one.
646
647
  - Pointer `status: terminal` and the result carries `nextInGroup` → the task is finished and the task-group has a task not yet started: say this task is finished, then close on `/okstra-run` for `nextInGroup.briefId` from its `brief` path — the group's start order is the brief ordinal, and `nextCommand.note` already names the task and its brief.
647
648
  - Pointer `status: blocked` → the pointer's `rationale` names what is in the way and what to run. Quote it and issue that command — `/okstra-user-response` for the `C-NNN` ids it lists, or `/okstra-run` for the phase it names.
648
- - Pointer `status: pending` with a `rationale` → the user's own input is what comes next. Quote the `rationale` and issue the command it names. Do not re-run the phase that just completed, and do not send the user to `/okstra-inspect`: a finished phase has nothing to inspect, and re-running it discards the result the user is being asked to act on.
649
- - Otherwise → `/okstra-inspect status` for this task.
649
+ - Pointer `status: pending` with a `rationale` → the user's own input is what comes next. Quote the `rationale` and issue the command it names. Do not re-run the phase that just completed,; re-running it discards the result the user is being asked to act on.
650
+ - Otherwise → `okstra task-show <task-key>` for this task.
650
651
 
651
652
  When the host native picker is available and two of those rows could apply, ask with that picker (recommended first). Do not end the turn after the status dump.
652
653
 
@@ -83,4 +83,4 @@ For the `selected-direction` plan branch: A direction change routes to `implemen
83
83
 
84
84
  For the legacy candidate-comparison branch: Any deviation MUST be justified in the final report AND routed to a new `implementation-planning` run; never silently expand scope.
85
85
 
86
- Enforcement boundary: the lead applies these semantic distinctions through the phase-transition checklist in [the lead contract](./okstra-lead-contract.md). `tests/contract/test_prompt_fragment_ownership.py` preserves the decision rules at this canonical location; it checks instruction ownership, not the correctness of an individual model judgement.
86
+ Enforcement boundary: the lead applies these semantic distinctions through the phase-transition checklist in [the lead contract](./okstra-lead-contract.md). the retired Python suite preserves the decision rules at this canonical location; it checks instruction ownership, not the correctness of an individual model judgement.
@@ -97,7 +97,7 @@ This section adds report-specific checks to [okstra-lead-contract](./okstra-lead
97
97
 
98
98
  A report-writer materialization without `--corrections` whose narrative already exists and parses is refused before any prompt is written — free-form corrections cannot be checked before the writer runs, and four of six re-runs in the 2026-09-03 measurement were lead instructions that contradicted the authoring contract. Only a narrative whose structure does not parse (line grammar, an unknown top-level field) is re-authored, not corrected: that dispatch needs no ledger, and its body quotes the parser's message. Because re-authoring overwrites the live file in place, okstra copies the existing narrative to `worker-results/<narrative-name>.pre-<invocation-id>.md` at materialization and renders a `## Previous Attempt` section naming that copy (**Enforced:** `_preserve_reauthored_narrative` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`); the 2026-09-09 dev-10642 run lost a 579-line attempt to a failed in-place re-indent command with no copy to fall back on. A narrative that breaks the line grammar is not a produced artifact: the dispatcher settles that attempt as `required worker artifact is unusable: narrative does not parse: …` and retries it inside the same batch, so you see the parser's message at collection, not at Phase 7 assembly (**Enforced:** `okstra_ctl.dispatch_state.unusable_result_defect`, read by `missing_completion_paths` and the `team await` record path). The synthesis packet's Authoring Contract carries the line grammar itself (`report_narrative.NARRATIVE_GRAMMAR_INSTRUCTIONS`), so a writer that reads only the packet still sees it. Value defects — an id outside its pattern, a value outside its enum, a missing required field — leave the structure readable and are exactly what the ledger fixes; the a3 attempt of the 2026-09-03 run carried twenty `SC-` ids that assembly refused and was still a corrective base.
99
99
 
100
- **Enforced:** `_with_report_writer_sections` / `_refuse_free_form_correction` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`, `report_corrections.check_corrections`, `agent/prompt_cli/corrections.run_corrections_apply`; `tests/run/test_agent_prompt_corrections.py` and `tests/contract/test_report_writer_v3_contract.py` keep this procedure in the lead contract.
100
+ **Enforced:** `_with_report_writer_sections` / `_refuse_free_form_correction` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`, `report_corrections.check_corrections`, `agent/prompt_cli/corrections.run_corrections_apply`; the retired Python suite and the retired Python suite keep this procedure in the lead contract.
101
101
 
102
102
  ## Implementation-planning sequence
103
103
 
@@ -144,7 +144,7 @@ Do not run the ten steps below manually. Invoke `okstra report-finalize`; contra
144
144
 
145
145
  After `report-finalize` returns with `ok: true`, the lead closes the run with the launch prompt's User closeout. A generated HTML file alone does not establish successful validation.
146
146
 
147
- When the result carries `recovery.mode: same-run`, continue the authorized work in this run. Read every `recovery.issues` entry and failed step output. Correct writer-owned fields through the correction ledger procedure above; correct orchestrator-owned inputs through their owning commands. If plan content changes, prepare and verify the affected items before finalizing. Then execute `recovery.resumeCommand`, which retains this run manifest and resumes from the earliest failure, including reassembly of contract 3.0 inputs. Keep previous approvals, user decisions, model selections and completed evidence. Do not ask for another `/okstra-run` to repair references, coverage summaries, narrative syntax or command spelling. Ask only when an unresolved user decision or an actual external prerequisite prevents the correction. Do not edit an installed runtime or another repository while recovering a consuming project's task. **Enforced:** `report_finalize._finalize_recovery` returns the same-run command and complete owner issues, `closeout_command` suppresses the new-run closeout for that result, and `tests/report/test_report_finalize.py` checks recovery after a failed step. Execution of the correction remains the lead's responsibility.
147
+ When the result carries `recovery.mode: same-run`, continue the authorized work in this run. Read every `recovery.issues` entry and failed step output. Correct writer-owned fields through the correction ledger procedure above; correct orchestrator-owned inputs through their owning commands. If plan content changes, prepare and verify the affected items before finalizing. Then execute `recovery.resumeCommand`, which retains this run manifest and resumes from the earliest failure, including reassembly of contract 3.0 inputs. Keep previous approvals, user decisions, model selections and completed evidence. Do not ask for another `/okstra-run` to repair references, coverage summaries, narrative syntax or command spelling. Ask only when an unresolved user decision or an actual external prerequisite prevents the correction. Do not edit an installed runtime or another repository while recovering a consuming project's task. **Enforced:** `report_finalize._finalize_recovery` returns the same-run command and complete owner issues, `closeout_command` suppresses the new-run closeout for that result, and the retired Python suite previously checked recovery after a failed step. Execution of the correction remains the lead's responsibility.
148
148
 
149
149
  ## Routing pointer
150
150
 
@@ -163,7 +163,7 @@ Write the routing `rationale` for someone who reads the pointer with no report i
163
163
 
164
164
  `phase` is non-empty only under `ready`. `prepare` may lower `ready` to `pending` while retaining `phase` in `scripts/okstra_ctl/render.py::_derive_next_recommended_phase`; readers must use `status` for launchability. The projection maps a `release-handoff(stage-group)` target onto `phase` `release-handoff` — the parenthesised form is a scope qualifier, not a task type, and the wizard asks the stage scope separately. A `done` target ends the lifecycle: `terminal`, no `phase`, carrying your `rationale` as the reason the task is finished.
165
165
 
166
- For `implementation-planning` the projection reads the record rather than a routing field. When `implementationPlanning.outcome` is `plan-ready`, or the plan is a candidate-comparison record with no `outcome` field, and a `Blocks=approval` row still blocks progress (`open`, or an unincorporated `request-revision` / `reject`), or the plan-body gate is `aborted-non-result`, the pointer comes out `blocked` with an empty `phase` and a reason naming the blocking ids. The same plan with no open approval blocker is approvable — `ready` at `implementation`. `blocked-by-disagreement` with every approval row user-proceeded (`accept-risk` / `select` / `answer`) or incorporated in `supersessionLedger` is approvable — `ready` at `implementation`. The user still has to approve it separately. A missing `outcome` is not `pending` and is not a reason to send the user to `/okstra-inspect`.
166
+ For `implementation-planning` the projection reads the record rather than a routing field. When `implementationPlanning.outcome` is `plan-ready`, or the plan is a candidate-comparison record with no `outcome` field, and a `Blocks=approval` row still blocks progress (`open`, or an unincorporated `request-revision` / `reject`), or the plan-body gate is `aborted-non-result`, the pointer comes out `blocked` with an empty `phase` and a reason naming the blocking ids. The same plan with no open approval blocker is approvable — `ready` at `implementation`. `blocked-by-disagreement` with every approval row user-proceeded (`accept-risk` / `select` / `answer`) or incorporated in `supersessionLedger` is approvable — `ready` at `implementation`. The user still has to approve it separately. A missing `outcome` is not `pending`.
167
167
 
168
168
  ## Compatibility
169
169
 
@@ -28,7 +28,7 @@ The start screen assigns a **model ref** (`provider/model`) to each **canonical
28
28
 
29
29
  **Dispatch does not invent a missing model assignment.** Launch-time empty slots are filled by the model default chain before the run starts. At dispatch the model for every role comes from `resultContract.workerRoles[*].modelExecutionValue` in `task-manifest.json` (and lead model metadata). There is no per-role hard-coded fallback — see "Model Assignment Rules" below.
30
30
 
31
- **Dispatch-prompt invariant.** Lead's dispatch prompt body for every rostered analysis worker MUST be byte-identical except for the role label and wrapper-specific path headers (for example `**Worktree:**`). The role label is the ONLY identity form the normalizer erases, and it erases exactly the label `worker_prompt_body.analysis_worker_label` renders for the run's own worker ids — so a provider outside that function's display map (`grok`, `kimi`, an installed adapter) is covered as it comes. Naming the worker any other way (a model name, a host name, a provider's product name) survives normalization and fails the equality group before publication. **Enforced:** `okstra_ctl.worker_prompt_contract.normalise_analysis_prompt`, pinned by `tests/contract/test_analysis_prompt_identity_normalization.py`. Lead MUST NOT bias the brief by inserting per-worker emphasis sentences ("you focus on X") into the body. Bias-by-prompt reproduces the historical failure mode where Claude commented only on assumptions, Codex only on code paths, and Antigravity only on requirements — leaving convergence with nothing to converge on.
31
+ **Dispatch-prompt invariant.** Lead's dispatch prompt body for every rostered analysis worker MUST be byte-identical except for the role label and wrapper-specific path headers (for example `**Worktree:**`). The role label is the ONLY identity form the normalizer erases, and it erases exactly the label `worker_prompt_body.analysis_worker_label` renders for the run's own worker ids — so a provider outside that function's display map (`grok`, `kimi`, an installed adapter) is covered as it comes. Naming the worker any other way (a model name, a host name, a provider's product name) survives normalization and fails the equality group before publication. **Enforced:** `okstra_ctl.worker_prompt_contract.normalise_analysis_prompt`, pinned by the former Python suite; that regression check is now retired. Lead MUST NOT bias the brief by inserting per-worker emphasis sentences ("you focus on X") into the body. Bias-by-prompt reproduces the historical failure mode where Claude commented only on assumptions, Codex only on code paths, and Antigravity only on requirements — leaving convergence with nothing to converge on.
32
32
 
33
33
  Disjoint initial scopes are invalid triangulation. Every selected analysis worker owns the same common verification requirements; provider diversity supplies independent observations, not separate coverage slices. Do not shard the common scope by worker, provider, or model. Worker-specific depth belongs only in the non-voting Specialization Lens after the shared analysis is complete.
34
34
 
@@ -123,7 +123,7 @@ Terminal statuses that can be recorded for a worker:
123
123
  4. A process exit, spawn acknowledgement, pane creation, or Result Path alone is insufficient when the backend contract requires additional status/audit artifacts.
124
124
  5. Apply the single shared retry budget through `redispatch_worker`; after the second failure, record the terminal status and proceed with reduced confidence.
125
125
 
126
- Keep one active runtime wait for the pending batch. `team await` reconciles wrapper completion and retries inside that process; its progress output names changed pending attempts, with `--heartbeat-seconds` limiting how frequently a changed summary is printed. Unchanged attempts produce no repeated summary. Enforcement: `dispatch_core.await_dispatches` and `tests/run/test_team_await_dead_wrapper.py`.
126
+ Keep one active runtime wait for the pending batch. `team await` reconciles wrapper completion and retries inside that process; its progress output names changed pending attempts, with `--heartbeat-seconds` limiting how frequently a changed summary is printed. Unchanged attempts produce no repeated summary. Enforcement: `dispatch_core.await_dispatches` and the retired Python suite.
127
127
 
128
128
  Host guidance: use a completion notification or blocking wait for the same handle when the current host provides it. If the host yields before completion, resume that handle with its supported wait interval. A transport timeout with no changed worker state does not call for another `team await`, a log reread, a liveness command, or a lead progress record. Worker deadlines and liveness remain inside the existing runtime wait. Host callbacks and model wakeups are controlled by the host; this guidance does not claim the runtime can suppress them.
129
129
 
@@ -315,4 +315,4 @@ Every consumer of this file reads these keys by name. Write them exactly as spel
315
315
  | `livenessMode` | every row | `audit-heartbeat` (in-process) or `wrapper-status` (CLI wrapper) — authoritative, never inferred from the provider |
316
316
  | `usage` | terminal rows | `{totalTokens, toolUses, durationMs}` |
317
317
 
318
- **Enforced:** `okstra_ctl.worker_liveness.probe_target` refuses a row with a missing/unknown `livenessMode`, a missing artifact field for that mode, or a missing `startedAt`; `--wait` additionally refuses a row with no `resultPath`. `tests/contract/test_team_state_worker_row_fields.py` fails when this table drifts from the keys `dispatch_core` writes.
318
+ **Enforced:** `okstra_ctl.worker_liveness.probe_target` refuses a row with a missing/unknown `livenessMode`, a missing artifact field for that mode, or a missing `startedAt`; `--wait` additionally refuses a row with no `resultPath`. the retired Python suite fails when this table drifts from the keys `dispatch_core` writes.
@@ -2,7 +2,7 @@
2
2
  from __future__ import annotations
3
3
 
4
4
  import contextlib
5
- from dataclasses import dataclass
5
+ from dataclasses import dataclass, replace
6
6
  from datetime import datetime, timezone
7
7
  import fcntl
8
8
  import hashlib
@@ -15,6 +15,10 @@ import tempfile
15
15
  from typing import Any, Iterator, Literal, Mapping, get_args
16
16
 
17
17
  from ..domain.role import RoleCatalogError, role_for_duty
18
+ from ..verification_invocation import (
19
+ VerificationGenerationReference, read_invocation_generation,
20
+ select_verification_generation_header_lines, verification_generation_headers,
21
+ )
18
22
  from ..json_boundary import (
19
23
  JsonBoundaryError,
20
24
  external_invocation_json_source,
@@ -185,6 +189,7 @@ class AgentInvocationRequest:
185
189
  # Republish a prompt this invocation id already wrote, but only while no
186
190
  # dispatch has used it. See `_publish_or_reuse`.
187
191
  replace_undispatched: bool = False
192
+ verification_generation: VerificationGenerationReference | None = None
188
193
 
189
194
 
190
195
  @dataclass(frozen=True)
@@ -641,6 +646,7 @@ def prepare_agent_invocation(
641
646
  request: AgentInvocationRequest,
642
647
  ) -> PreparedAgentInvocation:
643
648
  """Materialize one immutable prompt and its adjacent completion metadata."""
649
+ request = _bind_generation_request(request)
644
650
  _validate_request(request)
645
651
  materialized = _materialize(request)
646
652
  if materialized.reservation_root is None:
@@ -811,12 +817,14 @@ def _retry_prompt_bytes(
811
817
 
812
818
  def compose_agent_prompt(request: AgentInvocationRequest) -> str:
813
819
  """Render and validate a prompt candidate without publishing artifacts."""
820
+ request = _bind_generation_request(request)
814
821
  _validate_request(request)
815
822
  return _materialize(request).prompt_bytes.decode("utf-8")
816
823
 
817
824
 
818
825
  def compose_unbound_run_prompt(request: AgentInvocationRequest) -> bytes:
819
826
  """Compose v2 run prompt bytes before a dynamic role identity is reserved."""
827
+ request = _bind_generation_request(request)
820
828
  _validate_common_request(request)
821
829
  _validate_unbound_v2_run_request(request)
822
830
  common = load_common_duty_contract(request.duty_root)
@@ -1172,6 +1180,58 @@ def _materialize(request: AgentInvocationRequest) -> _MaterializedInvocation:
1172
1180
  )
1173
1181
 
1174
1182
 
1183
+ def _bind_generation_request(request: AgentInvocationRequest) -> AgentInvocationRequest:
1184
+ try:
1185
+ manifest = _load_request_manifest(request)
1186
+ reference = _typed_generation_reference(request)
1187
+ _require_sealed_generation(
1188
+ request.project_root, request.run_manifest_path, manifest,
1189
+ reference, request.audience,
1190
+ )
1191
+ return _with_generation_anchors(request, reference)
1192
+ except (OSError, ValueError) as exc:
1193
+ raise AgentInvocationError(str(exc)) from exc
1194
+
1195
+
1196
+ def _load_request_manifest(request: AgentInvocationRequest) -> dict[str, object]:
1197
+ if request.run_manifest_path is None:
1198
+ return {}
1199
+ _project_relative(request.run_manifest_path, request.project_root, must_exist=True)
1200
+ return _load_json_object(request.run_manifest_path, "run manifest")
1201
+
1202
+
1203
+ def _typed_generation_reference(
1204
+ request: AgentInvocationRequest,
1205
+ ) -> VerificationGenerationReference | None:
1206
+ reference = request.verification_generation
1207
+ if reference is not None and not isinstance(
1208
+ reference, VerificationGenerationReference,
1209
+ ):
1210
+ raise ValueError("verification generation reference is invalid")
1211
+ return reference
1212
+
1213
+
1214
+ def _with_generation_anchors(
1215
+ request: AgentInvocationRequest,
1216
+ reference: VerificationGenerationReference | None,
1217
+ ) -> AgentInvocationRequest:
1218
+ anchors = request.instruction.anchor_lines
1219
+ existing = select_verification_generation_header_lines(anchors)
1220
+ if reference is None:
1221
+ if existing:
1222
+ raise ValueError(
1223
+ "verification generation anchors require a bound generation"
1224
+ )
1225
+ return request
1226
+ headers = verification_generation_headers(reference)
1227
+ if existing and existing != headers:
1228
+ raise ValueError("verification generation anchors conflict with reference")
1229
+ return replace(request, instruction=replace(
1230
+ request.instruction,
1231
+ anchor_lines=anchors if existing else (*anchors, *headers),
1232
+ ))
1233
+
1234
+
1175
1235
  def _validate_request(request: AgentInvocationRequest) -> None:
1176
1236
  _validate_common_request(request)
1177
1237
  if request.run_manifest_path is None:
@@ -1448,7 +1508,7 @@ def _invocation_digests(
1448
1508
  }
1449
1509
 
1450
1510
 
1451
- def _metadata_payload(
1511
+ def _base_metadata_payload(
1452
1512
  request: AgentInvocationRequest,
1453
1513
  duty: DutyContract,
1454
1514
  digests: Mapping[str, str],
@@ -1495,7 +1555,18 @@ def _metadata_payload(
1495
1555
  )
1496
1556
  },
1497
1557
  "digests": dict(digests),
1558
+ **({"verificationGeneration": request.verification_generation.to_payload()}
1559
+ if request.verification_generation is not None else {}),
1498
1560
  }
1561
+ return payload
1562
+
1563
+
1564
+ def _metadata_payload(
1565
+ request: AgentInvocationRequest,
1566
+ duty: DutyContract,
1567
+ digests: Mapping[str, str],
1568
+ ) -> dict[str, object]:
1569
+ payload = _base_metadata_payload(request, duty, digests)
1499
1570
  if _request_identity_version(request) == 2:
1500
1571
  manifest = _load_json_object(request.run_manifest_path, "run manifest")
1501
1572
  identity = invocation_execution_identity_from_manifest(
@@ -1901,9 +1972,64 @@ def _verify_prompt_file(
1901
1972
  errors.extend(_verify_instruction_digest(metadata, body))
1902
1973
  errors.extend(_verify_model_header(metadata, body))
1903
1974
  errors.extend(_verify_execution_delivery(metadata, path, body))
1975
+ errors.extend(_verify_generation_reference(metadata, project_root, body))
1904
1976
  return errors
1905
1977
 
1906
1978
 
1979
+ def _verify_generation_reference(
1980
+ metadata: Mapping[str, object], project_root: Path, prompt_bytes: bytes,
1981
+ ) -> list[str]:
1982
+ try:
1983
+ reference = metadata_generation_reference(metadata)
1984
+ manifest_path, manifest = _metadata_run_manifest(metadata, project_root)
1985
+ _require_sealed_generation(
1986
+ project_root, manifest_path, manifest, reference, metadata["audience"],
1987
+ )
1988
+ return _prompt_generation_header_errors(prompt_bytes, reference)
1989
+ except (AgentInvocationError, OSError, ValueError) as exc:
1990
+ return [str(exc)]
1991
+
1992
+
1993
+ def metadata_generation_reference(
1994
+ metadata: Mapping[str, object],
1995
+ ) -> VerificationGenerationReference | None:
1996
+ if "verificationGeneration" not in metadata:
1997
+ return None
1998
+ return VerificationGenerationReference.from_payload(
1999
+ metadata["verificationGeneration"],
2000
+ )
2001
+
2002
+
2003
+ def _metadata_run_manifest(
2004
+ metadata: Mapping[str, object], project_root: Path,
2005
+ ) -> tuple[Path | None, dict[str, object]]:
2006
+ value = metadata["contractSource"].get("runManifestPath")
2007
+ if not value:
2008
+ return None, {}
2009
+ manifest_path = _project_path(project_root, value, must_exist=True)
2010
+ return manifest_path, _load_json_object(manifest_path, "run manifest")
2011
+
2012
+
2013
+ def _prompt_generation_header_errors(
2014
+ prompt_bytes: bytes, reference: VerificationGenerationReference | None,
2015
+ ) -> list[str]:
2016
+ prefix, _ = _split_prompt(prompt_bytes.decode("utf-8"))
2017
+ actual = select_verification_generation_header_lines(prefix.splitlines())
2018
+ expected = verification_generation_headers(reference) if reference else ()
2019
+ if actual != expected:
2020
+ return ["verification generation reference differs from prompt"]
2021
+ return []
2022
+
2023
+
2024
+ def _require_sealed_generation(
2025
+ project_root: Path, manifest_path: Path | None, manifest: Mapping[str, object],
2026
+ reference: VerificationGenerationReference | None, audience: str,
2027
+ ) -> None:
2028
+ read_invocation_generation(
2029
+ project_root, manifest_path, manifest, reference, audience,
2030
+ )
2031
+
2032
+
1907
2033
  def _execution_delivery_lines(
1908
2034
  metadata: Mapping[str, object], metadata_path: Path,
1909
2035
  ) -> tuple[str, ...]:
@@ -2323,12 +2449,20 @@ def _verify_reservation(
2323
2449
 
2324
2450
  def _metadata_schema_is_exact(metadata: Mapping[str, object]) -> bool:
2325
2451
  schema = metadata.get("schemaVersion")
2452
+ present_optional_keys = set(metadata) & {"verificationGeneration"}
2453
+ has_generation = "verificationGeneration" in metadata
2454
+ if has_generation:
2455
+ generation = metadata["verificationGeneration"]
2456
+ try:
2457
+ VerificationGenerationReference.from_payload(generation)
2458
+ except ValueError:
2459
+ return False
2326
2460
  if schema == 1:
2327
- if set(metadata) != _TOP_LEVEL_KEYS:
2461
+ if set(metadata) != _TOP_LEVEL_KEYS | present_optional_keys:
2328
2462
  return False
2329
2463
  elif schema == "2.0":
2330
2464
  if (
2331
- set(metadata) != _V2_TOP_LEVEL_KEYS
2465
+ set(metadata) != _V2_TOP_LEVEL_KEYS | present_optional_keys
2332
2466
  or metadata.get("executionIdentityVersion") != 2
2333
2467
  or not all(
2334
2468
  isinstance(metadata.get(key), str) and metadata[key]
@@ -2360,13 +2494,16 @@ def _metadata_schema_is_exact(metadata: Mapping[str, object]) -> bool:
2360
2494
  return False
2361
2495
  if any(not isinstance(item, dict) or set(item) != {"kind", "path"} for item in sources):
2362
2496
  return False
2363
- return _digest_paths(metadata) == {
2497
+ expected_digests = {
2364
2498
  "digests.catalogDigest",
2365
2499
  "digests.assignmentDigest",
2366
2500
  "digests.dutyDigest",
2367
2501
  "digests.instructionDigest",
2368
2502
  "digests.promptDigest",
2369
2503
  }
2504
+ if has_generation:
2505
+ expected_digests.add("verificationGeneration.digest")
2506
+ return _digest_paths(metadata) == expected_digests
2370
2507
 
2371
2508
 
2372
2509
  def _model_assignment_projection(payload: object) -> dict[str, object] | None:
@@ -25,6 +25,7 @@ from ..invocation import (
25
25
  agent_model_assignment_from_payload,
26
26
  digest_duty_catalog,
27
27
  invocation_execution_identity_from_manifest,
28
+ metadata_generation_reference,
28
29
  prepare_agent_invocation,
29
30
  compose_agent_prompt,
30
31
  compose_unbound_run_prompt,
@@ -93,6 +94,8 @@ from .inputs import (
93
94
  _relative,
94
95
  )
95
96
  from .run_identity import _validate_run_identity
97
+ from ...verification_dispatch import seal_dispatch_generation
98
+ from ...verification_invocation import VerificationGenerationReference
96
99
 
97
100
 
98
101
  _AUDIENCES = frozenset(get_args(AgentAudience))
@@ -307,6 +310,10 @@ def _materialize_run(
307
310
  active_context = hydrate_active_run_context(
308
311
  _read_json_object(active_context_path, "active run context")
309
312
  )
313
+ metadata_path = prompt_path.with_name(prompt_path.name + ".meta.json")
314
+ generation = _reuse_or_seal_verifier_generation(
315
+ args, project_root, manifest_path, manifest, active_context, metadata_path,
316
+ )
310
317
  prompt_rel = _relative(project_root, prompt_path)
311
318
  result_rel = _relative(project_root, result_path)
312
319
  audit_rel = _relative(project_root, audit_source_path)
@@ -390,7 +397,7 @@ def _materialize_run(
390
397
  run_manifest_path=manifest_path,
391
398
  duty_root=duty_root,
392
399
  prompt_path=prompt_path,
393
- metadata_path=prompt_path.with_name(prompt_path.name + ".meta.json"),
400
+ metadata_path=metadata_path,
394
401
  dispatch_kind=args.dispatch_kind,
395
402
  participant_ref=identity.participant_ref if identity is not None else None,
396
403
  role_execution_ref=(
@@ -400,6 +407,7 @@ def _materialize_run(
400
407
  invocation_ref=args.invocation_id if identity is not None else None,
401
408
  attempt=1,
402
409
  replace_undispatched=args.replace_undispatched,
410
+ verification_generation=generation,
403
411
  )
404
412
  if is_reverify:
405
413
  candidate = compose_unbound_run_prompt(request).decode("utf-8") if dynamic_source else compose_agent_prompt(request)
@@ -427,6 +435,28 @@ def _materialize_run(
427
435
  _RESOURCE_AUDIENCES = frozenset({"implementation-executor", "implementation-verifier"})
428
436
 
429
437
 
438
+ def _reuse_or_seal_verifier_generation(
439
+ args: argparse.Namespace, project_root: Path, manifest_path: Path,
440
+ manifest: Mapping[str, Any], active_context: Mapping[str, Any],
441
+ metadata_path: Path,
442
+ ) -> VerificationGenerationReference | None:
443
+ # A rerun over a published prompt reuses the generation its metadata binds;
444
+ # sealing again would recapture a tree the verifier's own run may have changed.
445
+ try:
446
+ if metadata_path.is_file():
447
+ published = metadata_generation_reference(
448
+ _read_json_object(metadata_path, "invocation metadata"),
449
+ )
450
+ if published is not None:
451
+ return published
452
+ return seal_dispatch_generation(
453
+ project_root, manifest_path, manifest, active_context,
454
+ audience=args.audience, dispatch_kind=args.dispatch_kind,
455
+ )
456
+ except ValueError as exc:
457
+ raise AgentPromptCliError(f"verification generation: {exc}") from exc
458
+
459
+
430
460
  def _implementation_anchors(
431
461
  project_root: Path, manifest_path: Path, worker_id: str,
432
462
  ) -> list[str]:
@@ -222,7 +222,7 @@ class PaneGeometry:
222
222
  columns: int
223
223
  rows: int
224
224
  x: int
225
- y: int
225
+ y: float
226
226
  cell_width_points: int
227
227
  width_points: float = 0.0
228
228
  ref: str = ""
@@ -1023,7 +1023,9 @@ def _pane_geometry(entry: dict[str, Any]) -> PaneGeometry:
1023
1023
  columns=int(entry.get("columns", 0)),
1024
1024
  rows=int(entry.get("rows", 0)),
1025
1025
  x=int(frame.get("x", 0)),
1026
- y=int(frame.get("y", 0)),
1026
+ # `_overlaps_vertically` adds a fractional height to y. A truncated y
1027
+ # puts a pane flush below the lead inside the lead's rows.
1028
+ y=float(frame.get("y") or 0),
1027
1029
  cell_width_points=int(entry.get("cell_width_points", 0)),
1028
1030
  width_points=float(frame.get("width") or 0),
1029
1031
  ref=str(entry.get("ref", "")),