okstra 0.235.0 → 0.237.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 (80) hide show
  1. package/dist/lib/host-registry-client.d.mts +9 -2
  2. package/dist/lib/host-registry-client.mjs +29 -3
  3. package/dist/lib/host-registry-client.mjs.map +1 -1
  4. package/dist/lib/runtime-payload.mjs +1 -0
  5. package/dist/lib/runtime-payload.mjs.map +1 -1
  6. package/docs/architecture/storage-model.md +1 -0
  7. package/docs/architecture.md +2 -2
  8. package/docs/cli.md +6 -0
  9. package/package.json +1 -1
  10. package/runtime/BUILD.json +2 -2
  11. package/runtime/bin/lib/okstra/usage.sh +8 -8
  12. package/runtime/bin/okstra-qwen-exec.sh +5 -0
  13. package/runtime/prompts/lead/convergence.md +4 -1
  14. package/runtime/prompts/lead/okstra-lead-contract.md +4 -4
  15. package/runtime/prompts/profiles/_clarification-recommendation.md +1 -1
  16. package/runtime/prompts/profiles/_common-contract.md +10 -1
  17. package/runtime/prompts/wizard/prompts.ko.json +16 -4
  18. package/runtime/python/okstra_ctl/adapters/providers/antigravity/adapter.py +10 -2
  19. package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py +16 -1
  20. package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +20 -5
  21. package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py +17 -9
  22. package/runtime/python/okstra_ctl/adapters/providers/qwen/adapter.py +88 -0
  23. package/runtime/python/okstra_ctl/adapters/providers/qwen/manifest.json +1 -0
  24. package/runtime/python/okstra_ctl/adapters/providers/qwen/settings.json +12 -0
  25. package/runtime/python/okstra_ctl/adapters/providers/zai/adapter.py +8 -2
  26. package/runtime/python/okstra_ctl/approval_decisions.py +22 -2
  27. package/runtime/python/okstra_ctl/business_flow/contracts.py +11 -0
  28. package/runtime/python/okstra_ctl/business_flow/engine.py +90 -32
  29. package/runtime/python/okstra_ctl/business_flow/hooks.py +4 -2
  30. package/runtime/python/okstra_ctl/business_flow/source.py +39 -7
  31. package/runtime/python/okstra_ctl/business_flow/store.py +94 -28
  32. package/runtime/python/okstra_ctl/convergence.py +95 -5
  33. package/runtime/python/okstra_ctl/convergence_critic_verify_prompt.py +11 -10
  34. package/runtime/python/okstra_ctl/convergence_engine.py +30 -15
  35. package/runtime/python/okstra_ctl/convergence_reverify_prompt.py +9 -2
  36. package/runtime/python/okstra_ctl/coverage_census.py +75 -12
  37. package/runtime/python/okstra_ctl/entrypoints/hosts.py +1 -1
  38. package/runtime/python/okstra_ctl/lead_progress.py +1 -1
  39. package/runtime/python/okstra_ctl/manager_cli.py +42 -5
  40. package/runtime/python/okstra_ctl/manager_launch.py +60 -1
  41. package/runtime/python/okstra_ctl/manager_store.py +45 -0
  42. package/runtime/python/okstra_ctl/model_discovery.py +1 -1
  43. package/runtime/python/okstra_ctl/models.py +2 -2
  44. package/runtime/python/okstra_ctl/phases/discussion/profile.md +2 -2
  45. package/runtime/python/okstra_ctl/phases/error_analysis/profile.md +1 -1
  46. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  47. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +2 -1
  48. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +3 -3
  50. package/runtime/python/okstra_ctl/phases/requirements_discovery/profile.md +5 -5
  51. package/runtime/python/okstra_ctl/plan_item_evidence.py +25 -1
  52. package/runtime/python/okstra_ctl/registry/provider_registry.py +1 -1
  53. package/runtime/python/okstra_ctl/render_final_report.py +1 -1
  54. package/runtime/python/okstra_ctl/run.py +1 -1
  55. package/runtime/python/okstra_ctl/run_context.py +18 -3
  56. package/runtime/python/okstra_ctl/schema_excerpt.py +14 -9
  57. package/runtime/python/okstra_ctl/verdict_blocks.py +7 -2
  58. package/runtime/python/okstra_ctl/wizard/cli.py +14 -2
  59. package/runtime/python/okstra_ctl/wizard/engine.py +28 -1
  60. package/runtime/python/okstra_ctl/wizard/ids.py +8 -0
  61. package/runtime/python/okstra_ctl/wizard/picker_navigation.py +64 -2
  62. package/runtime/python/okstra_ctl/wizard/roles.py +194 -45
  63. package/runtime/python/okstra_ctl/wizard/sources.py +10 -1
  64. package/runtime/python/okstra_ctl/wizard/state.py +71 -21
  65. package/runtime/python/okstra_ctl/wizard/statefile.py +8 -3
  66. package/runtime/python/okstra_ctl/wizard/steps_roles.py +6 -3
  67. package/runtime/python/okstra_ctl/wizard/worker_settings.py +129 -25
  68. package/runtime/python/okstra_ctl/worker_audit_ledger.py +50 -8
  69. package/runtime/python/okstra_ctl/worker_prompt_body.py +26 -2
  70. package/runtime/python/okstra_ctl/worker_prompt_headers.py +12 -9
  71. package/runtime/python/okstra_token_usage/claude.py +5 -1
  72. package/runtime/python/okstra_token_usage/collect.py +3 -3
  73. package/runtime/python/okstra_token_usage/pricing.py +1 -0
  74. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  75. package/runtime/skills/okstra-discussion/SKILL.md +1 -1
  76. package/runtime/skills/okstra-manager/SKILL.md +8 -2
  77. package/runtime/skills/okstra-run/SKILL.md +2 -2
  78. package/runtime/skills/okstra-setup/SKILL.md +34 -5
  79. package/runtime/skills/okstra-setup/references/project-config.md +19 -0
  80. package/runtime/templates/worker-prompt-preamble.md +12 -2
@@ -2,6 +2,7 @@ from __future__ import annotations
2
2
 
3
3
  import re
4
4
  from collections import Counter
5
+ from collections.abc import Sequence
5
6
  from pathlib import Path
6
7
  from typing import Any, cast
7
8
 
@@ -29,6 +30,8 @@ from .source import candidate_projects, capture_project, knowledge_projects
29
30
 
30
31
  CONFIRMED_LEVELS = frozenset({"static", "execution-verified"})
31
32
  PACKET_CLAIM_LIMIT = 40
33
+ # Words every brief title or task id carries, which name no business.
34
+ _GENERIC_FOCUS_WORDS = frozenset({"task", "brief", "story", "feature", "with", "from", "that", "this"})
32
35
 
33
36
 
34
37
  def task_link_path(project_root: Path, task_key: str) -> Path:
@@ -141,7 +144,7 @@ def _claim(
141
144
 
142
145
 
143
146
  def _mark_conflicts(claims: list[StoredClaim]) -> None:
144
- groups: dict[str, list[StoredClaim]] = {}
147
+ groups: dict[tuple[str, str], list[StoredClaim]] = {}
145
148
  for claim in claims:
146
149
  if claim["level"] not in CONFIRMED_LEVELS or claim["status"] == "superseded":
147
150
  continue
@@ -149,10 +152,7 @@ def _mark_conflicts(claims: list[StoredClaim]) -> None:
149
152
  not row["digest"] for row in claim["sourceStates"].values()
150
153
  ):
151
154
  continue
152
- state = {key: row["digest"] for key, row in claim["sourceStates"].items()}
153
- groups.setdefault(
154
- fingerprint({"key": claim["key"], "states": state}), []
155
- ).append(claim)
155
+ groups.setdefault((claim["key"], _source_version(claim)), []).append(claim)
156
156
  for rows in groups.values():
157
157
  if len({row["value"] for row in rows}) > 1:
158
158
  for row in rows:
@@ -203,20 +203,16 @@ def validate_resolutions(
203
203
  "conflict resolution references unknown or repeated claims"
204
204
  )
205
205
  rows = _resolution_rows(data["claims"], resolution)
206
- state = fingerprint(
207
- {key: source["digest"] for key, source in rows[0]["sourceStates"].items()}
206
+ expected_ids = next(
207
+ (
208
+ {row["id"] for row in candidate}
209
+ for candidate in conflict_groups(data["claims"])
210
+ if candidate[0]["key"] == rows[0]["key"]
211
+ and _source_version(candidate[0]) == _source_version(rows[0])
212
+ ),
213
+ set(),
208
214
  )
209
- group = {
210
- row["id"]
211
- for row in data["claims"]
212
- if row["key"] == rows[0]["key"]
213
- and row["status"] == "conflict"
214
- and fingerprint(
215
- {key: source["digest"] for key, source in row["sourceStates"].items()}
216
- )
217
- == state
218
- }
219
- if ids != group:
215
+ if ids != expected_ids:
220
216
  raise BusinessFlowError(
221
217
  "conflict resolution must cover the complete active conflict"
222
218
  )
@@ -232,17 +228,24 @@ def _resolution_rows(
232
228
  if not ids.issubset(by_id) or resolution["acceptedClaimId"] not in ids:
233
229
  raise BusinessFlowError("conflict resolution references unknown claims")
234
230
  rows = [by_id[key] for key in ids]
235
- states = {
236
- fingerprint(
237
- {key: state["digest"] for key, state in row["sourceStates"].items()}
238
- )
239
- for row in rows
240
- }
241
- if len({row["key"] for row in rows}) != 1 or len(states) != 1:
231
+ if len({row["key"] for row in rows}) != 1 or len({_source_version(row) for row in rows}) != 1:
242
232
  raise BusinessFlowError("conflict resolution mixes subjects or source versions")
243
233
  return rows
244
234
 
245
235
 
236
+ def conflict_groups(claims: Sequence[StoredClaim]) -> list[list[StoredClaim]]:
237
+ """Claims in conflict on one key at one source version: what one resolution covers."""
238
+ groups: dict[tuple[str, str], dict[str, StoredClaim]] = {}
239
+ for claim in claims:
240
+ if claim["status"] == "conflict":
241
+ groups.setdefault((claim["key"], _source_version(claim)), {})[claim["id"]] = claim
242
+ return [list(group.values()) for group in groups.values()]
243
+
244
+
245
+ def _source_version(claim: StoredClaim) -> str:
246
+ return fingerprint({key: state["digest"] for key, state in claim["sourceStates"].items()})
247
+
248
+
246
249
  def read_shared_knowledge(project_root: Path, project_group: str) -> dict[str, Any]:
247
250
  claims, resolutions, errors = [], [], []
248
251
  candidates = knowledge_projects(
@@ -250,6 +253,9 @@ def read_shared_knowledge(project_root: Path, project_group: str) -> dict[str, A
250
253
  )
251
254
  for candidate in candidates:
252
255
  root = Path(candidate["root"])
256
+ # A project removed after it ran stays in run history; it has no store to read.
257
+ if not root.is_dir():
258
+ continue
253
259
  try:
254
260
  data = read_knowledge(root)
255
261
  claims.extend({**claim, "ownerRoot": str(root)} for claim in data["claims"])
@@ -387,17 +393,69 @@ def source_freshness(
387
393
  return "current" if source_states else "unverified"
388
394
 
389
395
 
396
+ def _words(text: str) -> set[str]:
397
+ return set(re.findall(r"[a-z0-9]+", text.casefold()))
398
+
399
+
400
+ def focus_terms(text: str) -> tuple[str, ...]:
401
+ """The words of a task's identity (task group, brief title) that can name a business."""
402
+ return tuple(sorted(
403
+ word for word in _words(text)
404
+ if len(word) >= 4 and not word.isdigit() and word not in _GENERIC_FOCUS_WORDS
405
+ ))
406
+
407
+
408
+ def task_focus(task_key: str, brief: str) -> tuple[str, ...]:
409
+ """The task group and the brief's title: what this task is about, without the brief's template."""
410
+ group = task_key.split(":")[1:2]
411
+ title = [line for line in brief.splitlines() if line.startswith("# ")][:1]
412
+ return focus_terms(" ".join([*group, *title]))
413
+
414
+
415
+ def _shares_stem(word: str, term: str) -> bool:
416
+ """Same word, its plural, or one a prefix of the other when both are long."""
417
+ if word == term or (min(len(word), len(term)) >= 4 and _singular(word) == _singular(term)):
418
+ return True
419
+ return min(len(word), len(term)) >= 6 and (word.startswith(term) or term.startswith(word))
420
+
421
+
422
+ def _singular(word: str) -> str:
423
+ return word[:-2] if word.endswith("es") and len(word) > 4 else word.removesuffix("s")
424
+
425
+
426
+ def _mentions(row: dict[str, Any], terms: Sequence[str]) -> bool:
427
+ words = _words(" ".join([row["business"], row["key"], row["value"], *row.get("aliases", [])]))
428
+ return any(_shares_stem(word, term) for word in words for term in terms)
429
+
430
+
431
+ def split_by_focus(
432
+ claims: list[dict[str, Any]], focus: Sequence[str]
433
+ ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
434
+ """Claims that mention one of the task's focus terms, and the rest."""
435
+ focused = [row for row in claims if _mentions(row, focus)]
436
+ return focused, [row for row in claims if not _mentions(row, focus)]
437
+
438
+
390
439
  def knowledge_packet(
391
- project_root: Path, question: str, source_root: Path | None = None
440
+ project_root: Path, question: str, source_root: Path | None = None,
441
+ focus: Sequence[str] = (),
392
442
  ) -> str:
443
+ """The packet's knowledge section.
444
+
445
+ `question` is the whole brief, so its words select nearly every stored claim.
446
+ `focus` holds the task's identity terms;
447
+ when given, only claims that mention one of them are shown and the rest are
448
+ left to lookup.
449
+ """
393
450
  try:
394
451
  result = query_knowledge(project_root, question, source_root)
395
452
  except (OSError, BusinessFlowError, JsonBoundaryError) as exc:
396
453
  return f"## Shared Business Knowledge\n\nKnowledge unavailable: {exc}\n"
397
- # 질문이 task-brief 전체라 토큰 매칭이 거의 모든 claim 을 고르므로, 선택 결과는
398
- # 관련도 순위가 아니다. 이 프로젝트가 기록한 claim 을 앞세우고 나머지는 조회로 넘긴다.
399
454
  own = str(project_root.resolve())
400
455
  claims = sorted(result["claims"], key=lambda row: row["ownerRoot"] != own)
456
+ unrelated: list[dict[str, Any]] = []
457
+ if focus:
458
+ claims, unrelated = split_by_focus(claims, focus)
401
459
  shown, omitted = claims[:PACKET_CLAIM_LIMIT], claims[PACKET_CLAIM_LIMIT:]
402
460
  lines = [
403
461
  "## Shared Business Knowledge",
@@ -427,6 +485,14 @@ def knowledge_packet(
427
485
  f"- {len(omitted)} more selected claims are omitted; look them up by business: "
428
486
  + ", ".join(f"`{name}` ({count})" for name, count in counts.most_common())
429
487
  )
488
+ if unrelated:
489
+ counts = Counter(row["business"] for row in unrelated)
490
+ lines.append(
491
+ f"- {len(unrelated)} stored claims do not mention this task's terms ("
492
+ + ", ".join(f"`{term}`" for term in focus)
493
+ + "); look them up by business if one applies: "
494
+ + ", ".join(f"`{name}` ({count})" for name, count in counts.most_common())
495
+ )
430
496
  lines.extend(f"- Knowledge read error: {error}" for error in result["errors"])
431
497
  lines.extend(
432
498
  [
@@ -1592,6 +1592,61 @@ def _recorded_results(
1592
1592
  return result_args
1593
1593
 
1594
1594
 
1595
+ # Verdicts that accept the cited evidence. `_grounded_vote` also checks a
1596
+ # burden-not-met refusal, which re-inspected it; counter-evidence stands on what
1597
+ # the verifier found instead.
1598
+ _GROUNDED_VERDICTS = ("agree", "supplement")
1599
+
1600
+
1601
+ def _origin_evidence_paths(plan_path: Path) -> dict[str, frozenset[str]]:
1602
+ """Each queued finding's cited files, from the working state beside the round plan.
1603
+
1604
+ ``plan-round`` writes `convergence-round-<N>-plan-<suffix>.json` next to the
1605
+ `convergence-work-<suffix>.json` it planned from. A plan named otherwise has
1606
+ no working state to read, and its votes are collected as given.
1607
+ """
1608
+ match = re.fullmatch(r"convergence-round-\d+-plan-(?P<suffix>.+)\.json", Path(plan_path).name)
1609
+ path = Path(plan_path).with_name(f"convergence-work-{match['suffix']}.json") if match else None
1610
+ if path is None or not path.is_file():
1611
+ return {}
1612
+ from .worker_audit_ledger import named_files
1613
+
1614
+ findings = load_owned_json_object(path).get("findings") or []
1615
+ return {
1616
+ str(row["findingId"]): frozenset(named_files(str(row.get("originEvidence") or "")))
1617
+ for row in findings if isinstance(row, Mapping) and row.get("findingId")
1618
+ }
1619
+
1620
+
1621
+ def _grounded_vote(vote: FindingVote, origin: frozenset[str] | None) -> dict[str, Any]:
1622
+ """The vote as collected; one that opened none of the cited files counts as unverifiable.
1623
+
1624
+ Evidence that names no file (a query result, prose) leaves nothing to compare,
1625
+ so such a vote is collected as given.
1626
+ """
1627
+ from .worker_audit_ledger import recorded_as_opened
1628
+
1629
+ row = {
1630
+ "verdict": vote.verdict,
1631
+ "disagreeBasis": vote.disagree_basis,
1632
+ "explanation": vote.explanation,
1633
+ }
1634
+ leans_on_origin = vote.verdict in _GROUNDED_VERDICTS or vote.disagree_basis == "burden-not-met"
1635
+ if not origin or not leans_on_origin:
1636
+ return row
1637
+ if any(recorded_as_opened(cited, frozenset(vote.opened)) for cited in origin):
1638
+ return row
1639
+ return {
1640
+ "verdict": "unverifiable",
1641
+ "disagreeBasis": None,
1642
+ "explanation": (
1643
+ "Collected as unverifiable: the Opened line names none of the cited files ("
1644
+ + ", ".join(sorted(origin)) + "). " + vote.explanation
1645
+ ),
1646
+ }
1647
+
1648
+
1649
+
1595
1650
  def _collect_results(args: argparse.Namespace) -> tuple[str, Path]:
1596
1651
  plan = load_owned_json_object(args.plan)
1597
1652
  planned = _planned_finding_ids(plan)
@@ -1624,14 +1679,13 @@ def _collect_results(args: argparse.Namespace) -> tuple[str, Path]:
1624
1679
  "close their attempt as ok — a discarded or failed attempt's file is not "
1625
1680
  "a vote"
1626
1681
  )
1682
+ origins = _origin_evidence_paths(args.plan)
1627
1683
  by_finding: dict[str, dict[str, Any]] = {}
1628
1684
  for worker, parsed in votes.items():
1629
1685
  for finding_id, vote in parsed.items():
1630
- by_finding.setdefault(finding_id, {})[worker] = {
1631
- "verdict": vote.verdict,
1632
- "disagreeBasis": vote.disagree_basis,
1633
- "explanation": vote.explanation,
1634
- }
1686
+ by_finding.setdefault(finding_id, {})[worker] = _grounded_vote(
1687
+ vote, origins.get(finding_id),
1688
+ )
1635
1689
  write_json_atomic(args.output, {
1636
1690
  "schemaVersion": "1.0",
1637
1691
  "round": plan.get("round"),
@@ -2123,6 +2177,36 @@ def _read_if_present(path: Path) -> str | None:
2123
2177
  return path.read_text(encoding="utf-8") if path.is_file() else None
2124
2178
 
2125
2179
 
2180
+ def _evidence_ledger(result_path: Path) -> frozenset[str] | None:
2181
+ """The Evidence read paths of a result's audit sidecar.
2182
+
2183
+ ``None`` when the result's prompt asked for no ledger — the rule
2184
+ validate-run applies — so a result of such a prompt is not checked. A prompt
2185
+ that asked for one and a sidecar without rows give an empty ledger.
2186
+ """
2187
+ from .worker_artifact_paths import WorkerArtifactPathError, audit_sidecar_rel
2188
+ from .worker_audit_ledger import audit_evidence_read_paths, ledger_required
2189
+
2190
+ prefix, separator, rest = result_path.name.partition("-worker-")
2191
+ prompt = result_path.parent.parent / "prompts" / f"{prefix}-worker-prompt-{rest}"
2192
+ if not separator or not ledger_required(prompt):
2193
+ return None
2194
+ try:
2195
+ sidecar = result_path.with_name(audit_sidecar_rel(result_path.name))
2196
+ except WorkerArtifactPathError:
2197
+ return None
2198
+ return frozenset(audit_evidence_read_paths(_read_if_present(sidecar) or ""))
2199
+
2200
+
2201
+ def _joined_ledger(
2202
+ first: frozenset[str] | None, gapfill: frozenset[str] | None,
2203
+ ) -> frozenset[str] | None:
2204
+ """A gap-fill without its own ledger is not checked: it may cite files it opened anew."""
2205
+ if gapfill is None:
2206
+ return None
2207
+ return gapfill | (first or frozenset())
2208
+
2209
+
2126
2210
  def _census_audit(args: argparse.Namespace) -> dict[str, Any]:
2127
2211
  """Audit the census verdicts. Unjudged cells are data, never an error."""
2128
2212
  authority = validated_run_authority(args.run_manifest)
@@ -2141,10 +2225,16 @@ def _census_audit(args: argparse.Namespace) -> dict[str, Any]:
2141
2225
  raise ConvergenceContractError(
2142
2226
  f"--gapfill names {unrostered}, which no --result names"
2143
2227
  )
2228
+ first_ledgers = {worker: _evidence_ledger(path) for worker, path in result_paths.items()}
2144
2229
  audit = audit_census(
2145
2230
  census,
2146
2231
  {worker: _read_if_present(path) for worker, path in result_paths.items()},
2147
2232
  {worker: _read_if_present(path) for worker, path in gapfill_paths.items()},
2233
+ opened=first_ledgers,
2234
+ gapfill_opened={
2235
+ worker: _joined_ledger(first_ledgers.get(worker), _evidence_ledger(path))
2236
+ for worker, path in gapfill_paths.items()
2237
+ },
2148
2238
  )
2149
2239
  for row in audit["workers"]:
2150
2240
  row["resultPath"] = relative_to_project_root(
@@ -9,7 +9,7 @@
9
9
 
10
10
  이 모듈이 그 지시문을 만든다. 입력은 리드가 `apply-critic-gaps` 에 줄 것과 같은
11
11
  coverage 배치(투표 전, `gaps[]` 만 채운 상태)와 Round 0 그룹(분석 로스터)이다.
12
- 배정은 엔진과 같은 규칙(`critic_gap_assignees`, 로스터 순서 round-robin)이라
12
+ 배정은 엔진과 같은 규칙(`critic_gap_assignees`: all analysers up to two, otherwise round-robin)이라
13
13
  `apply-critic-gaps` 의 커버리지 검사와 어긋나지 않는다. gap 마다 critic 결과
14
14
  파일의 `### [<gapId>]` 절과 critic 감사 사이드카를 실어, 검증자가 리드의 전사가
15
15
  아니라 critic 이 실제로 인용한 것을 판단하게 한다. 응답 형식은 번호 라운드와
@@ -131,10 +131,11 @@ def critic_verify_gaps(
131
131
  ) -> list[CriticGap]:
132
132
  """이 워커에게 배정된 gap 을 배치 순서대로.
133
133
 
134
- 배정은 `critic_gap_assignees` 와 같다: 선언된 중복을 뺀 gap *i* 가
135
- `roster[i % len(roster)]` 에게 간다. 로스터는 Round 0 그룹의 분석 audience
136
- 워커 순서다 — `apply-critic-gaps` 가 `analyserRoster` 로 적는 것과 같은
137
- 순서다.
134
+ The assignment is `critic_gap_assignees`: every analyser verifies every gap
135
+ on a roster of `FULL_GAP_VERIFICATION_ROSTER` or fewer, otherwise gap *i*
136
+ goes to `roster[i % len(roster)]`. The roster is the Round 0 groups'
137
+ analysis workers in order, the order `apply-critic-gaps` records as
138
+ `analyserRoster`.
138
139
  """
139
140
  gaps_value = batch.get("gaps")
140
141
  if not isinstance(gaps_value, list) or not gaps_value:
@@ -153,17 +154,17 @@ def critic_verify_gaps(
153
154
  gap for gap in gaps_value
154
155
  if isinstance(gap, Mapping) and not gap.get("duplicateOf")
155
156
  ]
156
- assignees = critic_gap_assignees(roster, verifiable)
157
+ verifiers_by_gap = critic_gap_assignees(roster, verifiable)
157
158
  assigned: list[CriticGap] = []
158
159
  seen: set[str] = set()
159
- for gap, assignee in zip(verifiable, assignees):
160
+ for gap, verifiers in zip(verifiable, verifiers_by_gap):
160
161
  gap_id = _nonempty_string(gap.get("gapId"))
161
162
  if not gap_id:
162
163
  raise CriticVerifyPromptError("coverage batch gap has no gapId")
163
164
  if gap_id in seen:
164
165
  raise CriticVerifyPromptError(f"duplicate critic gapId: {gap_id}")
165
166
  seen.add(gap_id)
166
- if assignee != worker_id:
167
+ if worker_id not in verifiers:
167
168
  continue
168
169
  ticket_ids = gap.get("ticketIds")
169
170
  assigned.append(CriticGap(
@@ -177,8 +178,8 @@ def critic_verify_gaps(
177
178
  ))
178
179
  if not assigned:
179
180
  raise CriticVerifyPromptError(
180
- f"round-robin assigns no gap to `{worker_id}`; assignees in batch "
181
- f"order: {', '.join(assignees) or 'none'}"
181
+ f"no gap is assigned to `{worker_id}`; verifiers in batch order: "
182
+ + (", ".join("+".join(verifiers) for verifiers in verifiers_by_gap) or "none")
182
183
  )
183
184
  return assigned
184
185
 
@@ -1136,26 +1136,34 @@ def _parse_critic_dispatches(
1136
1136
  return dispatches, completed
1137
1137
 
1138
1138
 
1139
+ # With this many analysers or fewer, every gap goes to all of them: one
1140
+ # verifier per gap lets a single shallow pass decide what merges into the report.
1141
+ FULL_GAP_VERIFICATION_ROSTER = 2
1142
+
1143
+
1139
1144
  def critic_gap_assignees(
1140
1145
  roster_order: list[str],
1141
1146
  gaps: list[Mapping[str, Any]],
1142
- ) -> list[str]:
1143
- """gap 하나당 검증자 한 명. 로스터 순서 위의 round-robin 이다.
1147
+ ) -> list[tuple[str, ...]]:
1148
+ """The verifiers of each gap, in batch order.
1144
1149
 
1145
- 종전 계약은 gap 배치를 분석자 전원에게 부치라고 요구했다. 거부도 승인과 같은
1146
- 값을 치르는데, 그 라운드는 `rounds: []` 로 기록조차 남지 않는 직렬 구간이다.
1147
- gap 마다 검증자 하나면 gap 이 로스터보다 적을 때 디스패치 수가 그만큼 줄고,
1148
- 많을 때는 각 분석자가 전체가 아니라 자기 몫만 읽는다.
1150
+ A roster of `FULL_GAP_VERIFICATION_ROSTER` or fewer verifies every gap in
1151
+ full. A larger roster is walked round-robin, one verifier per gap: a
1152
+ rejection costs the same as an acceptance in a stretch recorded as
1153
+ `rounds: []`, so each analyser reads only its share.
1149
1154
 
1150
- 선언한 중복(`duplicateOf`)은 배정에서 빠진다 — 검증하지 않기로 한 gap 이다.
1155
+ Declared duplicates (`duplicateOf`) are not assigned; they are not verified.
1151
1156
  """
1152
1157
  verifiable = [gap for gap in gaps if not gap.get("duplicateOf")]
1153
1158
  if not roster_order:
1154
1159
  return []
1155
- return [
1156
- roster_order[index % len(roster_order)]
1157
- for index in range(len(verifiable))
1158
- ]
1160
+ if len(roster_order) <= FULL_GAP_VERIFICATION_ROSTER:
1161
+ return [tuple(roster_order) for _ in verifiable]
1162
+ return [(worker,) for worker in _round_robin_assignees(roster_order, len(verifiable))]
1163
+
1164
+
1165
+ def _round_robin_assignees(roster_order: list[str], count: int) -> list[str]:
1166
+ return [roster_order[index % len(roster_order)] for index in range(count)]
1159
1167
 
1160
1168
 
1161
1169
  def _critic_gap_coverage_errors(
@@ -1174,13 +1182,20 @@ def _critic_gap_coverage_errors(
1174
1182
  계약 위반이 아니라 더 본 것이고, 그 사이 방치된 gap 은 표가 없어
1175
1183
  `unverifiedGaps` 로 스스로 드러난다.
1176
1184
  """
1177
- assignees = set(critic_gap_assignees(roster_order, gaps))
1178
- if dispatched == set(roster_order) or dispatched == assignees:
1185
+ assignees = {
1186
+ worker for verifiers in critic_gap_assignees(roster_order, gaps) for worker in verifiers
1187
+ }
1188
+ # A run finished under the earlier one-verifier rule dispatched the round-robin set.
1189
+ earlier = set(_round_robin_assignees(
1190
+ roster_order, len([gap for gap in gaps if not gap.get("duplicateOf")]),
1191
+ )) if roster_order else set()
1192
+ if dispatched in (set(roster_order), assignees, earlier):
1179
1193
  return []
1180
1194
  missing = sorted(assignees - dispatched)
1181
1195
  return [
1182
- "critic dispatches must cover every gap exactly once (round-robin over "
1183
- "the analyser roster) or account for every non-critic analyser exactly "
1196
+ "critic dispatches must cover every gap's assigned verifiers (all analysers "
1197
+ f"up to {FULL_GAP_VERIFICATION_ROSTER}, otherwise round-robin) or account "
1198
+ "for every non-critic analyser exactly "
1184
1199
  f"once; missing: {', '.join(missing) or 'none'}"
1185
1200
  ]
1186
1201
 
@@ -94,7 +94,14 @@ ADVERSARIAL_RESPONSE = """### <finding-id>
94
94
  **Basis** (only if REFUTED): counter-evidence | burden-not-met
95
95
  **Explanation** (required for every verdict, SURVIVES included): <2-3 sentences; for
96
96
  SURVIVES say what you attacked and why the attack failed; for counter-evidence include
97
- the file:line you found>"""
97
+ the file:line you found>
98
+ **Opened**: <every file you opened for this finding, as path:line, comma-separated>"""
99
+
100
+ # `okstra convergence collect-results` enforces this for round votes
101
+ # (`convergence._grounded_vote`); critic and acceptance votes are not collected there.
102
+ OPENED_RULE = """A SURVIVES, SURVIVES-WITH-CAVEAT or burden-not-met verdict whose `**Opened**` line
103
+ names none of the files the finding cites is collected as UNVERIFIABLE: a verdict
104
+ on evidence you did not open is not a vote."""
98
105
 
99
106
  def _nonempty_string(value: Any) -> str:
100
107
  return value if isinstance(value, str) and value.strip() else ""
@@ -222,7 +229,7 @@ def reverify_prompt_body(
222
229
  "collector also reads `**Verdict:** …` and `- Verdict: …` as the same field.\n\n"
223
230
  )
224
231
  rows.append(ADVERSARIAL_RESPONSE.replace("<finding-id>", findings[0].finding_id))
225
- rows.append("\n")
232
+ rows.append("\n\n" + OPENED_RULE + "\n")
226
233
  if len(findings) > 1:
227
234
  rows.append(f"\n### {findings[1].finding_id}\n**Verdict**: ...\n")
228
235
  return "".join(rows)