okstra 0.167.0 → 0.169.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 (102) hide show
  1. package/README.md +6 -5
  2. package/docs/architecture/storage-model.md +57 -1
  3. package/docs/architecture.md +70 -2
  4. package/docs/cli.md +8 -4
  5. package/docs/for-ai/skills/okstra-code-review.md +3 -2
  6. package/docs/for-ai/skills/okstra-schedule-gen.md +3 -1
  7. package/docs/pr-template-usage.md +10 -6
  8. package/docs/project-structure-overview.md +14 -11
  9. package/package.json +1 -1
  10. package/runtime/BUILD.json +2 -2
  11. package/runtime/agents/workers/claude-worker.md +6 -5
  12. package/runtime/agents/workers/report-writer-worker.md +9 -4
  13. package/runtime/agents/workers/translator-worker.md +6 -4
  14. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +27 -1
  15. package/runtime/prompts/coding-preflight/clean-code.md +13 -0
  16. package/runtime/prompts/duties/acceptance-critic.md +24 -0
  17. package/runtime/prompts/duties/acceptance-verifier.md +24 -0
  18. package/runtime/prompts/duties/analysis-worker.md +24 -0
  19. package/runtime/prompts/duties/code-reviewer.md +24 -0
  20. package/runtime/prompts/duties/common.md +35 -0
  21. package/runtime/prompts/duties/implementation-executor.md +24 -0
  22. package/runtime/prompts/duties/implementation-verifier.md +24 -0
  23. package/runtime/prompts/duties/lead.md +24 -0
  24. package/runtime/prompts/duties/report-writer.md +24 -0
  25. package/runtime/prompts/duties/reverification-worker.md +24 -0
  26. package/runtime/prompts/duties/schedule-verifier.md +24 -0
  27. package/runtime/prompts/duties/scope-critic.md +24 -0
  28. package/runtime/prompts/duties/translator.md +24 -0
  29. package/runtime/prompts/lead/convergence.md +51 -7
  30. package/runtime/prompts/lead/okstra-lead-contract.md +10 -20
  31. package/runtime/prompts/lead/plan-body-verification.md +16 -1
  32. package/runtime/prompts/lead/report-writer.md +20 -5
  33. package/runtime/prompts/lead/team-contract.md +13 -13
  34. package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
  35. package/runtime/prompts/profiles/_implementation-diff-review.md +3 -1
  36. package/runtime/prompts/profiles/_implementation-executor.md +1 -1
  37. package/runtime/prompts/profiles/_implementation-verifier.md +3 -1
  38. package/runtime/prompts/profiles/implementation.md +4 -2
  39. package/runtime/python/okstra_ctl/adapters/hosts/antigravity/adapter.py +6 -0
  40. package/runtime/python/okstra_ctl/adapters/hosts/antigravity/relay.md +3 -2
  41. package/runtime/python/okstra_ctl/adapters/hosts/capability_adapter.py +8 -0
  42. package/runtime/python/okstra_ctl/adapters/hosts/claude-code/adapter.py +33 -0
  43. package/runtime/python/okstra_ctl/adapters/hosts/claude-code/relay.md +13 -12
  44. package/runtime/python/okstra_ctl/adapters/hosts/codex/adapter.py +6 -0
  45. package/runtime/python/okstra_ctl/adapters/hosts/codex/relay.md +3 -2
  46. package/runtime/python/okstra_ctl/adapters/hosts/external/adapter.py +2 -0
  47. package/runtime/python/okstra_ctl/adapters/hosts/external/relay.md +3 -3
  48. package/runtime/python/okstra_ctl/adapters/hosts/grok/adapter.py +6 -0
  49. package/runtime/python/okstra_ctl/adapters/hosts/grok/relay.md +2 -1
  50. package/runtime/python/okstra_ctl/adapters/hosts/kimi/adapter.py +6 -0
  51. package/runtime/python/okstra_ctl/adapters/hosts/kimi/relay.md +2 -1
  52. package/runtime/python/okstra_ctl/agent_invocation.py +1502 -0
  53. package/runtime/python/okstra_ctl/agent_prompt_cli.py +788 -0
  54. package/runtime/python/okstra_ctl/codex_dispatch.py +2 -107
  55. package/runtime/python/okstra_ctl/context_cost.py +46 -5
  56. package/runtime/python/okstra_ctl/dispatch_core.py +312 -37
  57. package/runtime/python/okstra_ctl/dispatch_state.py +461 -36
  58. package/runtime/python/okstra_ctl/doctor.py +150 -16
  59. package/runtime/python/okstra_ctl/entrypoints/hosts.py +87 -9
  60. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +214 -23
  61. package/runtime/python/okstra_ctl/path_hints.py +26 -0
  62. package/runtime/python/okstra_ctl/paths.py +20 -0
  63. package/runtime/python/okstra_ctl/ports/__init__.py +8 -0
  64. package/runtime/python/okstra_ctl/ports/host.py +3 -0
  65. package/runtime/python/okstra_ctl/ports/host_model.py +60 -0
  66. package/runtime/python/okstra_ctl/pr_template.py +3 -6
  67. package/runtime/python/okstra_ctl/registry/host_registry.py +5 -0
  68. package/runtime/python/okstra_ctl/render.py +217 -12
  69. package/runtime/python/okstra_ctl/report_finalize.py +44 -0
  70. package/runtime/python/okstra_ctl/run.py +368 -51
  71. package/runtime/python/okstra_ctl/session.py +16 -12
  72. package/runtime/python/okstra_ctl/team.py +11 -11
  73. package/runtime/python/okstra_ctl/worker_dispatch.py +104 -0
  74. package/runtime/python/okstra_ctl/worker_prompt_body.py +5 -38
  75. package/runtime/python/okstra_ctl/worker_prompt_contract.py +32 -2
  76. package/runtime/python/okstra_ctl/worker_prompt_policy.py +38 -1
  77. package/runtime/skills/okstra-code-review/SKILL.md +22 -3
  78. package/runtime/skills/okstra-run/SKILL.md +16 -1
  79. package/runtime/skills/okstra-schedule-gen/SKILL.md +15 -1
  80. package/runtime/templates/implementation-worker-preamble.md +0 -10
  81. package/runtime/templates/report-writer-prompt-preamble.md +0 -9
  82. package/runtime/templates/reports/settings.template.json +0 -11
  83. package/runtime/templates/worker-prompt-preamble.md +0 -10
  84. package/runtime/validators/lib/fixtures.sh +93 -0
  85. package/runtime/validators/lib/validate-assets.sh +0 -8
  86. package/runtime/validators/validate-run.py +182 -0
  87. package/src/cli-registry.mjs +14 -0
  88. package/src/commands/execute/agent-prompt.mjs +25 -0
  89. package/src/commands/execute/codex-dispatch.mjs +6 -63
  90. package/src/commands/execute/worker-dispatch.mjs +76 -0
  91. package/src/commands/lifecycle/doctor.mjs +18 -3
  92. package/src/commands/lifecycle/install.mjs +33 -15
  93. package/src/commands/lifecycle/uninstall.mjs +4 -3
  94. package/src/lib/install-assets.mjs +9 -0
  95. package/runtime/agents/workers/antigravity-worker.md +0 -259
  96. package/runtime/agents/workers/codex-worker.md +0 -259
  97. package/runtime/agents/workers/grok-worker.md +0 -259
  98. package/runtime/agents/workers/kimi-worker.md +0 -259
  99. package/runtime/prompts/coding-preflight/scripts/preedit-check.sh +0 -79
  100. package/runtime/templates/operating-standard.md +0 -22
  101. package/src/lib/worker-agent-render.mjs +0 -50
  102. /package/runtime/templates/{prd → pr}/pr-body.template.md +0 -0
@@ -314,6 +314,19 @@ A new mock, state setter, or repository branch that no test calls is unfinished
314
314
 
315
315
  A change to memory use, concurrency, batching, or stream handling is not covered by a functional test that passes on a small input. Add a test that pins the bound the change claims to hold — peak size, concurrent count, chunk count.
316
316
 
317
+ ## Trace what this change can do wrong
318
+
319
+ The rules above name defect shapes. A defect with no name on this list is still a defect, and the ones that reach production usually have no name — they are ordinary code that produces a wrong result for one input nobody walked.
320
+
321
+ For every source file this change touches, follow the paths the change creates or alters to their end, and state where a wrong result comes out:
322
+
323
+ - **error** — what the caller sees when each new call fails, and whether that is distinguishable from the other failures it must be told apart from.
324
+ - **partial** — the change succeeded halfway; what is left written, and what the next run sees.
325
+ - **concurrent** — something else is still writing, or the deadline fired and the work did not stop.
326
+ - **selection** — when several candidates fail, which one's evidence survives.
327
+
328
+ **A finding names the input or state that produces the wrong result.** *"If the archive yields no entries, line 42 reports success and stores an empty result"* is a finding. Code that works as written is `clean`, however you would have written it differently: alternative structures, guards for states no caller can reach, extra tests for covered paths, and "consider extracting / renaming / memoizing" are improvements, not findings. A real failure that is small and cheap to fix is still a finding.
329
+
317
330
  ## No magic numbers
318
331
 
319
332
  Replace hardcoded values with named constants.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: acceptance-critic
3
+ version: 1
4
+ kind: role
5
+ appliesTo: acceptance-critic
6
+ ---
7
+
8
+ # Acceptance Critic Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Find new candidate defects that could prevent acceptance.
13
+
14
+ ## Required conduct
15
+
16
+ Challenge the strongest completion claims and produce only distinct, evidence-backed candidates.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not repeat an existing defect, lower the acceptance standard, or make the final acceptance decision.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ Name the completion claim that cannot be challenged and the evidence needed to evaluate it.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: acceptance-verifier
3
+ version: 1
4
+ kind: role
5
+ appliesTo: acceptance-verifier
6
+ ---
7
+
8
+ # Acceptance Verifier Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Independently decide whether the declared acceptance criteria and deliverables are satisfied.
13
+
14
+ ## Required conduct
15
+
16
+ Evaluate every criterion against current evidence and return an explicit pass, fail, or blocked judgment.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not infer acceptance from effort, intent, or unrelated passing checks.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ List each undecidable criterion and the exact missing artifact or observation.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: analysis-worker
3
+ version: 1
4
+ kind: role
5
+ appliesTo: analysis-worker
6
+ ---
7
+
8
+ # Analysis Worker Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Produce an independent, evidence-backed analysis of the assigned question.
13
+
14
+ ## Required conduct
15
+
16
+ Inspect the assigned sources, cite concrete evidence, and state uncertainty or counterevidence.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not imitate another worker's expected answer, coordinate conclusions, or expand the assigned question.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ Identify the unavailable evidence, the checks attempted, and the precise effect on the requested conclusion.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: code-reviewer
3
+ version: 1
4
+ kind: role
5
+ appliesTo: code-reviewer
6
+ ---
7
+
8
+ # Code Reviewer Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Return a verdict for every census cell assigned to the review.
13
+
14
+ ## Required conduct
15
+
16
+ Inspect every cell, preserve its identity, and support each finding or clean verdict with code evidence.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not reinterpret, merge, omit, or add census cells.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ Identify each cell that cannot be evaluated and the missing source, diff, or standard.
@@ -0,0 +1,35 @@
1
+ ---
2
+ id: common
3
+ version: 1
4
+ kind: common
5
+ ---
6
+
7
+ # Common Agent Duty Contract
8
+
9
+ ## Assignment fidelity
10
+
11
+ Perform the assigned work exactly as scoped. Do not silently broaden, narrow, replace, or reinterpret the assignment.
12
+
13
+ ## Completion discipline
14
+
15
+ Carry the assignment through every required check and deliverable. Do not stop at a plausible partial result.
16
+
17
+ ## Evidence first
18
+
19
+ Base conclusions on inspected inputs and observed results. Distinguish verified facts from inferences and unknowns.
20
+
21
+ ## Required inputs
22
+
23
+ Read every required input before acting. Report a missing, unreadable, or contradictory input instead of inventing its contents.
24
+
25
+ ## Authority and scope
26
+
27
+ Use only the permissions and project scope granted by the invocation. Do not perform unrelated or outward-facing actions.
28
+
29
+ ## Conflict handling
30
+
31
+ When instructions conflict, preserve safety and evidence, identify the exact conflict, and return it to the responsible lead.
32
+
33
+ ## Completion honesty
34
+
35
+ Do not report unperformed work as complete. Name remaining work, failed checks, and blockers precisely.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: implementation-executor
3
+ version: 1
4
+ kind: role
5
+ appliesTo: implementation-executor
6
+ ---
7
+
8
+ # Implementation Executor Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Be the sole change author for exactly one approved implementation stage.
13
+
14
+ ## Required conduct
15
+
16
+ Follow the approved stage, preserve concurrent work, test each behavior, and report every changed file and verification result.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not implement another stage, rewrite the plan, or delegate edits to a verifier.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ Name the stage item, the blocking dependency or failing evidence, and the unchanged state left behind.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: implementation-verifier
3
+ version: 1
4
+ kind: role
5
+ appliesTo: implementation-verifier
6
+ ---
7
+
8
+ # Implementation Verifier Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Independently reproduce quality-assurance checks for the assigned implementation.
13
+
14
+ ## Required conduct
15
+
16
+ Read project files without changing them, run the assigned checks, and distinguish reproduced results from executor claims.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not edit project files, repair failures, or approve work on the executor's assertion alone.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ Name the check that could not run, its missing prerequisite, and which acceptance claim remains unverified.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: lead
3
+ version: 1
4
+ kind: role
5
+ appliesTo: lead
6
+ ---
7
+
8
+ # Lead Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Own assignment, convergence, phase gates, and the final completion decision.
13
+
14
+ ## Required conduct
15
+
16
+ Give each agent a bounded assignment, reconcile claims against evidence, and require every gate before declaring completion. Prefer stronger evidence over majority agreement.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not let workers choose the roster, hide dissent, or treat vote count as proof.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ Name the blocked gate, the evidence already gathered, and the smallest decision or input needed to proceed.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: report-writer
3
+ version: 1
4
+ kind: role
5
+ appliesTo: report-writer
6
+ ---
7
+
8
+ # Report Writer Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Structure the settled run state into the required report format.
13
+
14
+ ## Required conduct
15
+
16
+ Preserve verdicts, evidence, uncertainty, and required sections exactly as supplied.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not perform new analysis, retry verification, or change an established verdict.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ Identify the missing settled input or schema requirement and the report section it prevents.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: reverification-worker
3
+ version: 1
4
+ kind: role
5
+ appliesTo: reverification-worker
6
+ ---
7
+
8
+ # Reverification Worker Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Return a verdict for every assigned convergence item using the supplied evidence.
13
+
14
+ ## Required conduct
15
+
16
+ Address each assigned item exactly once and explain the evidence that changes or preserves its status.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not invent new items, widen the review scope, or omit an assigned item.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ Mark the affected item blocked and state the single missing fact or artifact required for a verdict.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: schedule-verifier
3
+ version: 1
4
+ kind: role
5
+ appliesTo: schedule-verifier
6
+ ---
7
+
8
+ # Schedule Verifier Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Independently evaluate the draft schedule's consistency and executable independence.
13
+
14
+ ## Required conduct
15
+
16
+ Check dependencies, ordering, ownership, and collision risks from the supplied schedule and source plan.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not rely on unstated lead reasoning, rewrite the schedule, or invent missing work.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ Name the schedule relationship that cannot be evaluated and the missing plan fact required to decide it.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: scope-critic
3
+ version: 1
4
+ kind: role
5
+ appliesTo: scope-critic
6
+ ---
7
+
8
+ # Scope Critic Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Find both omitted required work and work that was performed without being requested.
13
+
14
+ ## Required conduct
15
+
16
+ Compare the request, accepted scope, and deliverables in both directions and cite each mismatch.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not turn preferences or speculative improvements into scope defects.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ Identify which scope source is unavailable or contradictory and which comparison cannot be completed.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: translator
3
+ version: 1
4
+ kind: role
5
+ appliesTo: translator
6
+ ---
7
+
8
+ # Translator Duty Contract
9
+
10
+ ## Responsibility
11
+
12
+ Translate only the designated sidecar while preserving the canonical source.
13
+
14
+ ## Required conduct
15
+
16
+ Preserve meaning, identifiers, code, paths, structure, and uncertainty without adding analysis.
17
+
18
+ ## Forbidden conduct
19
+
20
+ Do not edit the source of truth, translate unassigned files, or change a technical conclusion.
21
+
22
+ ## Blocked-state reporting
23
+
24
+ Name the ambiguous source passage and preserve it unchanged until the lead resolves it.
@@ -224,6 +224,31 @@ Design intent: one `counter-evidence` refute denies a claim consensus (it cannot
224
224
 
225
225
  ## Re-verification Dispatch
226
226
 
227
+ ### Invocation materialization gate (BLOCKING)
228
+
229
+ For every finding reverify row and critic-gap verification row, first write a
230
+ call-specific task-instructions file under the current run's `state/`
231
+ directory. Then run `okstra agent-prompt materialize` with `--audience
232
+ reverification-worker`, `--assignment-ref reverify/<workerId>`, the exact
233
+ `--worker-id`, `--dispatch-kind reverify-r<N>`, and the authorized
234
+ prompt/result/audit paths. The returned `promptPath` is the only body that may
235
+ be dispatched; do not append role prose or reconstruct model headers after
236
+ materialization.
237
+
238
+ Run `okstra agent-prompt verify --run-manifest <path> --metadata
239
+ <metadataPath> --json` immediately before dispatch. A failed verification is a
240
+ pre-dispatch contract failure. For `runner=native-session`, pass only the
241
+ returned `hostModelValue` to the host model argument. For
242
+ `runner=cli-wrapper`, invoke `okstra worker-dispatch` and let it consume the
243
+ returned `modelExecutionValue`; never pass that value as a native-host model
244
+ token. Before a host-native call, run `okstra agent-prompt record-dispatch`
245
+ with the project root, run manifest, metadata path, and
246
+ `--enforcement-mode host-native-spec-link-gate`. After its Result Path exists,
247
+ run `okstra agent-prompt link-result` with the same run manifest,
248
+ `--dispatch-id <invocationId>:attempt-1`, and that result path before reading
249
+ the result. This link proves that the accepted result belongs to a verified
250
+ call specification; it does not prove which bytes the host primitive delivered.
251
+
227
252
  ### Sponsorship Optimization
228
253
 
229
254
  For each persisted round plan, build exactly one prompt per `dispatches[]` row and call `redispatch_worker(assignment, prompt, reason)` once through the selected runtime adapter. The prompt contains exactly that row's `findingIds` in plan order and MUST NOT add, remove, or reorder findings. This excludes Section 6, every resolved finding, and every finding owned by the receiving origin worker because none can appear in the engine row. The assignment, model, prompt path, Result Path, worker-results path, errors paths, and `dispatchKind` come from the current run artifacts. Every reverify is a fresh one-shot session.
@@ -254,7 +279,7 @@ Assigned worker prompt history path: <Project Root>/<Prompt History Path>
254
279
 
255
280
  Before dispatch, materialize `**Audit sidecar path:**` by passing the exact reverify `**Result Path:**` through `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()` and resolving that project-relative result against `**Project Root:**`. Write the resulting absolute path into the header. The lead MUST NOT construct the audit filename from a role, task type, round, or sequence independently.
256
281
 
257
- The two errors paths carry the same absolute values the lead forwarded in the initial Phase 4 dispatch for that role (source: the launch prompt's `## Run Logs (error-log wiring)` section). Omitting either one makes a CLI-wrapper worker return `<WORKER>_ERRORS_PATH_MISSING` before it invokes its CLI — the path-delivery contract in [team-contract](./team-contract.md) "Error reporting" is not relaxed for reverify, because a reverify dispatch can fail the same way an initial dispatch can.
282
+ The two errors paths carry the same absolute values the lead forwarded in the initial Phase 4 dispatch for that role (source: the launch prompt's `## Run Logs (error-log wiring)` section). Omitting either one makes `worker-dispatch` reject the CLI invocation before it starts the provider process — the path-delivery contract in [team-contract](./team-contract.md) "Error reporting" is not relaxed for reverify.
258
283
 
259
284
  Relative to the Phase 4 anchor set rendered by `okstra_ctl.worker_prompt_headers.worker_prompt_headers()`, a reverify prompt adds `**Model:**` and drops two anchors whose targets lightweight mode never reads: `**Worker Preamble Path:**` and `**Coding preflight pack:**`.
260
285
 
@@ -323,7 +348,7 @@ This is the single largest avoidable cost in `requirements-discovery`, `error-an
323
348
  ### Lightweight Re-verification Prompt
324
349
 
325
350
  ```
326
- You are <worker-role> performing re-verification for <task-key> (round <N>).
351
+ Perform re-verification for <task-key> (round <N>).
327
352
 
328
353
  ## Instructions
329
354
 
@@ -365,7 +390,7 @@ For each finding, respond as:
365
390
  Used instead of the lightweight/full-reanalysis prompt when `config.adversarial == true`. The required anchor headers (§"Required reverify-prompt anchor headers") are identical. The `[Required reading]` clause is suppressed; only the cited-evidence paths of the items under attack are injected (see §"Adversarial Verification Mode" → Scoped full-reanalysis).
366
391
 
367
392
  ```
368
- You are <worker-role> performing ADVERSARIAL re-verification for <task-key> (round <N>).
393
+ Perform ADVERSARIAL re-verification for <task-key> (round <N>).
369
394
 
370
395
  ## Instructions
371
396
 
@@ -416,7 +441,7 @@ UNVERIFIABLE is **not** `verification-error`. A verifier that opened the evidenc
416
441
  ### Full Re-analysis Re-verification Prompt
417
442
 
418
443
  ```
419
- You are <worker-role> performing deep re-verification for <task-key> (round <N>).
444
+ Perform deep re-verification for <task-key> (round <N>).
420
445
 
421
446
  ## Instructions
422
447
 
@@ -550,7 +575,17 @@ The critic input is the Round 0 consolidated finding list. Reverify rounds only
550
575
  - **Gap verification + merge**: only after BOTH the finding-convergence loop has exited AND the critic result is collected, and BEFORE the Phase 6 report-writer dispatch. If the loop exited `aborted-non-result`, do NOT dispatch a gap-verification round — record every gap in `unverifiedGaps[]` per §"Gap verification".
551
576
 
552
577
  ### Dispatch (fresh one-shot)
553
- Dispatch one fresh pass to `config.critic.provider` through `redispatch_worker`, with `model = config.critic.modelExecutionValue` and `dispatchKind = "critic"`. If the model value is empty, record `critic-skipped: model-unresolved`; never dispatch without a model. Result path: `runs/<task-type>/worker-results/<provider>-worker-critic-<task-type>-<seq>.md`.
578
+ Write the critic-only task instructions, then run `okstra agent-prompt
579
+ materialize` with `--audience scope-critic`, `--assignment-ref critic/scope`,
580
+ the critic worker ID, and `--dispatch-kind critic`. Verify the returned
581
+ `metadataPath` before dispatch and use its `promptPath` without modification.
582
+ For `runner=native-session`, use only `hostModelValue`; for
583
+ `runner=cli-wrapper`, use `okstra worker-dispatch`, which consumes
584
+ `modelExecutionValue`. Record host-native linkage with
585
+ `enforcementMode=host-native-spec-link-gate` and the metadata path. If the
586
+ persisted assignment or either model value required by its runner is absent,
587
+ record `critic-skipped: model-unresolved`; never resolve a replacement model.
588
+ Result path: `runs/<task-type>/worker-results/<provider>-worker-critic-<task-type>-<seq>.md`.
554
589
 
555
590
  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.
556
591
 
@@ -567,7 +602,7 @@ Required reading before proposing a gap or an over-scope candidate:
567
602
  Operational guardrails are not task requirements. A gap must trace to a brief requirement, an analysis-packet scope item, a source path the packet authorizes, or an evidence claim in a worker result. Do NOT infer missing verification from a one-line summary; open the named result and audit sidecar first.
568
603
 
569
604
  ```
570
- You are the scope critic for <task-key>. Below are the consolidated findings the
605
+ Inspect scope coverage for <task-key>. Below are the consolidated findings the
571
606
  workers produced. Your job has exactly two halves. Answer both.
572
607
 
573
608
  (1) MISSING — name what nobody covered:
@@ -617,10 +652,19 @@ The asymmetry is deliberate and runs the opposite way from the coverage half: a
617
652
 
618
653
  The `final-verification` phase uses the same fresh one-shot `redispatch_worker` pattern and the same dispatch timing as §"Coverage critic pass" §"When" (provider + `config.critic.modelExecutionValue` from the `convergence.critic` block; default off; same model-unresolved skip rule) — the delivered work the critic inspects is likewise fixed before the reverify round starts. Only the prompt, the verification semantics, and the output sink differ — final-verification's findings are defects/blockers, so the critic acts as an **acceptance devil's advocate** (find reasons NOT to accept), and its candidate blockers are NEVER dropped (that would suppress real defects).
619
654
 
655
+ Before that call, write the acceptance-only task instructions and run `okstra
656
+ agent-prompt materialize` with `--audience acceptance-critic`,
657
+ `--assignment-ref critic/acceptance`, the critic worker ID, and
658
+ `--dispatch-kind critic`. Verify the returned `metadataPath`, dispatch only the
659
+ returned `promptPath`, and select `hostModelValue` for a native host or
660
+ `modelExecutionValue` through `okstra worker-dispatch`. Native dispatch linkage
661
+ uses `enforcementMode=host-native-spec-link-gate`; it does not claim prompt
662
+ delivery was observed.
663
+
620
664
  ### Prompt
621
665
 
622
666
  ```
623
- You are the acceptance devil's advocate for <task-key>. The delivered work is about
667
+ Challenge acceptance for <task-key>. The delivered work is about
624
668
  to be judged for acceptance. Your ONLY job is to find reasons it should NOT be
625
669
  accepted — surface candidate acceptance BLOCKERS the verifiers may have missed:
626
670
  - requirements / acceptance points with no covering evidence,
@@ -1,15 +1,5 @@
1
1
  # Okstra Lead Contract
2
2
 
3
- ## Operating standard
4
-
5
- Work like a senior engineer who owns this result, not a commentator on it.
6
- - Evidence over assertion — back every claim with a file:line, or mark it an explicit assumption. Never state the unverified as fact.
7
- - Read before you reason — read each required input end to end; when you lack basis, write "insufficient evidence" instead of filling the gap plausibly.
8
- - Shortest sound path — chase the most likely cause first; don't re-verify what is settled or pad with restatement.
9
- - Decide, don't survey — when options exist, give the trade-off and one recommendation, not an exhaustive list.
10
- - Fit what's here — match the surrounding code and prose; size the response to the request.
11
- - Own the synthesis — weigh worker outputs on evidence, not consensus; a better-grounded dissent outranks the majority.
12
-
13
3
  ## Overview
14
4
 
15
5
  The lead orchestrates the selected AI workers against a prepared task bundle, collects their independent outputs, supervises convergence, and ensures the final report is produced. When `Report writer worker` is in the selected roster, that worker authors the final-report artifacts; the lead reviews and approves them. The lead never substitutes its own reasoning for a worker result and never bypasses a rostered report writer.
@@ -143,7 +133,7 @@ The sequence is fixed:
143
133
 
144
134
  **The lead never invents a model.** Every role's model is read from `task-manifest.json` → `resultContract.requiredWorkerRoles[*].modelExecutionValue` (and the lead model metadata). A missing assignment is a manifest defect, not a license to fall back — see [team-contract](./team-contract.md) "Model Assignment Rules". The manifest is always populated at run-prep time by the CLI, which seeds these values from `OKSTRA_DEFAULT_*_MODEL` (`scripts/okstra_ctl/run.py`).
145
135
 
146
- **Reading an assignment is not enough — the selected adapter must apply it at dispatch.** `dispatch_worker` receives the manifest assignment, and the selected runtime adapter maps `modelExecutionValue` to its native invocation without changing provider, role, or model. A missing/unsupported mapping is a pre-dispatch contract failure, never a silent fallback.
136
+ **Reading an assignment is not enough — the selected adapter must apply it at dispatch.** `dispatch_worker` receives the complete manifest assignment. The selected runtime adapter passes `hostModelValue` to a `runner=native-session` host primitive or `modelExecutionValue` to a `runner=cli-wrapper` provider process without changing provider, role, or model. A missing or unsupported runner-specific mapping is a pre-dispatch contract failure, never a silent fallback.
147
137
 
148
138
  The table below documents those prep-time seed values **for reference only** — it is NOT a lead-applied fallback:
149
139
 
@@ -152,19 +142,19 @@ The table below documents those prep-time seed values **for reference only** —
152
142
  | Lead role | opus | -- | runtime-specific role label; orchestration + convergence supervision + final-report review/approval |
153
143
  | Report writer worker | sonnet | report-writer-worker | `agents/workers/report-writer-worker.md` |
154
144
  | Claude worker | opus | claude-worker | `agents/workers/claude-worker.md` |
155
- | Codex worker | gpt-5.6-sol | codex-worker | generated from `agents/workers/_cli-wrapper-template.md` + `codex-worker.params.json` |
156
- | Antigravity worker | gemini-3.1-pro | antigravity-worker | generated from `agents/workers/_cli-wrapper-template.md` + `antigravity-worker.params.json` |
145
+ | Codex worker | gpt-5.6-sol | codex-worker | duty + task instructions composed per invocation; deterministic `worker-dispatch` execution |
146
+ | Antigravity worker | gemini-3.1-pro | antigravity-worker | duty + task instructions composed per invocation; deterministic `worker-dispatch` execution |
157
147
 
158
- All three analysis workers use dedicated agent definitions; Codex/Antigravity wrappers handle external CLI invocation internally; Claude worker runs as an in-process subagent with explicitly registered MCP tools so it does not fall back to `claude --mcp-cli` Bash invocations.
148
+ Each analysis assignment follows its recorded `runner`. `runner=native-session` uses the host's native subagent primitive after `host-native-spec-link-gate`; `runner=cli-wrapper` uses the deterministic `okstra worker-dispatch` process boundary after `core-pre-dispatch` verification. No LLM transport wrapper sits in front of a provider CLI.
159
149
 
160
150
  ### Implementation phase: Executor binding
161
151
 
162
152
  For `--task-type implementation` runs, the task bundle additionally pins one of `claude` / `codex` / `antigravity` as the Executor — the only worker permitted to mutate project files in that run. The binding is exposed in two canonical places:
163
153
 
164
- - `instruction-set/analysis-profile.md` — top "Executor binding" block (provider, displayName, workerAgent, model)
165
- - `runs/implementation/manifests/run-manifest-*.json` — `teamContract.executor` object (same fields plus `appliesTo: "implementation"`)
154
+ - `instruction-set/analysis-profile.md` — top "Executor binding" block (provider, display name, model, runner, and dispatch mode)
155
+ - `runs/implementation/manifests/run-manifest-*.json` — `teamContract.executor` object (the same binding plus `appliesTo: "implementation"`)
166
156
 
167
- Lead MUST dispatch Edit/Write-bearing work only through the `workerAgent` declared there. The other two providers still run as read-only verifiers in the same run; the executor's own provider is *also* dispatched separately as a verifier in a fresh CLI session, so the diff is reviewed context-isolated. Session isolation is the primary self-review safeguard — same-model executor and same-provider verifier is acceptable in distinct sessions. A different model variant (e.g. executor=opus / Claude verifier=sonnet) is recommended but not mandatory.
157
+ Lead MUST dispatch Edit/Write-bearing work only through that executor binding: use the host primitive with `hostModelValue` for `runner=native-session`, or `okstra worker-dispatch` with `modelExecutionValue` for `runner=cli-wrapper`. The other two providers still run as read-only verifiers in the same run; the executor's own provider is *also* dispatched separately as a verifier in a fresh session, so the diff is reviewed context-isolated. Session isolation is the primary self-review safeguard — same-model executor and same-provider verifier is acceptable in distinct sessions. A different model variant (e.g. executor=opus / Claude verifier=sonnet) is recommended but not mandatory.
168
158
 
169
159
  Executor is chosen at run-prep time via `--executor <claude|codex|antigravity>` (or `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`); the model used by the executor is taken from the corresponding worker model flag (`--claude-model` / `--codex-model` / `--antigravity-model`). For CLI-backed executors, the underlying file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --sandbox workspace-write`), not through the lead runtime's `write_artifact` operation.
170
160
 
@@ -267,7 +257,7 @@ The launch prompt's `## Run Logs (error-log wiring)` section gives Lead the reso
267
257
 
268
258
  Workers are contractually required to extract these two lines and abort with `<WORKER>_ERRORS_PATH_MISSING` if either is absent (see each worker definition's "Path extraction (BLOCKING)" block). Omitting these headers reproduces the historical bug where every run's `errors-<task-type>-<seq>.jsonl` stayed empty (workers had only template placeholders).
269
259
 
270
- After each worker terminates, BEFORE classifying its terminal status, verify the canonical result file exists at the absolute path resolved from the `**Result Path:**` header. If it is absent — or the wrapper sub-agent returned `CODEX_RESULT_MISSING` / `ANTIGRAVITY_RESULT_MISSING` — re-dispatch the SAME worker once with the byte-identical prompt. Only after the second attempt also misses may the role be classified `error` with `--message "result-missing after 1 retry"`. Full rules: [team-contract](./team-contract.md) "Lead Redispatch Policy on Result-Missing".
260
+ After each worker terminates, BEFORE classifying its terminal status, verify the canonical result file exists at the absolute path resolved from the `**Result Path:**` header. If it is absent — or the deterministic provider process returned `CODEX_RESULT_MISSING` / `ANTIGRAVITY_RESULT_MISSING` — re-dispatch the SAME worker once with the byte-identical prompt. Only after the second attempt also misses may the role be classified `error` with `--message "result-missing after 1 retry"`. Full rules: [team-contract](./team-contract.md) "Lead Redispatch Policy on Result-Missing".
271
261
 
272
262
  After each worker terminates (any terminal status), if its errors sidecar exists, dump it to the run error log using the same resolved paths from the launch prompt:
273
263
 
@@ -286,7 +276,7 @@ okstra error-log append-from-worker \
286
276
 
287
277
  For a lead-attributed event there is no value in the list above — the selected adapter names the lead identity to pass.
288
278
 
289
- For Codex/Antigravity wrappers: if the CLI returns non-zero, times out, or hits a rate limit, immediately call `append-observed` with the captured exit code, duration, message, and stderr excerpt. `append-observed` additionally requires `--phase`, `--command`, and `--command-kind`, so copy this form rather than trimming the one above:
279
+ For deterministic Codex/Antigravity provider processes: if the CLI returns non-zero, times out, or hits a rate limit, immediately call `append-observed` with the captured exit code, duration, message, and stderr excerpt. `append-observed` additionally requires `--phase`, `--command`, and `--command-kind`, so copy this form rather than trimming the one above:
290
280
 
291
281
  ```bash
292
282
  okstra error-log append-observed \
@@ -303,7 +293,7 @@ okstra error-log append-observed \
303
293
 
304
294
  Keep `--message` to the error actually observed — asserting that a sandbox or permission boundary blocked the call requires `--context-json` carrying `cause` plus both `causeEvidence` probes, and an unevidenced block claim in `--message` is rejected. If an `append-from-worker` dump is rejected for that reason, correct the offending sidecar entry and re-run the dump instead of skipping it: the dump aborts at the rejected entry, so every later entry in that sidecar never reaches the run log.
305
295
 
306
- The wrapper subagent records this through its selected adapter — Lead does NOT need to re-record. Token usage is not inferred from dispatch return values; call `collect_usage` at the start of Phase 7.
296
+ The deterministic dispatcher records this through its selected adapter — Lead does NOT need to re-record. Token usage is not inferred from dispatch return values; call `collect_usage` at the start of Phase 7.
307
297
 
308
298
  ## Phase 5.5: Convergence loop
309
299
 
@@ -181,6 +181,21 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
181
181
 
182
182
  ## Round protocol (single round at default `maxRounds=1`)
183
183
 
184
+ Before each verifier call, write one task-instructions file under the current
185
+ run's `state/` directory and run `okstra agent-prompt materialize` with
186
+ `--audience reverification-worker`,
187
+ `--assignment-ref reverify/<workerId>`, the exact `--worker-id`, and
188
+ `--dispatch-kind reverify-r<N>`. Run `okstra agent-prompt verify` against the
189
+ returned `metadataPath` before dispatch and use the returned `promptPath`
190
+ without modification. Native-session calls use only `hostModelValue`; before
191
+ the host primitive, run `okstra agent-prompt record-dispatch` with the project
192
+ root, run manifest, metadata path, and `--enforcement-mode
193
+ host-native-spec-link-gate`, then run `okstra agent-prompt link-result` with
194
+ `--dispatch-id <invocationId>:attempt-1` and the result path before parsing it;
195
+ CLI-wrapper calls go through `okstra worker-dispatch` and consume only
196
+ `modelExecutionValue`. A missing or invalid invocation contract blocks the
197
+ round before any host or provider process starts.
198
+
184
199
  1. Lead runs `okstra plan-items extract --data <data.json> --output <state>/plan-items-....json`, places the persisted `items[]` verbatim in every verifier prompt with the compact `subject` and lossless `payload`, then runs `okstra plan-items validate --data <data.json> --items <state>/plan-items-....json`. Dispatch only after that exact-match validation succeeds.
185
200
  2. For each analyser worker in the roster (`claude`, `codex`, and `antigravity` if opted in), lead constructs a reverify prompt using the template in §"Plan-body reverify prompt" below.
186
201
  3. Dispatch uses the same wrapper infrastructure as finding convergence, so the `--role-slug` is the same canonical `<role>-worker` that convergence uses — not a round-specific slug. Result file path: `runs/<task-type>/worker-results/<role>-worker-plan-verify-r<N>-implementation-planning-<seq>.md` (e.g. `codex-worker-plan-verify-r1-implementation-planning-003.md`). The `-worker-` token is load-bearing twice over: §"Plan-body reverify prompt" requires the same anchor headers as convergence, whose `**Audit sidecar path:**` is derived by `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()` inserting `-audit-` after that token — a slug without it makes the header underivable and the helper raises. Record each `planItems[].verdicts[].worker` as the same `<role>-worker` string, because provenance compares it to this filename's prefix. **Enforced:** `tests/contract/test_reverify_dispatch_anchors.py` derives the sidecar from the documented name and re-extracts the prefix the provenance resolver uses.
@@ -357,7 +372,7 @@ The [convergence](./convergence.md) §"Required reverify output contract"
357
372
  applies unchanged: append it verbatim after the response format below.
358
373
 
359
374
  ````
360
- You are <worker-role> performing plan-body verification for <task-key> (round 1).
375
+ Perform plan-body verification for <task-key> (round 1).
361
376
 
362
377
  ## Instructions
363
378
 
@@ -23,12 +23,13 @@ Two `frontmatter` approval fields are always emitted with their unset default
23
23
  ## Phase 6 dispatch template (Report writer worker)
24
24
 
25
25
  1. Resolve the Report writer worker assignment and all required prompt/result/error paths from the manifests.
26
- 2. Persist the exact prompt history with the required anchor headers and audience-specific reading list.
27
- 3. Emit the Phase 6 checkpoint.
28
- 4. Call `dispatch_worker(report_writer_assignment, prompt)` through the selected adapter.
29
- 5. Call `await_workers([handle])` and verify the data.json Result Path, rendered Markdown sibling, and worker-result pointer at Worker Result Path. Verify the separate heartbeat audit sidecar before accepting the run. **Enforced:** both dispatch adapters keep the three completion paths in `WorkerJob.completion_paths`, and `validators/validate_session_conformance.py` validates the audit sidecar.
26
+ 2. Write a call-specific task-instructions file containing the anchor headers and audience-specific reading list.
27
+ 3. Run `okstra agent-prompt materialize --audience report-writer --assignment-ref initial/report-writer --worker-id report-writer --dispatch-kind report-writer ...`, then run `okstra agent-prompt verify` against the returned `metadataPath`. Use the returned `promptPath` without appending role prose. A correction redispatch repeats this step with a fresh invocation ID and the same audience and assignment reference.
28
+ 4. Emit the Phase 6 checkpoint.
29
+ 5. For `runner=native-session`, first run `okstra agent-prompt record-dispatch` with the project root, run manifest, metadata path, and `--enforcement-mode host-native-spec-link-gate`, then call the host primitive with only the returned `hostModelValue`. After its result exists, run `okstra agent-prompt link-result` with `--dispatch-id <invocationId>:attempt-1` and the result path before accepting it. For `runner=cli-wrapper`, call `okstra worker-dispatch --workers report-writer`, which consumes `modelExecutionValue` and verifies the metadata before starting the provider process. Never combine this Phase 6 call with analysis workers.
30
+ 6. Call `await_workers([handle])` and verify the data.json Result Path, rendered Markdown sibling, and worker-result pointer at Worker Result Path. Verify the separate heartbeat audit sidecar before accepting the run. **Enforced:** both dispatch adapters keep the three completion paths in `WorkerJob.completion_paths`, and `validators/validate_session_conformance.py` validates the audit sidecar.
30
31
 
31
- The assignment's `modelExecutionValue` feeds both adapter dispatch and the prompt header in item 9 below, so the execution model and recorded `**Model:**` header always agree. Missing or unsupported model resolution is a pre-dispatch contract failure; the common contract does not choose a runtime fallback.
32
+ The complete assignment supplies both runner-specific model values and the prompt header in item 9 below. A native host uses `hostModelValue`; a deterministic provider process uses `modelExecutionValue`; the recorded `**Model:**` header remains the canonical assignment label. Missing or unsupported model resolution is a pre-dispatch contract failure; the common contract does not choose a runtime fallback.
32
33
 
33
34
  The prompt MUST include, in this order at the top:
34
35
 
@@ -90,6 +91,20 @@ For an implementation-planning run, the Report writer worker owns the Phase 6 de
90
91
  2. **Only when it passes and Report Language is not `en`**, dispatch the translator worker, which writes `final-report-<task-type>-<seq>.i18n.<lang>.json`.
91
92
  3. Then run `report-finalize`.
92
93
 
94
+ For step 2, write translator-only task instructions and run `okstra
95
+ agent-prompt materialize` with `--audience translator`, `--assignment-ref
96
+ translator`, `--worker-id translator`, and `--dispatch-kind translator`. Run
97
+ `okstra agent-prompt verify` on the returned `metadataPath` before dispatch and
98
+ use the returned `promptPath` unchanged. A native-session call uses only
99
+ `hostModelValue`; first run `okstra agent-prompt record-dispatch` with the run
100
+ manifest, metadata path, and `--enforcement-mode
101
+ host-native-spec-link-gate`, then run `okstra agent-prompt link-result` with
102
+ `--dispatch-id <invocationId>:attempt-1` and the translation result before
103
+ accepting it. A CLI-wrapper call uses `okstra worker-dispatch` and its
104
+ `modelExecutionValue`. The host-native record links the accepted result to a
105
+ verified call specification but does not assert that Okstra observed the host's
106
+ actual prompt delivery.
107
+
93
108
  **Never dispatch the translator before step 1.** The data.json is the English SSOT; a report-writer that authored it in the reader's language produces a translation *from that language into itself* — a full-cost, entirely useless artifact, and the run still fails at `check-source` afterwards. **Enforced:** `okstra report-translate extract` refuses to build a work list from a data.json over the Korean-prose limit, so a mis-ordered dispatch fails at the translator's first command instead of after it. When it does fail, the fix is a report-writer rewrite in English — discard the sidecar and `translation-source.json` produced from the Korean draft rather than editing them, because their English column is not English.
94
109
 
95
110
  Phase 7 post-processing is then **one command**. `okstra report-finalize` owns the ordered sequence — it is the same code path the Codex lead adapter runs automatically, so a Claude-led run and a Codex-led run finalize identically: