okstra 0.228.2 → 0.230.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -5
- package/dist/cli-registry.mjs +0 -18
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/lifecycle/doctor.mjs +0 -15
- package/dist/commands/lifecycle/doctor.mjs.map +1 -1
- package/dist/lib/skill-catalog.mjs +4 -4
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/docs/architecture/storage-model.md +179 -13
- package/docs/architecture.md +13 -14
- package/docs/contributor-change-matrix.md +5 -5
- package/docs/project-structure-overview.md +16 -21
- package/package.json +1 -2
- package/runtime/BUILD.json +2 -2
- package/runtime/bin/lib/okstra/interactive.sh +2 -1
- package/runtime/bin/okstra-provider-exec.py +53 -4
- package/runtime/prompts/duties/code-reviewer.json +5 -2
- package/runtime/prompts/launch.template.md +5 -5
- package/runtime/prompts/lead/convergence.md +4 -4
- package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
- package/runtime/prompts/lead/phase-routing.md +1 -1
- package/runtime/prompts/lead/report-writer.md +3 -3
- package/runtime/prompts/lead/team-contract.md +3 -3
- package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
- package/runtime/python/okstra_ctl/cmux.py +4 -2
- package/runtime/python/okstra_ctl/code_review_census.py +194 -0
- package/runtime/python/okstra_ctl/code_review_coverage.py +18 -5
- package/runtime/python/okstra_ctl/code_review_scope.py +11 -7
- package/runtime/python/okstra_ctl/code_review_target.py +79 -25
- package/runtime/python/okstra_ctl/conformance.py +61 -0
- package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
- package/runtime/python/okstra_ctl/correction_round.py +19 -13
- package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
- package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +100 -2
- package/runtime/python/okstra_ctl/generated_input.py +21 -0
- package/runtime/python/okstra_ctl/ids.py +1 -41
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
- package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
- package/runtime/python/okstra_ctl/locks.py +28 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +17 -1
- package/runtime/python/okstra_ctl/paths.py +84 -31
- package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
- package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
- package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
- package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
- package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
- package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
- package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
- package/runtime/python/okstra_ctl/process_group.py +26 -3
- package/runtime/python/okstra_ctl/qa_commands.py +7 -2
- package/runtime/python/okstra_ctl/qa_procedures.py +60 -17
- package/runtime/python/okstra_ctl/recap.py +1 -2
- package/runtime/python/okstra_ctl/render.py +10 -2
- package/runtime/python/okstra_ctl/report_finalize.py +3 -3
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
- package/runtime/python/okstra_ctl/run.py +24 -20
- package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
- package/runtime/python/okstra_ctl/verification_capture.py +291 -0
- package/runtime/python/okstra_ctl/verification_conformance.py +182 -0
- package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
- package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
- package/runtime/python/okstra_ctl/verification_generation.py +248 -0
- package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +23 -2
- package/runtime/python/okstra_ctl/verification_inputs.py +161 -23
- package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
- package/runtime/python/okstra_ctl/verification_target.py +20 -5
- package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
- package/runtime/python/okstra_ctl/wizard/render.py +2 -1
- package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
- package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
- package/runtime/python/okstra_ctl/worker_runner.py +1 -1
- package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
- package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
- package/runtime/skills/okstra-code-review/SKILL.md +84 -48
- package/runtime/skills/okstra-code-review/references/census-rules.md +10 -4
- package/runtime/skills/okstra-code-review/references/review-calibration.md +7 -4
- package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +6 -6
- package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
- package/runtime/skills/okstra-setup/SKILL.md +2 -3
- package/runtime/validators/validate-run.py +118 -52
- package/docs/cli.md +0 -1060
- package/docs/container.md +0 -100
- package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
- package/docs/performance-improvement-plan-v2.md +0 -369
- package/runtime/python/okstra_ctl/container.py +0 -702
- package/runtime/python/okstra_ctl/rollup.py +0 -241
- package/runtime/python/okstra_ctl/usage_report.py +0 -362
- package/runtime/skills/okstra-container-build/SKILL.md +0 -139
- package/runtime/skills/okstra-inspect/SKILL.md +0 -100
- package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
- package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
- package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
- package/runtime/skills/okstra-inspect/facets/history.md +0 -86
- package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
- package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
- package/runtime/skills/okstra-inspect/facets/report.md +0 -57
- package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
- package/runtime/skills/okstra-inspect/facets/status.md +0 -163
- package/runtime/skills/okstra-inspect/facets/time.md +0 -57
- package/runtime/skills/okstra-rollup/SKILL.md +0 -75
- package/runtime/skills/okstra-usage/SKILL.md +0 -71
|
@@ -126,7 +126,7 @@ Follow this protocol exactly:
|
|
|
126
126
|
|
|
127
127
|
0. Version-selected schemas describe what the reducer reads: `schemas/convergence-groups-v1.0.schema.json` accepts only legacy groups, `schemas/convergence-groups-v2.0.schema.json` accepts only explicit v2 execution identity, and `schemas/convergence-round-results-v1.0.schema.json` feeds step 4's `apply-round --results`. `schemas/convergence-critic-results-v1.0.schema.json` is a fourth shape but **not** a reducer input — it describes the critic worker's own result document. Step 6's `apply-critic-gaps --results` takes the coverage batch you assemble from those candidates plus each analyser's vote (`{schemaVersion, taskKey, mode, provider, modelExecutionValue, dispatches[], gaps[]}`, spelled out in §"Coverage critic pass" §"State"); feeding the critic document straight in is rejected, by design. `okstra convergence example --kind <groups|round-results|critic-results>` prints a deterministic valid v1 instance of each and writes only JSON to stdout.
|
|
128
128
|
1. Run `okstra convergence seed --groups <groups> --run-manifest <current-run-manifest> --work-state <work> --final-state <final> --migration-dir <state/migrations>` for a v2 worker roster. `--run-manifest` must be the exact current manifest named by the groups document's `runManifestPath`; a previous run from the same task is not interchangeable. `seed` refuses a grouping that cites a worker whose initial attempt the mutation audit discarded (`contract-failed-unattributed`, `mutation-present-unresolved`) — the result file is still on disk, but the ledger says it was never accepted. Re-dispatch that worker as a new invocation and cite the new result, or leave it out of the grouping. **Enforced:** `discarded_worker_errors` in `scripts/okstra_ctl/convergence_provenance.py`, called by `_seed`. Omit the flag for a legacy v1 roster. A `reuse-final` action means validate the existing final and continue to Phase 6. `create-work`, `resume-work`, and `restart-round0` continue with planning.
|
|
129
|
-
2. Run `okstra convergence plan-round --work-state <work> --plan <round-plan>`. This is read-only with respect to the working state. Its stdout JSON carries `round` and `inputQueueSize`; on a `dispatch` plan the round's `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` line copies those two values — never count the queue by hand. **Enforced:** `_plan_round` in `scripts/okstra_ctl/convergence.py`,
|
|
129
|
+
2. Run `okstra convergence plan-round --work-state <work> --plan <round-plan>`. This is read-only with respect to the working state. Its stdout JSON carries `round` and `inputQueueSize`; on a `dispatch` plan the round's `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` line copies those two values — never count the queue by hand. **Enforced:** `_plan_round` in `scripts/okstra_ctl/convergence.py`, the retired Python suite.
|
|
130
130
|
3. Every plan carries `dispatchable`: `true` on an `action: "dispatch"` plan, `false` on an `action: "finalize"` plan. When the plan action is `dispatch`, create exactly one reverify prompt for each `dispatches[]` row and dispatch it through the selected runtime adapter. Its findings are exactly that row's `findingIds`.
|
|
131
131
|
4. Run `okstra convergence collect-results --plan <round-plan> --result <worker>=<path>… --run-manifest <current-run-manifest> --output convergence-round-<N>-results-<task-type>-<seq>.json`. Each planned worker's terminal outcome and `durationMs` come from the manifest's attempt ledger, not from the lead: an attempt still `started` refuses the collect — run `okstra team await` first so the attempt closes — and a worker whose attempt did not close `ok` cannot contribute a vote even if its result file exists. **Enforced:** `_dispatch_rows_from_manifest` in `scripts/okstra_ctl/convergence.py`. Then run `okstra convergence apply-round --work-state <work> --plan <round-plan> --results <round-results>`.
|
|
132
132
|
5. Repeat `plan-round` and `apply-round` until the plan action is `finalize`. A `finalize` plan is **never dispatched**: it carries `dispatchable: false`, an empty `dispatches[]`, and a `note` naming the next command. Its `round` is only the `<N>` in `convergence-round-<N>-plan-<task-type>-<seq>.json` — not a round to run — so do not open reverify workers for it. **Enforced:** `okstra convergence apply-round` refuses a non-dispatch plan and returns the gate's closing reason with the remedy (`scripts/okstra_ctl/convergence_engine.py` `apply_round_results`).
|
|
@@ -573,7 +573,7 @@ For `runner=native-session`, use only `hostModelValue`; for
|
|
|
573
573
|
`enforcementMode=host-native-spec-link-gate` and the metadata path. If the
|
|
574
574
|
persisted assignment or either model value required by its runner is absent,
|
|
575
575
|
record `critic-skipped: model-unresolved`; never resolve a replacement model.
|
|
576
|
-
Result path: `runs/<task-type>/worker-results/<provider>-worker-critic-<task-type>-<seq>.md`, where `<seq>` is the run manifest's `runSequencesByCategory.workerResults` — the analysers' result seq, which
|
|
576
|
+
Result path: `runs/<task-type>/worker-results/<provider>-worker-critic-<task-type>-<seq>.md`, where `<seq>` is the run manifest's `runSequencesByCategory.workerResults` — the analysers' result seq, which equals the run sequence for a run prepared with one seq for all categories and may differ for an older run. `okstra convergence critic-verify-prompt` reads the critic result from the latest `ok` attempt of the `critic` dispatch in the run manifest and falls back to this name only when no such attempt is recorded (`_settled_critic_result` in `scripts/okstra_ctl/convergence.py`).
|
|
577
577
|
|
|
578
578
|
**What the generated critic task-instructions file contains.** A critic dispatch
|
|
579
579
|
is not a reverify dispatch: `dispatchKind = "critic"` keeps
|
|
@@ -597,7 +597,7 @@ dispatch will reject). The rest of the body is:
|
|
|
597
597
|
- the two mandates below, including the `duplicateOf` declaration rule.
|
|
598
598
|
|
|
599
599
|
The lead writes none of it and edits none of it. **Enforced:**
|
|
600
|
-
|
|
600
|
+
the retired Python suite
|
|
601
601
|
`test_generated_critic_seed_satisfies_the_real_dispatch_checks` runs the
|
|
602
602
|
generated body through the same two checks the dispatch runs. A hand-edited file
|
|
603
603
|
that drops either line fails `okstra team dispatch --dispatch-kind critic ...`
|
|
@@ -609,7 +609,7 @@ gate") rather than editing the published prompt.
|
|
|
609
609
|
|
|
610
610
|
The `-worker-` token is load-bearing, not decoration: the critic prompt carries the same generated anchor headers as every other worker ([team-contract](./team-contract.md) §"Worker prompts"), and its `**Audit sidecar path:**` comes from passing that result path through `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()`, which inserts `-audit-` after the token and raises without it. A `<provider>-critic-...` name leaves the lead choosing between breaking the contract and hand-inventing the sidecar name. Note that `originWorker` stays `"<provider>-critic"` — that is a worker id in the convergence state, not a filename, and the two do not have to match.
|
|
611
611
|
|
|
612
|
-
The critic prompt carries the full analysis contract those anchor headers belong to — worker preamble, error-contract path, audit sidecar, packet boundary — but it is **exempt from the initial-analysis equality group**. Initial analysis workers must receive byte-identical normalized bodies (`worker_prompt_contract.validate_analysis_prompt_set`), and a critic body is deliberately unlike them, so `okstra_ctl.worker_prompt_policy.resolve_prompt_plan` resolves `dispatchKind = "critic"` to `equality_group = None` while keeping `audience = "analysis"`. Never reshape a critic prompt to match the initial one to satisfy that check — matching it would delete the pass. **Enforced:**
|
|
612
|
+
The critic prompt carries the full analysis contract those anchor headers belong to — worker preamble, error-contract path, audit sidecar, packet boundary — but it is **exempt from the initial-analysis equality group**. Initial analysis workers must receive byte-identical normalized bodies (`worker_prompt_contract.validate_analysis_prompt_set`), and a critic body is deliberately unlike them, so `okstra_ctl.worker_prompt_policy.resolve_prompt_plan` resolves `dispatchKind = "critic"` to `equality_group = None` while keeping `audience = "analysis"`. Never reshape a critic prompt to match the initial one to satisfy that check — matching it would delete the pass. **Enforced:** the retired Python suite pins both directions — the critic is exempt, and two mismatched *initial* prompts still fail.
|
|
613
613
|
|
|
614
614
|
The critic prompt seeds the consolidated findings and asks for two things only — coverage gaps and unrequested work. The second half exists because every other scope check in the lifecycle runs *later*: the plan-body `P-Opt-*` verdict judges options this phase has not authored yet (report-writer writes the plan in Phase 6), and the `implementation` verifier judges a diff. Here the unit is a **finding**, which is the input those stages build on — catching unrequested work while it is still a finding is the cheapest place to catch it at all.
|
|
615
615
|
|
|
@@ -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
|
-
|
|
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:**
|
|
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:**
|
|
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`,
|
|
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`,
|
|
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:**
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
649
|
-
- Otherwise →
|
|
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).
|
|
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`;
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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`.
|
|
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
|
|
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
|
-
|
|
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=
|
|
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:
|
|
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
|
|
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", "")),
|