okstra 0.231.0 → 0.231.1
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 +3 -3
- package/docs/architecture/storage-model.md +2 -2
- package/docs/architecture.md +4 -2
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/prompts/lead/convergence.md +3 -3
- package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
- package/runtime/prompts/lead/report-writer.md +1 -1
- package/runtime/prompts/lead/team-contract.md +1 -1
- package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
- package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
- package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
- package/runtime/python/okstra_ctl/convergence.py +112 -20
- package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
- package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
- package/runtime/python/okstra_ctl/correction_round.py +6 -1
- package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
- package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +80 -2
- package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +8 -0
- package/runtime/python/okstra_ctl/team.py +3 -1
- package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
- package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
- package/runtime/validators/validate-run.py +3 -6
package/README.md
CHANGED
|
@@ -68,10 +68,10 @@ okstra/ npm package = repo root
|
|
|
68
68
|
├── tools/build.mjs runtime/ synchronization script (invoked by prepack)
|
|
69
69
|
├── runtime/ gitignored install payload copied to ~/.okstra
|
|
70
70
|
├── scripts/ Python + Bash runtime sources
|
|
71
|
-
├── skills/ public skill Markdown sources (
|
|
71
|
+
├── skills/ public skill Markdown sources (12 user-facing skills)
|
|
72
72
|
├── agents/ Claude host execution-adapter definitions
|
|
73
73
|
├── prompts/, schemas/, templates/, validators/
|
|
74
|
-
├── docs/ English manuals (architecture, CLI, storage,
|
|
74
|
+
├── docs/ English manuals (architecture, CLI, storage, performance); implementation-process.md is Korean
|
|
75
75
|
├── tests/, tests-e2e/
|
|
76
76
|
├── .claude-plugin/plugin.json secondary skills-CLI channel manifest
|
|
77
77
|
├── .github/workflows/ release-please.yml, release.yml
|
|
@@ -105,7 +105,7 @@ Development and CI use Node.js 24 LTS and Python 3.14, selected by `.nvmrc` and
|
|
|
105
105
|
|
|
106
106
|
~/.claude/skills/ automatically discovered by Claude Code (when `~/.claude` exists)
|
|
107
107
|
~/.agents/skills/ discovered by Agent-compatible hosts (created by `install`)
|
|
108
|
-
└── okstra-*/SKILL.md
|
|
108
|
+
└── okstra-*/SKILL.md 12 user-facing skills only (setup/brief-gen/run/discussion/explain-flow/memory/chat/schedule-gen/manager/pr-gen/user-response/code-review)
|
|
109
109
|
|
|
110
110
|
~/.okstra/agents/ role, common and operation contracts (okstra reads them; no host discovers them)
|
|
111
111
|
├── common.json rules every okstra-owned invocation carries
|
|
@@ -320,8 +320,8 @@ Tier 3 command row. `validate-run` derives the evidence again and blocks
|
|
|
320
320
|
check, check run or generation, a changed record, a derived field that differs,
|
|
321
321
|
an omitted record, and an executed Tier 2 or Tier 3 row without a record. A
|
|
322
322
|
marked implementation run cannot settle a FAIL through `leadFixes`, and a stage
|
|
323
|
-
settled after correction round N needs
|
|
324
|
-
|
|
323
|
+
settled after correction round N needs the records of generation N + 1 of
|
|
324
|
+
each verifier that generation gives a check it may run. Unmarked runs and historical reports, including 2.0 reports and
|
|
325
325
|
`verdict: not-run` rows, assemble and validate as before; nothing converts them
|
|
326
326
|
or builds records from their strings. Execution records carry no server-target
|
|
327
327
|
observation and no applicability or skip disposition per frozen check, so the
|
package/docs/architecture.md
CHANGED
|
@@ -737,8 +737,10 @@ excludes it from default selection and rejects any mixed analysis/report batch.
|
|
|
737
737
|
The dispatch commands also record the lead checkpoints whose facts they hold
|
|
738
738
|
(`scripts/okstra_ctl/dispatch_checkpoints.py`): `team dispatch` and
|
|
739
739
|
`worker-dispatch` write `phase-3-team-create` when they write the implicit-team
|
|
740
|
-
marker, `phase-4-dispatch` per `initial` job and
|
|
741
|
-
|
|
740
|
+
marker, `phase-4-dispatch` per `initial` job and per job of an implementation
|
|
741
|
+
correction round (`correction-r<N>`, and a `reverify-r<k>` whose invocation id
|
|
742
|
+
carries `-correction-r<N>-`), and `phase-6-synthesis` on the first
|
|
743
|
+
report-writer dispatch; `team await` and `worker-dispatch` write
|
|
742
744
|
`phase-5-collect` for each `initial` dispatch they settle; `report-finalize`
|
|
743
745
|
writes `phase-7-persist` before its first step. The rows go through
|
|
744
746
|
`lead_progress.record_progress`, the writer `okstra lead-progress append` uses,
|
package/package.json
CHANGED
package/runtime/BUILD.json
CHANGED
|
@@ -52,7 +52,7 @@ Configure this in the `convergence` block of `task-manifest.json`. If the block
|
|
|
52
52
|
| `maxRounds` | `2` (range 1–3) | Maximum number of re-verification rounds. A second round runs only for a finding whose first round produced no usable vote or a tie the critic decides (§"Adversarial classification"); with `1`, a tie is `contested`. Lead resolves the effective value when the manifest omits the key and records it in `config.effectiveMaxRounds` of the convergence state artifact. |
|
|
53
53
|
| `adversarial` | `true` | Always `true`: every phase runs Phase 5.5 in **adversarial mode** (see §"Adversarial Verification Mode") — verifiers actively try to refute each finding, the burden of proof sits on the claim, and `verificationMode` is `"full-reanalysis"` scoped to the finding's cited evidence. `okstra convergence prepare-groups` writes both values regardless of the task manifest, and `seed` refuses a grouping with `adversarial: false` (**Enforced:** `_parse_config` in `scripts/okstra_ctl/convergence_engine.py`). |
|
|
54
54
|
|
|
55
|
-
**Auto-disable rule (BLOCKING).** Convergence requires ≥2 analyser workers to produce a meaningful consensus tally. When the run's selected roster (`resultContract.workerRoles`) holds fewer than 2 analyser workers — the user selected one analyser, or `release-handoff` (zero analyser workers, lead-only) — the lead MUST treat `convergence.enabled` as `false` for that run regardless of manifest configuration, skip Phase 5.5, and record `finalState: "converged"` with `totalRounds: 0`, `round2SkippedReason: "auto-disabled"`, an empty `roundHistory`, and an explanatory note in `config` (e.g. `"autoDisabled": "fewer-than-two-analysers"`). An `implementation-planning` run with one planner still runs the plan-body verification round; that planner's single vote settles each item (`plan-body-verification` (the absolute path in **Okstra Runtime Resources**), "A one-analyser roster"). **Enforced:** `scripts/okstra_ctl/convergence_engine.py` `seed_working_state` stops with `auto-disabled` below two analysis workers, and `validators/validate-run.py` `single_verifier_advisories` records the missing cross-model check as an advisory.
|
|
55
|
+
**Auto-disable rule (BLOCKING).** Convergence requires ≥2 analyser workers to produce a meaningful consensus tally. When the run's selected roster (`resultContract.workerRoles`) holds fewer than 2 analyser workers — the user selected one analyser, or `release-handoff` (zero analyser workers, lead-only) — the lead MUST treat `convergence.enabled` as `false` for that run regardless of manifest configuration, skip Phase 5.5, and record `finalState: "converged"` with `totalRounds: 0`, `round2SkippedReason: "auto-disabled"`, an empty `roundHistory`, and an explanatory note in `config` (e.g. `"autoDisabled": "fewer-than-two-analysers"`). An `implementation-planning` run with one planner still runs the plan-body verification round; that planner's single vote settles each item (`plan-body-verification` (the absolute path in **Okstra Runtime Resources**), "A one-analyser roster"). When the selected roster holds two or more, the seeded count is of those analysers that returned an accepted result, not of workers a group cites: a verifier no group cites still counts, and it re-verifies the queued findings it did not originate. **Enforced:** `scripts/okstra_ctl/convergence.py` `_group_workers` puts every analysis-role execution with an accepted result into the grouping's `workers`, `scripts/okstra_ctl/convergence_engine.py` `seed_working_state` stops with `auto-disabled` below two analysis workers, and `validators/validate-run.py` `single_verifier_advisories` records the missing cross-model check as an advisory.
|
|
56
56
|
|
|
57
57
|
## Finding Category
|
|
58
58
|
|
|
@@ -97,7 +97,7 @@ Read the worker result files generated in Phase 4/5 and extract individual findi
|
|
|
97
97
|
- For bullet/numbered findings, parse `[TICKETID: <id>]` from the item title.
|
|
98
98
|
- Items with multiple tickets (e.g. `TICKET-123, TICKET-456`) expand to a set of ticket keys.
|
|
99
99
|
- Items tagged `unknown` keep the literal `unknown` as their ticket key.
|
|
100
|
-
2. For each finding, record the summary, evidence (file path, line number, basis), the discovering worker, **the worker-internal item ID that worker assigned** (e.g. `F-001`, `1.1`, `F-3` — see `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT), and the parsed ticket set. Persist the item ID as `findings[].discoveredBy.<worker>.itemId` and each cross-worker confirmation as `findings[].sourceItems[]` (one entry per contributing `<worker>:<item-id>` pair). The final-report `## 6.1 Consensus` / `## 6.2 Differences` / `## 2.1 Primary Evidence` tables read this verbatim into their `Source items` columns; without it the synthesised `C-NNN` row loses its link back to the original worker wording.
|
|
100
|
+
2. For each finding, record the summary, evidence (file path, line number, basis), the discovering worker, **the worker-internal item ID that worker assigned** (e.g. `F-001`, `1.1`, `F-3` — see `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT), and the parsed ticket set. Persist the item ID as `findings[].discoveredBy.<worker>.itemId` and each cross-worker confirmation as `findings[].sourceItems[]` (one entry per contributing `<worker>:<item-id>` pair). The final-report `## 6.1 Consensus` / `## 6.2 Differences` / `## 2.1 Primary Evidence` tables read this verbatim into their `Source items` columns; without it the synthesised `C-NNN` row loses its link back to the original worker wording. A worker item that carries no id cannot be cited: do not mint one for it, since `okstra convergence seed` refuses an id the worker's result does not contain. Record the omission with `okstra error-log append-observed --error-type contract-violation` against that worker; the worker still counts toward the analyser roster (Auto-disable rule above).
|
|
101
101
|
3. The lead groups findings based on semantic similarity AND ticket-set equality:
|
|
102
102
|
- Same semantics + same ticket set across 2+ workers → one multi-source group.
|
|
103
103
|
- Same semantics but disjoint ticket sets → separate groups (do NOT over-merge across tickets).
|
|
@@ -128,7 +128,7 @@ Follow this protocol exactly:
|
|
|
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
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
|
-
4. Run `okstra convergence collect-results --plan <round-plan> --
|
|
131
|
+
4. Run `okstra convergence collect-results --plan <round-plan> --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. A worker whose attempt closed `ok` is read from the result path that attempt recorded; `--result <worker>=<path>` (repeatable) overrides it for that worker. The collect refuses a completed worker when the ledger recorded no result path or the recorded file is missing, and names the worker. **Enforced:** `_dispatch_rows_from_manifest` and `_recorded_results` in `scripts/okstra_ctl/convergence.py`, tested by `tests/verification/test_convergence_collect_results.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`).
|
|
133
133
|
6. When the coverage critic is enabled, convert its verification batch to the canonical `dispatches[]` / `gaps[]` result shape and run `okstra convergence apply-critic-gaps --work-state <work> --results <critic-results>` exactly once. The reducer, not the lead, merges verified gaps.
|
|
134
134
|
7. Run `okstra convergence finalize --work-state <work> --output <final>`.
|
|
@@ -143,7 +143,7 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
|
|
|
143
143
|
| `okstra convergence seed --groups <path> --work-state <path> --final-state <path> --migration-dir <dir>` | Create, resume, or recover the working state | `convergence` "Round 0" |
|
|
144
144
|
| `okstra convergence plan-round --work-state <path> --plan <path>` | Write the next round's dispatch plan | `convergence` "Round 1-N" |
|
|
145
145
|
| `okstra convergence reverify-prompt --run-manifest <path> --plan <path> --worker <worker>` | Print one worker's reverify instructions; never compose them by hand | `convergence` "Re-verification Dispatch" |
|
|
146
|
-
| `okstra convergence collect-results --plan <path> --result <worker>=<path> --run-manifest <path> --output <path>` | Read one round's responses into the apply-round input | `convergence` "Round 1-N" |
|
|
146
|
+
| `okstra convergence collect-results --plan <path> [--result <worker>=<path>] --run-manifest <path> --output <path>` | Read one round's responses into the apply-round input | `convergence` "Round 1-N" |
|
|
147
147
|
| `okstra convergence apply-round --work-state <path> --plan <path> --results <path>` | Apply a round's results | `convergence` "Round 1-N" |
|
|
148
148
|
| `okstra convergence critic-prompt --run-manifest <path>` | Print the critic instructions (acceptance on `final-verification`, coverage elsewhere); dispatch concurrently with the first reverify round | `convergence` "Coverage critic pass" |
|
|
149
149
|
| `okstra convergence critic-verify-prompt --run-manifest <path> --gaps <path> --worker <worker>` | Print one analyser's gap-verification or acceptance-candidate instructions | `convergence` "Gap verification", "Acceptance critic pass" |
|
|
@@ -265,7 +265,7 @@ Record each checkpoint with `okstra lead-progress append --project-root <dir> --
|
|
|
265
265
|
|
|
266
266
|
Some checkpoints are recorded by the command that performs the step, because that command holds the fact the line states:
|
|
267
267
|
|
|
268
|
-
- `okstra team dispatch` (on a `terminalBackend: cmux-pane` run) and `okstra worker-dispatch` / `okstra codex-dispatch` record `phase-3-team-create using implicit team` when the dispatch is the one that writes the implicit-team marker into team-state (no `teamCreate` recorded yet), `phase-4-dispatch` for each `initial` job
|
|
268
|
+
- `okstra team dispatch` (on a `terminalBackend: cmux-pane` run) and `okstra worker-dispatch` / `okstra codex-dispatch` record `phase-3-team-create using implicit team` when the dispatch is the one that writes the implicit-team marker into team-state (no `teamCreate` recorded yet), `phase-4-dispatch` for each `initial` job and for each job of an implementation correction round — its `correction-r<N>` executor and verifier dispatches and each `reverify-r<k>` whose invocation id carries `-correction-r<N>-` — and `phase-6-synthesis` on the run's first report-writer dispatch.
|
|
269
269
|
- On a `cmux-pane` run `okstra team await` records `phase-5-poll` on entry and again when the counts changed; `okstra team await` there and `okstra worker-dispatch` record `phase-5-collect worker=<role> status=<terminal-status>` for each `initial` dispatch they settled — the settlement is the result verification: the required artifact exists, the mutation audit passed and the result is linked to its dispatch, or the attempt closed as `error` / `timeout`. A retried attempt counts once its retry settles.
|
|
270
270
|
- On a `cmux-pane` run `okstra team reclaim` records `phase-batch-cleanup`.
|
|
271
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.
|
|
@@ -34,7 +34,7 @@ Resolution `checkRefs` name existing `A-NNN` activity rows. Those activity rows
|
|
|
34
34
|
|
|
35
35
|
Two rules the assembled record is checked against, both learned from the 2026-09-05 audit of shipped pages:
|
|
36
36
|
|
|
37
|
-
- **An empty value is empty, never a null literal.** A prose field with nothing to say is omitted or left `""`. `"None"`, `"null"`, `"undefined"` and `"NaN"` are serialisation artefacts the page prints as text (`tradeoffMatrix` cells in nlpvibe planning-009…014). The lowercase `none` an option's `addedWork`/`directionChange` uses to mean "nothing" is a contract token and stays. **Enforced:** `validators/validate-run.py` `_validate_no_null_literals_in_prose` fails a prose field holding one of those literals.
|
|
37
|
+
- **An empty value is empty, never a null literal.** A prose field with nothing to say is omitted or left `""`. `"None"`, `"null"`, `"undefined"` and `"NaN"` are serialisation artefacts the page prints as text (`tradeoffMatrix` cells in nlpvibe planning-009…014). The lowercase `none` an option's `addedWork`/`directionChange` uses to mean "nothing" is a contract token and stays. **Enforced:** `validators/validate-run.py` `_validate_no_null_literals_in_prose` fails a prose field holding one of those literals, and `scripts/okstra_ctl/approval_decisions.py` `DecisionOption` refuses one in an option's `addedWork`/`directionChange` when the lead records the option.
|
|
38
38
|
- **Citations name rows the reader can reach.** `evidenceRefs`, `supportingEvidence` and the other citation lists carry the record's own ids (`E-`, `CV-`, `D-`, `EA-`, `C-`, `A-`) or a `path:line`. A worker's own finding number (`F-NNN`) reaches the reader only through a promoted `evidence.primary[]` row whose `sourceItems` name it as `<worker>:F-NNN` — the page links a bare `F-NNN` to that row when exactly one row carries it, and leaves it as dead text otherwise. **Enforced:** `_unbridged_worker_finding_refs` in `validators/validate-run.py` warns on every bare `F-NNN` no `sourceItems` entry carries; the narrative rule `_validate_no_opaque_id_references` already fails one in a reader-facing sentence.
|
|
39
39
|
|
|
40
40
|
## Report-writer dispatch
|
|
@@ -170,7 +170,7 @@ After each worker attempt returns (regardless of role), Lead MUST verify the can
|
|
|
170
170
|
- The deterministic provider process returned an explicit `*_RESULT_MISSING` sentinel.
|
|
171
171
|
- The result file is absent at the resolved absolute path even though the worker returned without a `*_RESULT_MISSING` sentinel — for example, claude-worker returned its final assistant message but never persisted the artifact, or the wrapper exited 0 and the codex/antigravity sub-agent forwarded raw stdout despite the contract.
|
|
172
172
|
- The result file exists but cannot be parsed (frontmatter unreadable, sections 1–5 entirely missing). A truncated file in the middle of section 5 is NOT covered here — it goes to the validator's regular `error` path, not the retry path.
|
|
173
|
-
- A reverify (`reverify-r<N>`) result file exists but does not parse as verdict blocks — a missing `**Explanation**`, an unknown verdict token, an unreadable file. This one is settled by the dispatcher, not by you: `okstra_ctl.dispatch_state.unusable_result_defect` counts it as a missing artifact at collection, so the batch re-dispatches it and, if the second attempt fails the same way, closes the attempt as failed. `okstra convergence collect-results` then reads that worker's round status as `error` from the ledger and the engine records its findings as `verification-error` — do not hand-edit the result, and do not
|
|
173
|
+
- A reverify (`reverify-r<N>`) result file exists but does not parse as verdict blocks — a missing `**Explanation**`, an unknown verdict token, an unreadable file. This one is settled by the dispatcher, not by you: `okstra_ctl.dispatch_state.unusable_result_defect` counts it as a missing artifact at collection, so the batch re-dispatches it and, if the second attempt fails the same way, closes the attempt as failed. `okstra convergence collect-results` then reads that worker's round status as `error` from the ledger and the engine records its findings as `verification-error` — do not hand-edit the result, and do not leave that worker out of the collect while its attempt still reads `ok`: collect-results reads its recorded result file even without `--result`, and refuses it while it does not parse.
|
|
174
174
|
- `okstra worker-liveness --team-state <path> --worker <id>` reports a **CLI-wrapper** worker `did-not-launch` after its launch grace. The probe resolves both wrapper artifacts through `wrapper_status`; a missing guessed filename is not this verdict. Use the persisted probe outcome before retrying.
|
|
175
175
|
- `okstra worker-liveness --team-state <path> --worker <id>` reports an **in-process** worker `stalled` — its registered audit sidecar's newest `- PROGRESS:` heartbeat is older than the cadence budget, or the sidecar carries no heartbeat at all. This is the in-process equivalent of the CLI wrappers' idle watchdog: the wrapper reaps a silent CLI itself, but nothing reaped a silent in-process worker until its deadline. The same selector serves both worker kinds — the sidecar is reused when a worker is re-dispatched, so the probe needs the row's `startedAt` to tell the previous attempt's last heartbeat apart from this dispatch's silence. A budget breach is not a verdict on its own: the probe re-reads the sidecar after half that stage's budget and reports `stalled` only when the newest heartbeat has not advanced, so an unhealthy verdict costs that confirmation window before it returns. That window is what separates a worker inside one long uninterruptible tool call — which cannot append a heartbeat at all — from a worker that died, and measuring it is the probe's job, not yours: do not second-guess a verdict by checking mtimes yourself. Tune it with `--stall-confirm <seconds>`; `0` restores the immediate verdict.
|
|
176
176
|
- The result file exists but its audit sidecar does not, at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`. Workers write both in the same step, so a result without a sidecar means the Reading Confirmation block — the only evidence the worker read its inputs — was never produced. `validate-run.py` fails the run on this at Phase 7 either way (`validate_worker_results_audit`); checking it here spends the existing one-retry budget while the role can still be re-dispatched, instead of surfacing hours later when the worker session is gone.
|
|
@@ -4,9 +4,10 @@
|
|
|
4
4
|
- `rationale` — why this option is on the board, as long as the reason needs.
|
|
5
5
|
- `reach` — exactly one of `in-repo` or `cross-repo`.
|
|
6
6
|
- `scopeEffects` — optional tokens drawn from `{new-schema, deferrable}`.
|
|
7
|
-
- `addedWork` — the work this choice creates that the other choices do not. Name the files, stages, or commands; do not substitute a cost adjective.
|
|
8
|
-
- `directionChange` — what this choice reverses: an approved plan item, a recorded decision, an earlier answer. Name that item. When it reverses nothing,
|
|
7
|
+
- `addedWork` — the work this choice creates that the other choices do not. Name the files, stages, or commands; do not substitute a cost adjective. When it creates none, write `none`.
|
|
8
|
+
- `directionChange` — what this choice reverses: an approved plan item, a recorded decision, an earlier answer. Name that item. When it reverses nothing, write `none`.
|
|
9
9
|
- `disposition` — the effect of selecting the option. Use `select` for `user-decision`. Use `accept-risk` on any classification, including `correctness-critical`, when the user ends the gate and leaves the DISAGREE on the record. Use `request-revision` or `reject` when the option sends the plan back.
|
|
10
|
+
- `addedWork` and `directionChange` never hold `None`, `null`, `undefined` or `NaN`; the page would print them as text. **Enforced:** `scripts/okstra_ctl/approval_decisions.py` `DecisionOption` refuses them when `okstra approval-decision open` records the option.
|
|
10
11
|
- report assembly derives `approvalContext`, status, and resolution. `approvalContext` contains only `classification`, `unblockCondition`, and `recommendedDisposition`; it never copies plan or activity identifiers.
|
|
11
12
|
- a `C-NNN` you name outside the row itself must be a row that exists. One place is checked: a `blocked` `endStateCoverage` row's `blockedBy.ref`, when its `kind` is `clarification` — see each phase profile's `blockedBy` rule and `validators/validate-run.py` `_validate_end_state_blocked_by`. Everywhere else — `coveredBy`, `rationale`, `verdictCard.nextStep`, `finalVerdict.nextStep`, `humanSummary.actions[]`, `recommendedNextSteps[].text` — is free prose and stays uncheckable: a shipped report legitimately writes `C-057 through C-068 are applied or carried` or `C-201 does not apply`, and a validator scanning those fields for ids would fail 15 of the 56 reports on disk. There it is on you not to send a reader after an id with no row. An id an earlier run already answered reaches this report as a carried decision — prepare seeds `carriedDecisions[]` from the run's carry-in record, and `okstra approval-decision carry` admits one that record does not answer — never by citing it bare. `crossVerification` rows are numbered `CV-NNN` so a `C-NNN` has exactly one meaning.
|
|
12
13
|
- the three impact fields answer three different questions — how far the change reaches, what new work it creates, and what it overturns. Someone choosing between options needs all three, so never fold them into one field: whichever axis is easiest to write would silently stand in for the other two.
|
|
@@ -21,6 +21,7 @@ from .convergence_store import write_json_atomic
|
|
|
21
21
|
from .final_report_schema import load_schema_version
|
|
22
22
|
from .json_boundary import JsonBoundaryError, load_owned_object
|
|
23
23
|
from .report_contract import CURRENT_REPORT_SCHEMA_VERSION
|
|
24
|
+
from .report_prose_keys import NULL_LITERALS
|
|
24
25
|
|
|
25
26
|
|
|
26
27
|
@lru_cache(maxsize=None)
|
|
@@ -73,6 +74,19 @@ def _required(value: str, field: str) -> str:
|
|
|
73
74
|
return value.strip()
|
|
74
75
|
|
|
75
76
|
|
|
77
|
+
def _refuse_null_literal(value: str, field: str) -> None:
|
|
78
|
+
"""Refuse a stringified null in an impact field and name the `none` token.
|
|
79
|
+
|
|
80
|
+
Report assembly copies the ledger row into the published report
|
|
81
|
+
unchanged, and `validate-run` sees the value only after publication, so
|
|
82
|
+
the ledger write is where the author can still replace it."""
|
|
83
|
+
if value.strip() in NULL_LITERALS:
|
|
84
|
+
raise ApprovalDecisionError(
|
|
85
|
+
f"{field} holds the null literal {value.strip()!r}; write `none` when "
|
|
86
|
+
"the option adds no work or reverses nothing"
|
|
87
|
+
)
|
|
88
|
+
|
|
89
|
+
|
|
76
90
|
@dataclass(frozen=True)
|
|
77
91
|
class DecisionOption:
|
|
78
92
|
role: str
|
|
@@ -89,6 +103,8 @@ class DecisionOption:
|
|
|
89
103
|
raise ApprovalDecisionError(f"invalid option role: {self.role}")
|
|
90
104
|
for field in ("answer", "rationale", "added_work", "direction_change"):
|
|
91
105
|
_required(getattr(self, field), field)
|
|
106
|
+
for field in ("added_work", "direction_change"):
|
|
107
|
+
_refuse_null_literal(getattr(self, field), field)
|
|
92
108
|
if self.disposition not in DISPOSITIONS:
|
|
93
109
|
raise ApprovalDecisionError(f"invalid disposition: {self.disposition}")
|
|
94
110
|
if self.reach not in REACHES:
|
|
@@ -24,8 +24,13 @@ from ..registry.provider_registry import default_provider_registry
|
|
|
24
24
|
from ..worker_request import build_request
|
|
25
25
|
from ..worker_runner import QUIET, run_worker
|
|
26
26
|
from ..write_policy import build_write_policy, derive_write_enforcement
|
|
27
|
+
from ..wrapper_status import WrapperStatus, read_log_tail, read_wrapper_status
|
|
27
28
|
from .contracts import OPERATION, BusinessFlowError, FlowRequest
|
|
28
29
|
|
|
30
|
+
# The message lands in the execution record's `error` field, so it carries
|
|
31
|
+
# the CLI's last lines rather than its whole transcript.
|
|
32
|
+
_EXIT_LOG_TAIL_BYTES = 800
|
|
33
|
+
|
|
29
34
|
|
|
30
35
|
@dataclass(frozen=True)
|
|
31
36
|
class PreparedCall:
|
|
@@ -111,14 +116,16 @@ class ProviderFlowExecutor:
|
|
|
111
116
|
pool = ModelPool.from_registry(registry)
|
|
112
117
|
selected = pool.resolve_alias(assignment["provider"], assignment["model"])
|
|
113
118
|
request = _read_only_worker_request(call, assignment)
|
|
119
|
+
log_path = call.prompt_path.with_suffix(".log")
|
|
120
|
+
status_path = call.prompt_path.with_suffix(".status.json")
|
|
114
121
|
output, errors = io.StringIO(), io.StringIO()
|
|
115
122
|
with contextlib.redirect_stdout(output), contextlib.redirect_stderr(errors):
|
|
116
123
|
code = run_worker(
|
|
117
124
|
provider.exec_strategy,
|
|
118
125
|
request,
|
|
119
126
|
presentation=QUIET,
|
|
120
|
-
log_path=
|
|
121
|
-
status_path=
|
|
127
|
+
log_path=log_path,
|
|
128
|
+
status_path=status_path,
|
|
122
129
|
status_extra={
|
|
123
130
|
"writePolicy": request.policy.write_policy.to_payload(),
|
|
124
131
|
"writeEnforcement": request.policy.write_enforcement.to_payload(),
|
|
@@ -130,11 +137,36 @@ class ProviderFlowExecutor:
|
|
|
130
137
|
)
|
|
131
138
|
if code:
|
|
132
139
|
raise BusinessFlowError(
|
|
133
|
-
f"business investigator exited {code}:
|
|
140
|
+
f"business investigator exited {code}: "
|
|
141
|
+
+ _exit_cause(errors.getvalue(), status_path, log_path)
|
|
134
142
|
)
|
|
135
143
|
return output.getvalue().encode("utf-8")
|
|
136
144
|
|
|
137
145
|
|
|
146
|
+
def _exit_cause(stderr: str, status_path: Path, log_path: Path) -> str:
|
|
147
|
+
"""run_worker writes the CLI's own output to the log, not to this
|
|
148
|
+
process's stderr, so the cause is read back from the status sidecar and
|
|
149
|
+
the log tail, with the log path for the rest."""
|
|
150
|
+
status = read_wrapper_status(status_path)
|
|
151
|
+
parts = (
|
|
152
|
+
stderr.strip(),
|
|
153
|
+
_sidecar_cause(status) if status is not None else "",
|
|
154
|
+
read_log_tail(log_path, _EXIT_LOG_TAIL_BYTES) or "",
|
|
155
|
+
f"log: {log_path}",
|
|
156
|
+
)
|
|
157
|
+
return "; ".join(part for part in parts if part)
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def _sidecar_cause(status: WrapperStatus) -> str:
|
|
161
|
+
"""An idle-watchdog kill records `timeout` and `idle_seconds` but no
|
|
162
|
+
`failure` (worker_runner.run_worker), so it is named separately."""
|
|
163
|
+
if not status.timeout:
|
|
164
|
+
return status.failure
|
|
165
|
+
idle = status.raw.get("idle_seconds")
|
|
166
|
+
timeout = f"idle timeout after {idle}s" if isinstance(idle, int) else "idle timeout"
|
|
167
|
+
return "; ".join(part for part in (status.failure, timeout) if part)
|
|
168
|
+
|
|
169
|
+
|
|
138
170
|
def _read_only_worker_request(
|
|
139
171
|
call: PreparedCall, assignment: dict[str, str]
|
|
140
172
|
) -> WorkerExecRequest:
|
|
@@ -14,6 +14,7 @@ from okstra_project.slug import slugify
|
|
|
14
14
|
from okstra_project.state import StateError, parse_task_key
|
|
15
15
|
|
|
16
16
|
from .convergence_engine import (
|
|
17
|
+
ANALYSIS_SOURCE_ROLES,
|
|
17
18
|
ConvergenceContractError,
|
|
18
19
|
apply_acceptance_critic_results,
|
|
19
20
|
apply_critic_gap_results,
|
|
@@ -54,9 +55,11 @@ from .convergence_migration import (
|
|
|
54
55
|
)
|
|
55
56
|
from .convergence_provenance import (
|
|
56
57
|
GROUPS_BASENAME_RE,
|
|
58
|
+
accepted_role_execution_refs,
|
|
57
59
|
discarded_worker_errors,
|
|
58
60
|
missing_scope_results,
|
|
59
61
|
provenance_errors,
|
|
62
|
+
resolve_recorded_result_path,
|
|
60
63
|
worker_result_suffix,
|
|
61
64
|
)
|
|
62
65
|
from .correction_round import (
|
|
@@ -454,7 +457,9 @@ def _parser() -> argparse.ArgumentParser:
|
|
|
454
457
|
collect.add_argument("--plan", type=Path, required=True)
|
|
455
458
|
collect.add_argument("--result", action="append", default=[],
|
|
456
459
|
metavar="<worker>=<path>",
|
|
457
|
-
help="one worker's reverify result file (repeatable)"
|
|
460
|
+
help="one worker's reverify result file (repeatable); "
|
|
461
|
+
"a worker without one is read from the result "
|
|
462
|
+
"path its ok attempt recorded")
|
|
458
463
|
collect.add_argument("--run-manifest", type=Path, required=True,
|
|
459
464
|
help="the current run manifest; each planned worker's "
|
|
460
465
|
"terminal outcome and duration are read from its "
|
|
@@ -1418,7 +1423,7 @@ def _dispatch_rows_from_manifest(
|
|
|
1418
1423
|
manifest: Any,
|
|
1419
1424
|
run_manifest_path: Path,
|
|
1420
1425
|
scope: str | None = None,
|
|
1421
|
-
) -> list[dict[str, Any]]:
|
|
1426
|
+
) -> tuple[list[dict[str, Any]], dict[str, str]]:
|
|
1422
1427
|
"""`dispatches[]` 를 execution manifest 의 attempt 원장에서 도출한다.
|
|
1423
1428
|
|
|
1424
1429
|
종전에는 리드가 `--dispatch <worker>=<status>:<durationMs>` 로 상태와
|
|
@@ -1432,6 +1437,11 @@ def _dispatch_rows_from_manifest(
|
|
|
1432
1437
|
상태 대응: `ok` → completed, 그 밖의 terminal 은 error (wrapper 가 timeout
|
|
1433
1438
|
으로 닫은 attempt 는 `changeSummary.timeout` 이 참이면 timeout). 이 라운드의
|
|
1434
1439
|
invocation 이 없는 워커는 not-run.
|
|
1440
|
+
|
|
1441
|
+
The second value maps each worker to the `resultPath` its deciding attempt
|
|
1442
|
+
closed with. A batch dispatch records the worker-result file there, so the
|
|
1443
|
+
lead does not have to repeat it as `--result`: collect-results reads it for
|
|
1444
|
+
each completed worker given no `--result`, and refuses when it is absent.
|
|
1435
1445
|
"""
|
|
1436
1446
|
round_number = plan.get("round")
|
|
1437
1447
|
if not isinstance(round_number, int) or round_number < 1:
|
|
@@ -1441,12 +1451,9 @@ def _dispatch_rows_from_manifest(
|
|
|
1441
1451
|
role.role_execution_ref: role.source_role_execution_ref or role.role_execution_ref
|
|
1442
1452
|
for role in getattr(manifest, "role_executions", ())
|
|
1443
1453
|
}
|
|
1444
|
-
latest
|
|
1445
|
-
for attempt in getattr(manifest, "attempts", ()):
|
|
1446
|
-
current = latest.get(attempt.invocation_ref)
|
|
1447
|
-
if current is None or attempt.attempt > current.attempt:
|
|
1448
|
-
latest[attempt.invocation_ref] = attempt
|
|
1454
|
+
latest = _latest_attempts(manifest)
|
|
1449
1455
|
rows: list[dict[str, Any]] = []
|
|
1456
|
+
recorded_result_paths: dict[str, str] = {}
|
|
1450
1457
|
for row in plan.get("dispatches") or []:
|
|
1451
1458
|
if not isinstance(row, Mapping):
|
|
1452
1459
|
continue
|
|
@@ -1475,15 +1482,30 @@ def _dispatch_rows_from_manifest(
|
|
|
1475
1482
|
"round result written over an open attempt is a status the ledger "
|
|
1476
1483
|
"never recorded"
|
|
1477
1484
|
)
|
|
1478
|
-
status = _ATTEMPT_DISPATCH_STATUS.get(attempt.status, "error")
|
|
1479
|
-
if status == "error" and bool((attempt.change_summary or {}).get("timeout")):
|
|
1480
|
-
status = "timeout"
|
|
1481
1485
|
rows.append({
|
|
1482
1486
|
"worker": worker,
|
|
1483
|
-
"status":
|
|
1487
|
+
"status": _attempt_dispatch_status(attempt),
|
|
1484
1488
|
"durationMs": _duration_ms(attempt.started_at, attempt.finished_at),
|
|
1485
1489
|
})
|
|
1486
|
-
|
|
1490
|
+
if attempt.result_path:
|
|
1491
|
+
recorded_result_paths[worker] = attempt.result_path
|
|
1492
|
+
return rows, recorded_result_paths
|
|
1493
|
+
|
|
1494
|
+
|
|
1495
|
+
def _latest_attempts(manifest: Any) -> dict[str, Any]:
|
|
1496
|
+
latest: dict[str, Any] = {}
|
|
1497
|
+
for attempt in getattr(manifest, "attempts", ()):
|
|
1498
|
+
current = latest.get(attempt.invocation_ref)
|
|
1499
|
+
if current is None or attempt.attempt > current.attempt:
|
|
1500
|
+
latest[attempt.invocation_ref] = attempt
|
|
1501
|
+
return latest
|
|
1502
|
+
|
|
1503
|
+
|
|
1504
|
+
def _attempt_dispatch_status(attempt: Any) -> str:
|
|
1505
|
+
status = _ATTEMPT_DISPATCH_STATUS.get(attempt.status, "error")
|
|
1506
|
+
if status == "error" and bool((attempt.change_summary or {}).get("timeout")):
|
|
1507
|
+
return "timeout"
|
|
1508
|
+
return status
|
|
1487
1509
|
|
|
1488
1510
|
|
|
1489
1511
|
def _duration_ms(started_at: str, finished_at: str) -> int:
|
|
@@ -1541,10 +1563,39 @@ def _worker_votes(
|
|
|
1541
1563
|
return votes
|
|
1542
1564
|
|
|
1543
1565
|
|
|
1566
|
+
def _recorded_results(
|
|
1567
|
+
dispatches: list[dict[str, Any]],
|
|
1568
|
+
recorded_result_paths: Mapping[str, str],
|
|
1569
|
+
supplied_results: list[str],
|
|
1570
|
+
authority: Mapping[str, Any],
|
|
1571
|
+
) -> list[str]:
|
|
1572
|
+
explicit_workers = {_split_pair(raw, "--result")[0] for raw in supplied_results}
|
|
1573
|
+
result_args: list[str] = []
|
|
1574
|
+
for row in dispatches:
|
|
1575
|
+
worker = row["worker"]
|
|
1576
|
+
if row["status"] != "completed" or worker in explicit_workers:
|
|
1577
|
+
continue
|
|
1578
|
+
value = recorded_result_paths.get(worker)
|
|
1579
|
+
if not value:
|
|
1580
|
+
raise ConvergenceContractError(
|
|
1581
|
+
f"`{worker}` closed its attempt ok but the ledger recorded no result "
|
|
1582
|
+
f"path and no `--result {worker}=<path>` was given — a completed "
|
|
1583
|
+
"worker without a vote fails apply-round"
|
|
1584
|
+
)
|
|
1585
|
+
path = resolve_recorded_result_path(value, authority)
|
|
1586
|
+
if not path.is_file():
|
|
1587
|
+
raise ConvergenceContractError(
|
|
1588
|
+
f"`{worker}` closed its attempt ok with result `{path}`, which does "
|
|
1589
|
+
f"not exist; pass `--result {worker}=<path>` for the file it wrote"
|
|
1590
|
+
)
|
|
1591
|
+
result_args.append(f"{worker}={path}")
|
|
1592
|
+
return result_args
|
|
1593
|
+
|
|
1594
|
+
|
|
1544
1595
|
def _collect_results(args: argparse.Namespace) -> tuple[str, Path]:
|
|
1545
1596
|
plan = load_owned_json_object(args.plan)
|
|
1546
1597
|
planned = _planned_finding_ids(plan)
|
|
1547
|
-
manifest,
|
|
1598
|
+
manifest, authority = read_execution_manifest_view(args.run_manifest)
|
|
1548
1599
|
if getattr(manifest, "legacy", False):
|
|
1549
1600
|
raise ConvergenceContractError(
|
|
1550
1601
|
"collect-results reads dispatch outcomes from a v2 execution manifest; "
|
|
@@ -1554,8 +1605,14 @@ def _collect_results(args: argparse.Namespace) -> tuple[str, Path]:
|
|
|
1554
1605
|
scope = convergence_scope(args.correction_round)
|
|
1555
1606
|
except CorrectionRoundError as exc:
|
|
1556
1607
|
raise ConvergenceContractError(str(exc)) from exc
|
|
1557
|
-
dispatches = _dispatch_rows_from_manifest(
|
|
1558
|
-
|
|
1608
|
+
dispatches, recorded_result_paths = _dispatch_rows_from_manifest(
|
|
1609
|
+
plan, manifest, args.run_manifest, scope
|
|
1610
|
+
)
|
|
1611
|
+
raw_results = [
|
|
1612
|
+
*args.result,
|
|
1613
|
+
*_recorded_results(dispatches, recorded_result_paths, args.result, authority),
|
|
1614
|
+
]
|
|
1615
|
+
votes = _worker_votes(raw_results, planned)
|
|
1559
1616
|
returned_without_completion = sorted(
|
|
1560
1617
|
worker for worker in votes
|
|
1561
1618
|
if next((row["status"] for row in dispatches if row["worker"] == worker), None)
|
|
@@ -1750,6 +1807,42 @@ def _group_worker(manifest: Mapping[str, Any], worker_id: str) -> dict[str, str]
|
|
|
1750
1807
|
"sourceRoleExecutionRef": str(execution["roleExecutionRef"])}
|
|
1751
1808
|
|
|
1752
1809
|
|
|
1810
|
+
def _group_workers(
|
|
1811
|
+
manifest: Mapping[str, Any],
|
|
1812
|
+
execution_manifest: ExecutionManifest | None,
|
|
1813
|
+
cited: list[str],
|
|
1814
|
+
scope: str | None,
|
|
1815
|
+
) -> list[dict[str, str]]:
|
|
1816
|
+
"""Grouping roster: analysis workers with an accepted result, the other cited workers, the critic.
|
|
1817
|
+
|
|
1818
|
+
Analysis workers are listed in `workerAssignments` order whether or not a group cites them, so
|
|
1819
|
+
the auto-disable rule counts analysers that returned a result. A legacy or missing execution
|
|
1820
|
+
manifest has no attempt ledger, so its roster is the cited workers.
|
|
1821
|
+
"""
|
|
1822
|
+
if execution_manifest is None or execution_manifest.legacy:
|
|
1823
|
+
workers = [_group_worker(manifest, worker) for worker in cited]
|
|
1824
|
+
else:
|
|
1825
|
+
accepted = accepted_role_execution_refs(execution_manifest, scope)
|
|
1826
|
+
# Groups may cite `codex-verifier-worker` for the `codex-verifier` row; the roster keeps the
|
|
1827
|
+
# cited spelling because the engine matches group sources to roster rows by that string.
|
|
1828
|
+
spelling = {worker.removesuffix("-worker"): worker for worker in cited}
|
|
1829
|
+
assignments = manifest.get("workerAssignments")
|
|
1830
|
+
workers = []
|
|
1831
|
+
for row in assignments if isinstance(assignments, list) else []:
|
|
1832
|
+
if not isinstance(row, Mapping) or row.get("role") not in ANALYSIS_SOURCE_ROLES:
|
|
1833
|
+
continue
|
|
1834
|
+
bare_id = str(row.get("workerId") or "").removesuffix("-worker")
|
|
1835
|
+
if not bare_id:
|
|
1836
|
+
continue
|
|
1837
|
+
worker = _group_worker(manifest, spelling.get(bare_id, bare_id))
|
|
1838
|
+
if worker["sourceRoleExecutionRef"] in accepted:
|
|
1839
|
+
workers.append(worker)
|
|
1840
|
+
listed = {worker["workerId"] for worker in workers}
|
|
1841
|
+
workers.extend(_group_worker(manifest, worker) for worker in cited if worker not in listed)
|
|
1842
|
+
workers.extend(_critic_tie_breaker(manifest))
|
|
1843
|
+
return workers
|
|
1844
|
+
|
|
1845
|
+
|
|
1753
1846
|
def _critic_tie_breaker(manifest: Mapping[str, Any]) -> list[dict[str, str]]:
|
|
1754
1847
|
"""로스터에 크리틱이 있으면 동률 finding 을 판정할 `critic` 워커 행 하나."""
|
|
1755
1848
|
executions = manifest.get("roleExecutions") if isinstance(manifest.get("roleExecutions"), list) else []
|
|
@@ -1838,16 +1931,15 @@ def _prepare_groups(args: argparse.Namespace) -> tuple[str, Path]:
|
|
|
1838
1931
|
authority = validated_run_authority(args.run_manifest)
|
|
1839
1932
|
manifest = authority.payload
|
|
1840
1933
|
groups = _parse_grouping_markdown(args.input)
|
|
1841
|
-
|
|
1934
|
+
cited_worker_ids = list(dict.fromkeys(
|
|
1842
1935
|
source["worker"] for group in groups for source in group["sourceItems"]
|
|
1843
1936
|
))
|
|
1937
|
+
scope = _correction_scope(args, authority)
|
|
1844
1938
|
output = authority.run_dir / "state" / _canonical_run_artifact_name(
|
|
1845
|
-
"convergence-groups", authority.task_type, authority.state_sequence,
|
|
1846
|
-
_correction_scope(args, authority),
|
|
1939
|
+
"convergence-groups", authority.task_type, authority.state_sequence, scope,
|
|
1847
1940
|
)
|
|
1848
1941
|
config = _convergence_config(authority)
|
|
1849
|
-
workers =
|
|
1850
|
-
workers.extend(_critic_tie_breaker(manifest))
|
|
1942
|
+
workers = _group_workers(manifest, authority.execution_manifest, cited_worker_ids, scope)
|
|
1851
1943
|
source_refs = [worker["sourceRoleExecutionRef"] for worker in workers]
|
|
1852
1944
|
if len(source_refs) != len(set(source_refs)):
|
|
1853
1945
|
raise ConvergenceContractError("duplicate sourceRoleExecutionRef")
|
|
@@ -26,6 +26,7 @@ _AUDIENCE_SOURCE_ROLES = {
|
|
|
26
26
|
"report-writer": frozenset({"report-writer"}),
|
|
27
27
|
"critic": frozenset({"critic"}),
|
|
28
28
|
}
|
|
29
|
+
ANALYSIS_SOURCE_ROLES = _AUDIENCE_SOURCE_ROLES["analysis"]
|
|
29
30
|
_VERIFICATION_MODES = {"lightweight", "full-reanalysis"}
|
|
30
31
|
# `unverified` 가 없던 시절의 산출물. `reuse-final` 이 그대로 읽으므로 그
|
|
31
32
|
# 어휘로 검증한다 — 없던 키를 요구하면 이미 디스크에 있는 리포트가 무효가 된다.
|
|
@@ -133,6 +133,28 @@ def discovery_attempts(
|
|
|
133
133
|
return by_role
|
|
134
134
|
|
|
135
135
|
|
|
136
|
+
def accepted_role_execution_refs(
|
|
137
|
+
manifest: ExecutionManifest, scope: str | None = None,
|
|
138
|
+
) -> set[str]:
|
|
139
|
+
"""Role executions whose latest attempt of some discovery invocation in the scope is ``ok``."""
|
|
140
|
+
return {
|
|
141
|
+
ref for ref, attempts in discovery_attempts(manifest, scope).items()
|
|
142
|
+
if any(attempt.status == "ok" for attempt in attempts)
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def resolve_recorded_result_path(result_path: str, authority: Mapping) -> Path:
|
|
147
|
+
# A batch dispatch records the absolute worker-result path; a native agent
|
|
148
|
+
# dispatch records it relative to the project root.
|
|
149
|
+
candidate = Path(result_path)
|
|
150
|
+
if candidate.is_absolute():
|
|
151
|
+
return candidate
|
|
152
|
+
project_root = authority.get("projectRoot")
|
|
153
|
+
if not _nonempty_string(project_root):
|
|
154
|
+
raise ValueError("relative accepted resultPath requires projectRoot")
|
|
155
|
+
return Path(project_root) / candidate
|
|
156
|
+
|
|
157
|
+
|
|
136
158
|
def worker_result_paths(
|
|
137
159
|
run_dir: Path, document: Mapping, suffix: str, scope: str | None = None,
|
|
138
160
|
) -> dict[str, Path]:
|
|
@@ -162,12 +184,7 @@ def worker_result_paths(
|
|
|
162
184
|
]
|
|
163
185
|
if not accepted:
|
|
164
186
|
continue
|
|
165
|
-
candidate =
|
|
166
|
-
if not candidate.is_absolute():
|
|
167
|
-
project_root = authority.get("projectRoot")
|
|
168
|
-
if not _nonempty_string(project_root):
|
|
169
|
-
raise ValueError("relative accepted resultPath requires projectRoot")
|
|
170
|
-
candidate = Path(project_root) / candidate
|
|
187
|
+
candidate = resolve_recorded_result_path(accepted[-1].result_path, authority)
|
|
171
188
|
if candidate.resolve().parent != results_dir.resolve():
|
|
172
189
|
raise ValueError(f"accepted resultPath is outside worker-results: {candidate}")
|
|
173
190
|
if not candidate.is_file():
|
|
@@ -357,6 +374,7 @@ def discarded_workers(
|
|
|
357
374
|
if execution_manifest is None or getattr(execution_manifest, "legacy", False):
|
|
358
375
|
return {}
|
|
359
376
|
attempts = discovery_attempts(execution_manifest, scope)
|
|
377
|
+
accepted = accepted_role_execution_refs(execution_manifest, scope)
|
|
360
378
|
result: dict[str, str] = {}
|
|
361
379
|
for row in document["workers"]:
|
|
362
380
|
if not isinstance(row, dict):
|
|
@@ -366,7 +384,7 @@ def discarded_workers(
|
|
|
366
384
|
if not _nonempty_string(worker) or not _nonempty_string(role_ref):
|
|
367
385
|
continue
|
|
368
386
|
rows = attempts.get(role_ref, [])
|
|
369
|
-
if not rows or
|
|
387
|
+
if not rows or role_ref in accepted:
|
|
370
388
|
continue
|
|
371
389
|
discarded = [item for item in rows if item.status in DISCARDED_ATTEMPT_STATUSES]
|
|
372
390
|
if discarded:
|
|
@@ -424,14 +442,12 @@ def missing_scope_results(
|
|
|
424
442
|
return []
|
|
425
443
|
if not isinstance(document, dict):
|
|
426
444
|
return []
|
|
427
|
-
|
|
445
|
+
accepted = accepted_role_execution_refs(execution_manifest, scope)
|
|
428
446
|
missing = sorted({
|
|
429
447
|
str(row.get("workerId"))
|
|
430
448
|
for row in document.get("workers") or []
|
|
431
449
|
if isinstance(row, dict) and row.get("audience") == "analysis"
|
|
432
|
-
and not
|
|
433
|
-
item.status == "ok" for item in attempts.get(row.get("sourceRoleExecutionRef"), [])
|
|
434
|
-
)
|
|
450
|
+
and row.get("sourceRoleExecutionRef") not in accepted
|
|
435
451
|
})
|
|
436
452
|
return [
|
|
437
453
|
f"`{worker}` has no accepted `{scope}` result; await that round's verifiers "
|
|
@@ -61,6 +61,11 @@ def correction_convergence_states(initial_final: Path) -> list[tuple[str, Path]]
|
|
|
61
61
|
return rows
|
|
62
62
|
|
|
63
63
|
|
|
64
|
+
def invocation_in_correction_namespace(invocation_ref: str) -> bool:
|
|
65
|
+
"""Whether an invocation id contains `-correction-r`, as every correction-round id does."""
|
|
66
|
+
return f"-{CORRECTION_DISPATCH_KIND_PREFIX}" in invocation_ref
|
|
67
|
+
|
|
68
|
+
|
|
64
69
|
def reverify_invocation_in_scope(invocation_ref: str, scope: str | None, round_number: int) -> bool:
|
|
65
70
|
"""Whether a `reverify-r<N>` invocation belongs to this convergence namespace.
|
|
66
71
|
|
|
@@ -68,7 +73,7 @@ def reverify_invocation_in_scope(invocation_ref: str, scope: str | None, round_n
|
|
|
68
73
|
correction re-convergence names it `…-correction-r<M>-reverify-r<N>-<worker>`.
|
|
69
74
|
"""
|
|
70
75
|
if scope is None:
|
|
71
|
-
return
|
|
76
|
+
return not invocation_in_correction_namespace(invocation_ref)
|
|
72
77
|
return f"-{scope}-reverify-r{round_number}-" in invocation_ref
|
|
73
78
|
|
|
74
79
|
|
|
@@ -6,9 +6,14 @@ dispatch 를 정하고 결과를 확정하는 곳은 `team dispatch` / `team awa
|
|
|
6
6
|
명령들이 갖고 있다. 리드가 같은 사실을 `okstra lead-progress append` 로 다시
|
|
7
7
|
적으면 체크포인트마다 전체 컨텍스트를 한 턴씩 쓰는데, 여기서 기록하면 턴이 들지 않는다.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
The per-worker `phase-4-dispatch` line is recorded for `initial` jobs and for the jobs of an
|
|
10
|
+
implementation correction round: its `correction-r<N>` executor and verifier dispatches and
|
|
11
|
+
the reverify rounds that re-converge it (`…-correction-r<N>-reverify-r<k>-…`). The lead
|
|
12
|
+
emits the lines this command prints instead of appending `phase-4-dispatch` itself, so a
|
|
13
|
+
correction round left out here showed the user no dispatch at all. The initial-namespace
|
|
14
|
+
reverify, critic and plan-verify rounds stay out; the lead reports them through
|
|
15
|
+
`phase-5.5-convergence`, `phase-5.6-critic` and `phase-5.5.9-plan-verify`.
|
|
16
|
+
`phase-5-collect` still counts `initial` dispatches only.
|
|
12
17
|
|
|
13
18
|
activity-contract v1 run 에서는 검증기가 워커별 `phase-4-dispatch` /
|
|
14
19
|
`phase-5-collect` 마다 같은 워커의 `worker-dispatched` / `worker-completed`
|
|
@@ -26,8 +31,10 @@ from .agent.activity import (
|
|
|
26
31
|
conversation_activity_line,
|
|
27
32
|
record_activity,
|
|
28
33
|
)
|
|
34
|
+
from .correction_round import correction_round, invocation_in_correction_namespace
|
|
29
35
|
from .dispatch_state import (
|
|
30
36
|
TERMINAL_WORKER_STATUSES,
|
|
37
|
+
WorkerJob,
|
|
31
38
|
dispatch_worker_key,
|
|
32
39
|
has_recorded_team_create,
|
|
33
40
|
worker_dispatch_records,
|
|
@@ -35,6 +42,7 @@ from .dispatch_state import (
|
|
|
35
42
|
from .json_boundary import JsonBoundaryError, load_owned_object
|
|
36
43
|
from .lead_progress import record_checkpoint
|
|
37
44
|
from .worker_prompt_body import REPORT_WRITER_WORKER_ID
|
|
45
|
+
from .worker_prompt_policy import is_reverify_dispatch_kind
|
|
38
46
|
|
|
39
47
|
_INITIAL = "initial"
|
|
40
48
|
|
|
@@ -63,7 +71,7 @@ def record_dispatch_checkpoints(
|
|
|
63
71
|
project_root, run_manifest, "phase-3-team-create", source=source,
|
|
64
72
|
))
|
|
65
73
|
for job in jobs:
|
|
66
|
-
if job
|
|
74
|
+
if _announces_worker_dispatch(job):
|
|
67
75
|
lines.append(record_checkpoint(
|
|
68
76
|
project_root, run_manifest, "phase-4-dispatch", source=source,
|
|
69
77
|
worker=job.worker_id,
|
|
@@ -73,7 +81,7 @@ def record_dispatch_checkpoints(
|
|
|
73
81
|
lines.append(_record_worker_activity(
|
|
74
82
|
project_root, run_manifest, source=source,
|
|
75
83
|
kind="worker-dispatched", agent=job.worker_id,
|
|
76
|
-
summary=
|
|
84
|
+
summary=_dispatch_summary(job),
|
|
77
85
|
result_path=_project_relative(project_root, str(job.worker_result_path)),
|
|
78
86
|
outcome="pending",
|
|
79
87
|
))
|
|
@@ -88,6 +96,21 @@ def record_dispatch_checkpoints(
|
|
|
88
96
|
return [line for line in lines if line]
|
|
89
97
|
|
|
90
98
|
|
|
99
|
+
def _announces_worker_dispatch(job: WorkerJob) -> bool:
|
|
100
|
+
kind = job.dispatch_kind
|
|
101
|
+
if kind == _INITIAL or correction_round(kind) is not None:
|
|
102
|
+
return True
|
|
103
|
+
return is_reverify_dispatch_kind(kind) and invocation_in_correction_namespace(
|
|
104
|
+
job.invocation_id or job.invocation_ref
|
|
105
|
+
)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def _dispatch_summary(job: WorkerJob) -> str:
|
|
109
|
+
if job.dispatch_kind == _INITIAL:
|
|
110
|
+
return f"Dispatched {job.worker_id} as an initial worker"
|
|
111
|
+
return f"Dispatched {job.worker_id} for {job.dispatch_kind}"
|
|
112
|
+
|
|
113
|
+
|
|
91
114
|
def settled_initial_dispatches(
|
|
92
115
|
team_state: Mapping[str, Any],
|
|
93
116
|
) -> dict[str, Mapping[str, Any]]:
|
|
@@ -133,6 +133,7 @@ from .wrapper_status import (
|
|
|
133
133
|
log_path_for_prompt,
|
|
134
134
|
mutation_snapshot_path_for_prompt,
|
|
135
135
|
prompt_derived_paths,
|
|
136
|
+
read_log_tail,
|
|
136
137
|
read_wrapper_status,
|
|
137
138
|
status_path_for_prompt,
|
|
138
139
|
)
|
|
@@ -2015,8 +2016,7 @@ def _wrapper_failure_text(outcome: WorkerOutcome | None) -> str:
|
|
|
2015
2016
|
status = read_wrapper_status(outcome.status_sidecar_path)
|
|
2016
2017
|
if status is None:
|
|
2017
2018
|
return ""
|
|
2018
|
-
|
|
2019
|
-
return failure[:_MUTATION_REASON_FAILURE_LIMIT]
|
|
2019
|
+
return status.failure[:_MUTATION_REASON_FAILURE_LIMIT]
|
|
2020
2020
|
|
|
2021
2021
|
|
|
2022
2022
|
def _mutation_failure_reason(mutation, outcome: WorkerOutcome | None = None) -> str:
|
|
@@ -2604,15 +2604,7 @@ def _wrapper_log_tail(job: WorkerJob) -> str | None:
|
|
|
2604
2604
|
some process exited 1. Capped well under the writer's own excerpt limit
|
|
2605
2605
|
because a whole record must stay inside one atomic `PIPE_BUF` append.
|
|
2606
2606
|
"""
|
|
2607
|
-
|
|
2608
|
-
try:
|
|
2609
|
-
with log_path.open("rb") as handle:
|
|
2610
|
-
handle.seek(0, 2)
|
|
2611
|
-
handle.seek(max(0, handle.tell() - _WRAPPER_LOG_TAIL_BYTES))
|
|
2612
|
-
tail = handle.read()
|
|
2613
|
-
except OSError:
|
|
2614
|
-
return None
|
|
2615
|
-
return tail.decode("utf-8", errors="replace").strip() or None
|
|
2607
|
+
return read_log_tail(log_path_for_prompt(job.prompt_path), _WRAPPER_LOG_TAIL_BYTES)
|
|
2616
2608
|
|
|
2617
2609
|
|
|
2618
2610
|
def _transition_job_status(
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md
CHANGED
|
@@ -13,7 +13,7 @@ are collected and convergence finished. Phase 1-5 do not need it.
|
|
|
13
13
|
- **Plan link & approval evidence**: path to the approved `final-report.md`, the exact quoted approval marker, AND the executed stage number / title quoted from the Stage Map row. For a selected-direction plan, also quote `selectedDirectionRef.optionId`, `snapshotPath`, and the validated snapshot digest; for a legacy plan, quote the effective `implementation-option` or the Recommended Option fallback.
|
|
14
14
|
- **Commit list**: each commit's SHA (or short SHA), message, and the plan step(s) / TDD cycle it satisfies. A lead minor fix commit is listed too, with `planStep` `Lead minor fix (<finding ids>)`.
|
|
15
15
|
- **Lead minor fixes**: when the lead fixed verifier findings in this run, pass each `implementation.leadFixes[]` entry to the report writer as recorded (§"Lead minor fix"). Omit the field when there was none.
|
|
16
|
-
- **Correction rounds**: when this run ran correction rounds, pass one `implementation.correctionRounds[]` entry per round to the report writer — `round`, `findingIds`, `baseCommit`, `commit`, each verifier's re-verification `verifierVerdicts`, and `result` (§"Correction round"). `verifierResults` then carries the last round's verdicts. Omit the field when there was none.
|
|
16
|
+
- **Correction rounds**: when this run ran correction rounds, pass one `implementation.correctionRounds[]` entry per round to the report writer — `round`, `findingIds`, `baseCommit`, `commit`, each verifier's re-verification `verifierVerdicts`, and `result` (§"Correction round"). `verifierResults` then carries the last round's verdicts, and each row's `discrepancy` carries only a divergence in that verifier's last-round rerun: it stays empty when the last rerun matched. The change from an initial `FAIL` to a last-round `PASS` is recorded in `correctionRounds[].verifierVerdicts`, never in `discrepancy` — `_validate_verifier_discrepancy_is_not_passed` reads text there beside `PASS` as an unresolved divergence. The report-writer packet states this rule for every correction-round run (`report_synthesis_packet.ReportSynthesisPacket._task_instructions`). Omit the field when there was none.
|
|
17
17
|
- **Diff summary**: capture `git diff --stat <base>..<captured-head>` and `git diff --numstat <base>..<captured-head>` for the full implementation stage, including after a fix run. Supply both outputs to the report writer; put each file's added/deleted counts alone in `diffSummary.files[].lines` (`+150/-0`) and one sentence on what the change in that file does in `diffSummary.files[].summary` — the report renders `summary` as the file's "what it does" column and `lines` as a separate number column. Do not substitute a fix-run aggregate or carry forward older statistics. If the captured commits are unavailable, identify the missing reference in the evidence instead of inventing counts.
|
|
18
18
|
- **Change narrative scope**: `userNarrative.changeExplanation` describes the same scope as `diffSummary` — the whole stage from its base, every file the table lists. On a fix run, state what the fix run itself changed (its commits and files) as a separate sentence; never present the fix-run delta as the stage's change.
|
|
19
19
|
- **Out-of-plan edits block**: every file edited that was not in the approved plan's file list, with rationale (empty block is acceptable and preferred)
|
|
@@ -45,7 +45,7 @@ are collected and convergence finished. Phase 1-5 do not need it.
|
|
|
45
45
|
|
|
46
46
|
## Lead minor fix (decided after convergence, before the report-writer dispatch)
|
|
47
47
|
|
|
48
|
-
**Not in an evidence-contract run.** When the run manifest carries `verificationEvidenceVersion`, there is no lead minor fix: every fix, however small, goes through a correction round below, so the executor commits it and a new generation is sealed before the verifiers check it again. **Enforced:** `scripts/okstra_ctl/phases/implementation/validation.py` `_validate_lead_fixes` blocks any `implementation.leadFixes` entry in such a run, and `validate_settled_round_was_reverified` blocks a stage settled after correction round N without
|
|
48
|
+
**Not in an evidence-contract run.** When the run manifest carries `verificationEvidenceVersion`, there is no lead minor fix: every fix, however small, goes through a correction round below, so the executor commits it and a new generation is sealed before the verifiers check it again. **Enforced:** `scripts/okstra_ctl/phases/implementation/validation.py` `_validate_lead_fixes` blocks any `implementation.leadFixes` entry in such a run, and `validate_settled_round_was_reverified` blocks a stage settled after correction round N without the records of generation N + 1 of each verifier that generation gives a check it may run. Runs without the field keep the rules below.
|
|
49
49
|
|
|
50
50
|
When the synthesised verdict would be `FAIL` only because of verifier findings that are small and local, the lead fixes them itself in this run instead of ending it and opening a fix run. Decide after Phase 5.5 convergence, before building the report-writer dispatch prompt and before "Lead post-stage persistence" below. No worker dispatch is open then, so the edit falls inside no read-only worker's mutation audit window. Never edit while a verifier, convergence, or report-writer dispatch is running: its audit reports `readonly source changed` and discards that worker's result.
|
|
51
51
|
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md
CHANGED
|
@@ -235,7 +235,7 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
|
|
|
235
235
|
- **File-size limit (every verifier, not only the stage QA owner):** run `okstra correction file-size --base <base>` from the worktree cwd and log it in the `Read-only command log`. Each `FILE-SIZE:<path>:501 <before>-><after>` line it prints is a blocking finding cited exactly as printed — a new file over 500 lines, or a file the diff took from 500 or fewer past 500. A file already over 500 at the stage base that the diff grows is not blocking; the command prints it as an advisory line. Recommended fix: move whole responsibilities into new modules or test files beside it. The command writes nothing and its result is the same for every verifier, so the finding converges and the lead sends it to a correction round. Each `FILE-SIZE-ADVISORY:<path>:301` line (the 300-line target: a new file over 300, a file the diff took past 300, or a file already over 300 the diff grew, including one already over 500) goes under the advisory findings below, not here. Do not judge size yourself: a file it does not print is not a finding (lockfiles, data, Markdown, fixtures, snapshots, generated files and languages without a coding preflight are exempt by `scripts/okstra_ctl/file_size_cap.py` `capped_path`).
|
|
236
236
|
- **Caller-less identifier (YAGNI / orphan):** an identifier this diff leaves with zero callers — either newly added and never called (a speculative parameter, an optional config object, a "future-proof" hook, an exported helper whose only caller is hypothetical), or pre-existing code orphaned because this diff removed its last caller. Grep the identifier across the whole repository rather than the diff alone; a hit inside its own declaration, its own test, or a commented-out line is not a caller. Two exits are legitimate and must be **stated with their evidence**, never assumed: an identifier the approved plan reserves for a named later stage (cite the plan step), and a contract point something other than project code calls (a framework entrypoint, an implemented interface method, a migration hook, the public API of a published package — cite the caller or the registration). Anything else is work no requirement asked for: recommend deleting it, or folding an added parameter back into its single call site. A caller-less identifier is the one YAGNI violation that survives a green pipeline unchanged, which is why it grades here rather than as a recommendation.
|
|
237
237
|
- **Advisory findings (recorded as recommendations; verdict MAY still PASS):** each `FILE-SIZE-ADVISORY:` line from the file-size command (a file over the 300-line target but within 500), function >50 effective lines, a single body mixing read+write stages, weak readability, a missing-but-non-critical outcome assertion, weak-but-not-misleading names, priority-between-inputs policy inlined in a service condition instead of a named domain function, an error message asserting a cause the code never observed, a memory / concurrency / batching change with no test pinning the bound it claims, or (hexagonal overlay only) a service dependency this diff adds or modifies that injects a concrete adapter instead of a port — record it with the port sketch; advisory only while the project has not declared `architecture.style = hexagonal`, since that declaration — and only that one — promotes exactly this item to blocking per the declared-style bullet above, while a declared `layered` binds dependency direction instead and leaves this item advisory; an existing convention of concrete injections does not convert this one to `clean`, it is the debt the rule pays down. These land in the verifier result as `should-fix` / `nit` recommendations, not as a `FAIL`.
|
|
238
|
-
- **Output.** Every finding — blocking or advisory — is a structured item in the verifier's worker result (`path:line`, rule, severity, suggested fix) so it carries into Phase 5.5 convergence and the final report. A blocking hit sets the verifier verdict to `FAIL` with the rule cited, using the same verdict machinery as the Discrepancy rule above. The Okstra lead MUST NOT silently downgrade a cited blocking finding to advisory during synthesis; an override requires a concrete cited reason, exactly as for the Discrepancy rule.
|
|
238
|
+
- **Output.** Every finding — blocking or advisory — is a structured item in the verifier's worker result (`path:line`, rule, severity, suggested fix) so it carries into Phase 5.5 convergence and the final report. Each item, advisory items included, carries an item id as `prompts/profiles/_common-contract.md` "Cross-worker traceability" defines it for worker output. The lead cites a finding by that id, and `okstra convergence seed` refuses a cited id that does not occur in the result, so an unnumbered item cannot enter convergence and drops out of the report. This is a guideline: nothing parses a verifier result for missing ids. A blocking hit sets the verifier verdict to `FAIL` with the rule cited, using the same verdict machinery as the Discrepancy rule above. The Okstra lead MUST NOT silently downgrade a cited blocking finding to advisory during synthesis; an override requires a concrete cited reason, exactly as for the Discrepancy rule.
|
|
239
239
|
|
|
240
240
|
### Fix-run incremental scope (applies when the profile carries a "Fix-Run Carry" block)
|
|
241
241
|
|
|
@@ -257,4 +257,4 @@ This phase does not declare final acceptance. It says only ready for final-verif
|
|
|
257
257
|
| I-2 | A verifier cannot report a discrepancy with a PASS verdict. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_verifier_discrepancy_is_not_passed` |
|
|
258
258
|
| I-3 | Frozen legacy instruction pointers resolve within the selected installation without rewriting the frozen profile. | unenforced |
|
|
259
259
|
| I-4 | In a run marked `verificationEvidenceVersion: "1.0"`, each verifier's `executionEvidence` is the latest run of every check under its latest attempt of the invocation bound to the newest generation, with the recorded bytes and observation; a record that is not `completed` is incomplete collection. | `scripts/okstra_ctl/phases/implementation/validation.py::validate_verifier_execution_evidence` |
|
|
260
|
-
| I-5 | In a marked run, a `leadFixes` entry blocks the report, and a stage settled after correction round N shows
|
|
260
|
+
| I-5 | In a marked run, a `leadFixes` entry blocks the report, and a stage settled after correction round N shows the records of generation N + 1 of each verifier that generation gives a check it may run. Unmarked runs keep the lead-fix reading. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_lead_fixes`, `validate_settled_round_was_reverified` |
|
|
@@ -3,16 +3,23 @@ from __future__ import annotations
|
|
|
3
3
|
|
|
4
4
|
import re
|
|
5
5
|
from collections.abc import Callable, Mapping
|
|
6
|
+
from dataclasses import dataclass
|
|
6
7
|
from pathlib import Path
|
|
7
8
|
from typing import Any
|
|
8
9
|
|
|
10
|
+
from ...agent.invocation import AgentInvocationError, reserved_generation_reference
|
|
9
11
|
from ...correction_round import correction_round
|
|
12
|
+
from ...json_boundary import load_owned_object
|
|
10
13
|
from ...report_execution_evidence import (
|
|
11
14
|
EXECUTION_EVIDENCE_BLOCKING, collect_report_evidence, omitted_records, reference_errors,
|
|
12
15
|
)
|
|
13
16
|
from ...paths import RunRef
|
|
17
|
+
from ...qa_procedures import safe_qa_path
|
|
18
|
+
from ...registry.verification_inputs_store import default_verification_input_store
|
|
14
19
|
from ...verification_dispatch import generation_sealed_after_round
|
|
15
20
|
from ...verification_evidence import roster_verifier_role_execution_ref
|
|
21
|
+
from ...verification_generation import read_verification_generation
|
|
22
|
+
from ...worker_prompt_policy import stage_qa_owner
|
|
16
23
|
|
|
17
24
|
_PASSING_VERDICT_TOKENS = frozenset({"accepted", "conditional-accept"})
|
|
18
25
|
_CHECKLIST_ID_RE = re.compile(r"\bVC-\d{3,}\b")
|
|
@@ -453,13 +460,74 @@ def validate_verifier_execution_evidence(
|
|
|
453
460
|
f"verifier's execution records {omitted}")
|
|
454
461
|
|
|
455
462
|
|
|
463
|
+
@dataclass(frozen=True)
|
|
464
|
+
class _GenerationChecks:
|
|
465
|
+
qa: bool
|
|
466
|
+
conformance: bool
|
|
467
|
+
|
|
468
|
+
def owed_by(self, *, conformance_owner: bool) -> bool:
|
|
469
|
+
"""Whether a verifier has a check of this generation that evidence
|
|
470
|
+
mode lets it run: any frozen qaCommands entry, or a sealed conformance
|
|
471
|
+
stage for the stage QA owner."""
|
|
472
|
+
return self.qa or (self.conformance and conformance_owner)
|
|
473
|
+
|
|
474
|
+
|
|
475
|
+
def _generation_checks(
|
|
476
|
+
project_root: Path, manifest: Mapping[str, Any], generation_path: str,
|
|
477
|
+
) -> _GenerationChecks | None:
|
|
478
|
+
"""The kinds of check the generation at `generation_path` holds; None when
|
|
479
|
+
no verifier invocation is bound to it, so no verifier was dispatched after
|
|
480
|
+
the fix and every one still owes a record."""
|
|
481
|
+
root = project_root.resolve()
|
|
482
|
+
digest = _bound_generation_digest(root, manifest, generation_path)
|
|
483
|
+
if digest is None:
|
|
484
|
+
return None
|
|
485
|
+
generation_record = read_verification_generation(
|
|
486
|
+
safe_qa_path(root, generation_path), digest,
|
|
487
|
+
)
|
|
488
|
+
inputs = default_verification_input_store().read(
|
|
489
|
+
safe_qa_path(root, generation_record["verificationInputsPath"]),
|
|
490
|
+
generation_record["verificationInputsDigest"],
|
|
491
|
+
)
|
|
492
|
+
return _GenerationChecks(
|
|
493
|
+
qa=any(inputs["qaCommands"].values()),
|
|
494
|
+
conformance=bool(generation_record.get("conformanceStages")),
|
|
495
|
+
)
|
|
496
|
+
|
|
497
|
+
|
|
498
|
+
def _bound_generation_digest(
|
|
499
|
+
project_root: Path, manifest: Mapping[str, Any], generation_path: str,
|
|
500
|
+
) -> str | None:
|
|
501
|
+
"""The digest an invocation reservation of this run binds the generation at
|
|
502
|
+
`generation_path` to; None when no reservation binds it."""
|
|
503
|
+
contract = manifest.get("agentContract")
|
|
504
|
+
reservations = (contract.get("invocationReservationRootPath")
|
|
505
|
+
if isinstance(contract, Mapping) else None)
|
|
506
|
+
if not isinstance(reservations, str):
|
|
507
|
+
return None
|
|
508
|
+
for path in sorted(safe_qa_path(project_root, reservations).glob("*.json")):
|
|
509
|
+
reservation = load_owned_object(path, artifact="invocation reservation")
|
|
510
|
+
reference = reserved_generation_reference(
|
|
511
|
+
project_root, manifest, reservation["invocationRef"], reservation["attempt"],
|
|
512
|
+
)
|
|
513
|
+
if reference is not None and reference.path == generation_path:
|
|
514
|
+
return reference.digest
|
|
515
|
+
return None
|
|
516
|
+
|
|
517
|
+
|
|
456
518
|
def validate_settled_round_was_reverified(
|
|
457
519
|
data: dict, project_root: Path, manifest_path: Path,
|
|
458
520
|
manifest: Mapping[str, Any], failures: list[str],
|
|
459
521
|
) -> None:
|
|
460
522
|
"""A stage settled after correction round N in an evidence-contract run
|
|
461
|
-
shows
|
|
462
|
-
|
|
523
|
+
shows the records of generation N + 1, the one sealed after the executor's
|
|
524
|
+
fix, of each verifier that generation gives a check it may run.
|
|
525
|
+
|
|
526
|
+
Evidence mode refuses a `conformance:` check from anyone but the stage QA
|
|
527
|
+
owner, so with no frozen `qaCommands` entry the other verifiers can write no
|
|
528
|
+
record at all; requiring one from them made such a stage impossible to
|
|
529
|
+
settle.
|
|
530
|
+
"""
|
|
463
531
|
implementation = data.get("implementation")
|
|
464
532
|
if not isinstance(implementation, dict) or not _stage_settled(implementation):
|
|
465
533
|
return
|
|
@@ -470,9 +538,19 @@ def validate_settled_round_was_reverified(
|
|
|
470
538
|
generation = generation_sealed_after_round(max(rounds))
|
|
471
539
|
expected = RunRef.from_manifest(manifest_path, manifest).verification_generation(
|
|
472
540
|
generation).resolve().relative_to(project_root.resolve()).as_posix()
|
|
541
|
+
try:
|
|
542
|
+
checks = _generation_checks(project_root, manifest, expected)
|
|
543
|
+
except (AgentInvocationError, OSError, ValueError, KeyError) as exc:
|
|
544
|
+
failures.append(f"{_CORRECTION_BLOCKING} generation {generation} "
|
|
545
|
+
f"(`{expected}`) could not be read: {exc}")
|
|
546
|
+
return
|
|
547
|
+
owner = stage_qa_owner(manifest)
|
|
473
548
|
for who, row in _verifier_rows(data):
|
|
474
549
|
if row.get("verdict") == "not-run":
|
|
475
550
|
continue
|
|
551
|
+
if checks is not None and not checks.owed_by(
|
|
552
|
+
conformance_owner=row.get("verifier") == owner):
|
|
553
|
+
continue
|
|
476
554
|
references = [reference for reference in row.get("executionEvidence") or []
|
|
477
555
|
if isinstance(reference, dict)]
|
|
478
556
|
if not references or any((reference.get("generation") or {}).get("path")
|
|
@@ -151,3 +151,10 @@ PROSE_KEYS = frozenset({
|
|
|
151
151
|
"whyItMatters",
|
|
152
152
|
"workingAssumption",
|
|
153
153
|
})
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
# A stringified null is not prose. Lowercase `none` is a token the clarification
|
|
157
|
+
# option contract uses on purpose ("reverses nothing"), so only the capitalised
|
|
158
|
+
# and language-native spellings count — 2026-09-05 audit: `"None"` in 16
|
|
159
|
+
# trade-off cells and 2 option fields across the shipped reports.
|
|
160
|
+
NULL_LITERALS = frozenset({"None", "null", "undefined", "NaN"})
|
|
@@ -263,6 +263,14 @@ class ReportSynthesisPacket:
|
|
|
263
263
|
"state` is the initial round's. Describe the stage's open findings from the "
|
|
264
264
|
"last round's re-convergence, not the initial one; report what each round "
|
|
265
265
|
"fixed through `implementation.correctionRounds`.",
|
|
266
|
+
"`implementation.verifierResults[]` holds each verifier's last-round "
|
|
267
|
+
"verdict. Its `implementation.verifierResults[].discrepancy` records only "
|
|
268
|
+
"a divergence between that verifier's last-round rerun and the executor's "
|
|
269
|
+
"reported result: leave it empty when that rerun matched. A verdict that "
|
|
270
|
+
"changed between rounds (an initial `FAIL`, then `PASS`) is not a "
|
|
271
|
+
"discrepancy; `implementation.correctionRounds[].verifierVerdicts` records "
|
|
272
|
+
"it. `validate-run` reads any text in `discrepancy` beside a `PASS` "
|
|
273
|
+
"verdict as an unresolved divergence.",
|
|
266
274
|
]
|
|
267
275
|
if self.task_type != "implementation-option-selection":
|
|
268
276
|
return []
|
|
@@ -101,7 +101,9 @@ wrapper subprocess holding no pane, so there is nothing to close.
|
|
|
101
101
|
that never reached a terminal status.
|
|
102
102
|
|
|
103
103
|
On a cmux-pane run, dispatch records `phase-3-team-create` when it writes the
|
|
104
|
-
implicit-team marker, `phase-4-dispatch` for each `initial` job and
|
|
104
|
+
implicit-team marker, `phase-4-dispatch` for each `initial` job and each
|
|
105
|
+
job of an implementation correction round (`correction-r<N>`, and a
|
|
106
|
+
`reverify-r<k>` whose invocation id carries `-correction-r<N>-`), and
|
|
105
107
|
`phase-6-synthesis` on the first report-writer dispatch; await records
|
|
106
108
|
`phase-5-poll` on entry and again when the counts changed, and
|
|
107
109
|
`phase-5-collect` for each `initial` dispatch it settled. The lead does not
|
|
@@ -120,7 +120,9 @@ Native-session assignments remain owned by the active host session.
|
|
|
120
120
|
|
|
121
121
|
It records the lead checkpoints it owns and prints them as `progressLines`:
|
|
122
122
|
`phase-3-team-create` when it writes the implicit-team marker,
|
|
123
|
-
`phase-4-dispatch` for each `initial` job
|
|
123
|
+
`phase-4-dispatch` for each `initial` job and each job of an implementation
|
|
124
|
+
correction round (`correction-r<N>`, and a `reverify-r<k>` whose invocation id
|
|
125
|
+
carries `-correction-r<N>-`), `phase-6-synthesis` on the first
|
|
124
126
|
report-writer dispatch, and `phase-5-collect` for each `initial` dispatch it
|
|
125
127
|
settled. The lead emits those lines instead of calling
|
|
126
128
|
`okstra lead-progress append` for them.
|
|
@@ -20,6 +20,7 @@ class WrapperStatus:
|
|
|
20
20
|
# wrapper 가 init 에 기록한 자기 pid (`okstra-wrapper-status.py init`). 상태
|
|
21
21
|
# 파일을 못 쓰고 죽은 프로세스를 await 가 알아보는 유일한 단서다.
|
|
22
22
|
pid: int | None = None
|
|
23
|
+
failure: str = ""
|
|
23
24
|
|
|
24
25
|
@property
|
|
25
26
|
def is_terminal(self) -> bool:
|
|
@@ -45,6 +46,20 @@ def log_path_for_prompt(prompt_path: Path) -> Path:
|
|
|
45
46
|
return Path(f"{prompt_path}.log")
|
|
46
47
|
|
|
47
48
|
|
|
49
|
+
def read_log_tail(log_path: Path, max_bytes: int) -> str | None:
|
|
50
|
+
"""The last ``max_bytes`` of a worker log, decoded, or None when the log
|
|
51
|
+
is unreadable or blank. A CLI's own failure text usually sits there and
|
|
52
|
+
nowhere else."""
|
|
53
|
+
try:
|
|
54
|
+
with log_path.open("rb") as handle:
|
|
55
|
+
handle.seek(0, 2)
|
|
56
|
+
handle.seek(max(0, handle.tell() - max_bytes))
|
|
57
|
+
tail = handle.read()
|
|
58
|
+
except OSError:
|
|
59
|
+
return None
|
|
60
|
+
return tail.decode("utf-8", errors="replace").strip() or None
|
|
61
|
+
|
|
62
|
+
|
|
48
63
|
def mutation_snapshot_path_for_prompt(prompt_path: Path) -> Path:
|
|
49
64
|
"""Where okstra writes this prompt's pre-dispatch mutation snapshot."""
|
|
50
65
|
return prompt_path.with_suffix(prompt_path.suffix + ".mutation-audit.json")
|
|
@@ -86,6 +101,7 @@ def read_wrapper_status(path: Path) -> WrapperStatus | None:
|
|
|
86
101
|
log_path=_optional_path(raw.get("log_path")),
|
|
87
102
|
raw=raw,
|
|
88
103
|
pid=_optional_int(raw.get("pid")),
|
|
104
|
+
failure=raw["failure"].strip() if isinstance(raw.get("failure"), str) else "",
|
|
89
105
|
)
|
|
90
106
|
|
|
91
107
|
|
|
@@ -3430,11 +3430,6 @@ def _validate_no_opaque_id_references(data: dict, failures: list[str]) -> None:
|
|
|
3430
3430
|
)
|
|
3431
3431
|
|
|
3432
3432
|
|
|
3433
|
-
# A stringified null is not prose. Lowercase `none` is a token the clarification
|
|
3434
|
-
# option contract uses on purpose ("reverses nothing"), so only the capitalised
|
|
3435
|
-
# and language-native spellings count — 2026-09-05 audit: `"None"` in 16
|
|
3436
|
-
# trade-off cells and 2 option fields across the shipped reports.
|
|
3437
|
-
_NULL_LITERALS = frozenset({"None", "null", "undefined", "NaN"})
|
|
3438
3433
|
_FINDING_REF_RE = re.compile(r"^F-\d{3,}$")
|
|
3439
3434
|
# Citation lists the human page renders as links or plain text.
|
|
3440
3435
|
_CITATION_LIST_KEYS = ("evidenceRefs", "supportingEvidence", "falsifyingEvidenceChecked")
|
|
@@ -3462,10 +3457,12 @@ def _validate_no_null_literals_in_prose(data: dict, failures: list[str]) -> None
|
|
|
3462
3457
|
`None` under Test cost and Rollout cost. An empty value is spelled by
|
|
3463
3458
|
omitting the field or leaving it empty, never by naming the language's
|
|
3464
3459
|
null."""
|
|
3460
|
+
from okstra_ctl.report_prose_keys import NULL_LITERALS
|
|
3461
|
+
|
|
3465
3462
|
offenders = [
|
|
3466
3463
|
f"{pointer} = {value.strip()!r}"
|
|
3467
3464
|
for pointer, value in _prose_pointers(data)
|
|
3468
|
-
if value.strip() in
|
|
3465
|
+
if value.strip() in NULL_LITERALS
|
|
3469
3466
|
]
|
|
3470
3467
|
if offenders:
|
|
3471
3468
|
failures.append(
|