okstra 0.235.0 → 0.236.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 (68) 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.md +1 -1
  7. package/docs/cli.md +6 -0
  8. package/package.json +1 -1
  9. package/runtime/BUILD.json +2 -2
  10. package/runtime/bin/lib/okstra/usage.sh +8 -8
  11. package/runtime/bin/okstra-qwen-exec.sh +5 -0
  12. package/runtime/prompts/lead/convergence.md +4 -1
  13. package/runtime/prompts/lead/okstra-lead-contract.md +3 -3
  14. package/runtime/prompts/profiles/_common-contract.md +10 -1
  15. package/runtime/prompts/wizard/prompts.ko.json +16 -4
  16. package/runtime/python/okstra_ctl/adapters/providers/antigravity/adapter.py +10 -2
  17. package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py +16 -1
  18. package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +20 -5
  19. package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py +17 -9
  20. package/runtime/python/okstra_ctl/adapters/providers/qwen/adapter.py +88 -0
  21. package/runtime/python/okstra_ctl/adapters/providers/qwen/manifest.json +1 -0
  22. package/runtime/python/okstra_ctl/adapters/providers/qwen/settings.json +12 -0
  23. package/runtime/python/okstra_ctl/adapters/providers/zai/adapter.py +8 -2
  24. package/runtime/python/okstra_ctl/business_flow/contracts.py +11 -0
  25. package/runtime/python/okstra_ctl/business_flow/engine.py +90 -32
  26. package/runtime/python/okstra_ctl/business_flow/hooks.py +4 -2
  27. package/runtime/python/okstra_ctl/business_flow/source.py +39 -7
  28. package/runtime/python/okstra_ctl/business_flow/store.py +94 -28
  29. package/runtime/python/okstra_ctl/convergence.py +95 -5
  30. package/runtime/python/okstra_ctl/convergence_critic_verify_prompt.py +11 -10
  31. package/runtime/python/okstra_ctl/convergence_engine.py +30 -15
  32. package/runtime/python/okstra_ctl/convergence_reverify_prompt.py +9 -2
  33. package/runtime/python/okstra_ctl/coverage_census.py +75 -12
  34. package/runtime/python/okstra_ctl/entrypoints/hosts.py +1 -1
  35. package/runtime/python/okstra_ctl/lead_progress.py +1 -1
  36. package/runtime/python/okstra_ctl/model_discovery.py +1 -1
  37. package/runtime/python/okstra_ctl/models.py +2 -2
  38. package/runtime/python/okstra_ctl/phases/discussion/profile.md +2 -2
  39. package/runtime/python/okstra_ctl/phases/error_analysis/profile.md +1 -1
  40. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  41. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +2 -1
  42. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  43. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +3 -3
  44. package/runtime/python/okstra_ctl/phases/requirements_discovery/profile.md +5 -5
  45. package/runtime/python/okstra_ctl/registry/provider_registry.py +1 -1
  46. package/runtime/python/okstra_ctl/render_final_report.py +1 -1
  47. package/runtime/python/okstra_ctl/run.py +1 -1
  48. package/runtime/python/okstra_ctl/run_context.py +18 -3
  49. package/runtime/python/okstra_ctl/schema_excerpt.py +14 -9
  50. package/runtime/python/okstra_ctl/verdict_blocks.py +7 -2
  51. package/runtime/python/okstra_ctl/wizard/engine.py +28 -1
  52. package/runtime/python/okstra_ctl/wizard/ids.py +8 -0
  53. package/runtime/python/okstra_ctl/wizard/picker_navigation.py +64 -2
  54. package/runtime/python/okstra_ctl/wizard/roles.py +194 -45
  55. package/runtime/python/okstra_ctl/wizard/sources.py +10 -1
  56. package/runtime/python/okstra_ctl/wizard/state.py +67 -20
  57. package/runtime/python/okstra_ctl/wizard/steps_roles.py +6 -3
  58. package/runtime/python/okstra_ctl/wizard/worker_settings.py +129 -25
  59. package/runtime/python/okstra_ctl/worker_audit_ledger.py +44 -8
  60. package/runtime/python/okstra_ctl/worker_prompt_body.py +26 -2
  61. package/runtime/python/okstra_ctl/worker_prompt_headers.py +12 -9
  62. package/runtime/python/okstra_token_usage/claude.py +5 -1
  63. package/runtime/python/okstra_token_usage/collect.py +3 -3
  64. package/runtime/python/okstra_token_usage/pricing.py +1 -0
  65. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  66. package/runtime/skills/okstra-discussion/SKILL.md +1 -1
  67. package/runtime/skills/okstra-run/SKILL.md +2 -2
  68. package/runtime/templates/worker-prompt-preamble.md +12 -2
@@ -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)
@@ -22,13 +22,18 @@ from .convergence_provenance import id_occurs_wordbounded
22
22
  from .json_boundary import JsonBoundaryError, load_owned_object
23
23
  from .phases.improvement_discovery.lenses import LENSES, validate_priority_lenses
24
24
  from .scope_provenance import brief_end_state_id_sequence
25
+ from .worker_audit_ledger import named_files, recorded_as_opened
25
26
 
26
27
 
27
28
  CENSUS_SCHEMA_VERSION = "1.0"
29
+ RECORDS_EVIDENCE = "records"
28
30
  CENSUS_ASPECTS_LINE = "- Census aspects:"
29
31
  SCOPES = ("requirement", "task", "file", "lens")
32
+ # `[records]` marks an aspect that okstra's own records (brief, plan, other task
33
+ # records) may settle, so a `clean` citing only them is accepted.
30
34
  _ASPECT_RE = re.compile(
31
- r"^ - (?P<scope>[a-z]+) (?P<slug>[a-z0-9]+(?:-[a-z0-9]+)*):\s*(?P<question>\S.*)$"
35
+ r"^ - (?P<scope>[a-z]+) (?P<slug>[a-z0-9]+(?:-[a-z0-9]+)*)(?P<records> \[records\])?:"
36
+ r"\s*(?P<question>\S.*)$"
32
37
  )
33
38
 
34
39
 
@@ -41,6 +46,7 @@ class Aspect:
41
46
  scope: str
42
47
  slug: str
43
48
  question: str
49
+ records: bool = False
44
50
 
45
51
 
46
52
  def parse_census_aspects(profile_text: str) -> tuple[Aspect, ...]:
@@ -72,7 +78,10 @@ def parse_census_aspects(profile_text: str) -> tuple[Aspect, ...]:
72
78
  raise CensusError(
73
79
  f"census aspect scope {scope!r} is not one of {', '.join(SCOPES)}"
74
80
  )
75
- aspects.append(Aspect(scope, match.group("slug"), match.group("question").strip()))
81
+ aspects.append(Aspect(
82
+ scope, match.group("slug"), match.group("question").strip(),
83
+ records=match.group("records") is not None,
84
+ ))
76
85
  keys = [(aspect.scope, aspect.slug) for aspect in aspects]
77
86
  if len(keys) != len(set(keys)):
78
87
  raise CensusError("census aspects repeat a scope and slug pair")
@@ -101,6 +110,7 @@ def build_census(
101
110
  "aspect": aspect.slug,
102
111
  "subject": subject,
103
112
  "question": aspect.question,
113
+ **({"evidence": RECORDS_EVIDENCE} if aspect.records else {}),
104
114
  })
105
115
 
106
116
  by_scope = {
@@ -200,9 +210,13 @@ def render_census_section(census: Mapping[str, Any], census_rel_path: str) -> st
200
210
  "|---|---|---|---|",
201
211
  ]
202
212
  for cell in cells:
213
+ settled_by_records = (
214
+ " The brief or okstra records may settle it."
215
+ if cell.get("evidence") == RECORDS_EVIDENCE else ""
216
+ )
203
217
  rows.append(
204
218
  f"| `{cell['id']}` | {cell['scope']} | `{_cell_text(str(cell['subject']))}` "
205
- f"| {_cell_text(str(cell['question']))} |"
219
+ f"| {_cell_text(str(cell['question']) + settled_by_records)} |"
206
220
  )
207
221
  return "\n".join(rows)
208
222
 
@@ -265,12 +279,41 @@ def split_coverage_verdict_section(text: str) -> tuple[list[str], str]:
265
279
  return lines[start + 1:end], "\n".join(lines[:start] + lines[end:])
266
280
 
267
281
 
268
- def _judge(kind: str, rest: str, body_texts: Sequence[str]) -> tuple[str, str] | str:
269
- """``(kind, detail)`` for a usable verdict, otherwise why it is unusable."""
282
+ # Stage worktrees live under `~/.okstra/worktrees/`, so source cited by its
283
+ # absolute worktree path is not an okstra input.
284
+ _OKSTRA_INPUT_RE = re.compile(r"(?:^|/)\.okstra/(?!worktrees/)")
285
+
286
+
287
+ def _okstra_input(path: str) -> bool:
288
+ """One of okstra's own inputs: they pose the cell's question, they cannot clear it."""
289
+ return _OKSTRA_INPUT_RE.search(path) is not None
290
+
291
+
292
+ def _judge(
293
+ kind: str, rest: str, body_texts: Sequence[str], opened: frozenset[str] | None = None,
294
+ accepts_records: bool = False,
295
+ ) -> tuple[str, str] | str:
296
+ """``(kind, detail)`` for a usable verdict, otherwise why it is unusable.
297
+
298
+ ``opened`` holds the worker's recorded Evidence read paths; ``None`` means
299
+ the worker kept no ledger, so a clean is not checked against one.
300
+ """
270
301
  detail = rest.strip().lstrip(_SEPARATORS).strip()
271
302
  if kind == "clean":
272
303
  if not _CITATION_RE.search(detail):
273
304
  return "clean without a path:line citation"
305
+ sources = [path for path in named_files(detail) if not _okstra_input(path)]
306
+ if not sources and not accepts_records:
307
+ return "clean cites only .okstra/ artifacts, not the source it judges"
308
+ unopened = [
309
+ path for path in sources
310
+ if opened is not None and not recorded_as_opened(path, opened)
311
+ ]
312
+ if unopened:
313
+ return (
314
+ f"clean rests on `{unopened[0]}`, which the audit sidecar does not "
315
+ "record as opened"
316
+ )
274
317
  return kind, detail
275
318
  if kind == "n/a":
276
319
  if not detail:
@@ -290,12 +333,16 @@ def parse_cell_verdicts(
290
333
  cell_ids: Sequence[str],
291
334
  *,
292
335
  reference_texts: Sequence[str] = (),
336
+ opened: frozenset[str] | None = None,
337
+ record_cells: frozenset[str] = frozenset(),
293
338
  ) -> CellVerdicts:
294
339
  """Read a result's `Coverage Verdicts` section against ``cell_ids``.
295
340
 
296
341
  ``reference_texts`` are other results a `finding` may point into: a
297
342
  gap-fill result can cite an item its worker's first result already raised.
298
- The first usable line for a cell wins.
343
+ ``opened`` is the worker's Evidence read ledger, which a `clean` citation
344
+ must appear in. ``record_cells`` are cells whose `clean` may cite okstra
345
+ records alone. The first usable line for a cell wins.
299
346
  """
300
347
  section, body = split_coverage_verdict_section(result_text)
301
348
  wanted = list(dict.fromkeys(cell_ids))
@@ -315,7 +362,8 @@ def parse_cell_verdicts(
315
362
  if cell in verdicts:
316
363
  continue
317
364
  judged = _judge(
318
- match.group("kind").lower(), match.group("rest"), (body, *reference_texts)
365
+ match.group("kind").lower(), match.group("rest"), (body, *reference_texts), opened,
366
+ cell in record_cells,
319
367
  )
320
368
  if isinstance(judged, tuple):
321
369
  verdicts[cell] = judged
@@ -342,21 +390,33 @@ def audit_census(
342
390
  census: Mapping[str, Any],
343
391
  results: Mapping[str, str | None],
344
392
  gapfills: Mapping[str, str | None] | None = None,
393
+ opened: Mapping[str, frozenset[str] | None] | None = None,
394
+ gapfill_opened: Mapping[str, frozenset[str] | None] | None = None,
345
395
  ) -> dict[str, Any]:
346
396
  """Per-worker coverage of ``census``, the cell x worker matrix, and the
347
397
  cells two workers judged in opposite directions.
348
398
 
349
399
  ``results`` maps each analysis worker to its result text (``None``: the
350
400
  file is missing). ``gapfills`` does the same for the one gap-fill dispatch;
351
- a worker absent from it was not sent one. Whatever stays unjudged after
352
- both is ``unverdicted`` — recorded, never raised.
401
+ a worker absent from it was not sent one. ``opened`` and ``gapfill_opened``
402
+ map a worker to the Evidence read ledger of that result (``None`` or absent:
403
+ no ledger, no check). Whatever stays unjudged after both is ``unverdicted``
404
+ — recorded, never raised.
353
405
  """
354
406
  gapfills = gapfills or {}
407
+ opened = opened or {}
408
+ gapfill_opened = gapfill_opened or {}
355
409
  cell_ids = [str(cell["id"]) for cell in census.get("cells") or []]
410
+ record_cells = frozenset(
411
+ str(cell["id"]) for cell in census.get("cells") or []
412
+ if cell.get("evidence") == RECORDS_EVIDENCE
413
+ )
356
414
  workers: list[dict[str, Any]] = []
357
415
  judged: dict[str, dict[str, tuple[str, str]]] = {}
358
416
  for worker, text in results.items():
359
- first = parse_cell_verdicts(text or "", cell_ids)
417
+ first = parse_cell_verdicts(
418
+ text or "", cell_ids, opened=opened.get(worker), record_cells=record_cells,
419
+ )
360
420
  verdicts = dict(first.verdicts)
361
421
  missing = dict(first.missing)
362
422
  if text is None:
@@ -367,7 +427,8 @@ def audit_census(
367
427
  gapfill_status = "missing" if gapfill_text is None else "read"
368
428
  if gapfill_text is not None and missing:
369
429
  second = parse_cell_verdicts(
370
- gapfill_text, list(missing), reference_texts=(text or "",)
430
+ gapfill_text, list(missing), reference_texts=(text or "",),
431
+ opened=gapfill_opened.get(worker), record_cells=record_cells,
371
432
  )
372
433
  verdicts.update(second.verdicts)
373
434
  missing = {
@@ -446,7 +507,9 @@ requires, and only these two sections:
446
507
  evidence. Write `- none` when there is none. A `finding` may also cite an
447
508
  item ID from your first result.
448
509
  - `## 6. Coverage Verdicts` — one line per cell listed below, in the
449
- preamble's form: `clean — <path:line>`, `finding <ID>`, or `n/a — <reason>`.
510
+ preamble's form: `clean — <path:line>` citing project source (the brief or
511
+ okstra records only where the cell says they may settle it), `finding <ID>`,
512
+ or `n/a — <reason>`.
450
513
 
451
514
  Do not judge cells that are not listed, and do not repeat your first result.
452
515
  """.strip()
@@ -233,7 +233,7 @@ def _probe_paths(project_root: str, home_dir: str):
233
233
 
234
234
  def _unclaimed_host_message(registry: HostAdapterRegistry, command: str) -> str:
235
235
  runtime_flag = "--runtime" if command in {
236
- "install", "ensure-installed", "doctor"
236
+ "install", "ensure-installed", "doctor", "preflight"
237
237
  } else "--lead-runtime"
238
238
  allowed = "|".join(registry.ids())
239
239
  return (
@@ -317,7 +317,7 @@ def _append(args: argparse.Namespace) -> int:
317
317
 
318
318
  _CLI_EPILOG = r"""Usage:
319
319
  okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-1-intake
320
- okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-4-dispatch --worker codex-worker --field model=gpt-6.1-sol
320
+ okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-4-dispatch --worker codex-worker --field model=gpt-6.2-sol
321
321
  okstra lead-progress append --project-root <dir> --run-manifest <path> --phase phase-5-collect --worker codex-worker --field status=completed
322
322
 
323
323
  `progressLine` in the output is the line to emit to the user, verbatim.
@@ -45,7 +45,7 @@ def agy_tier_suffixes() -> frozenset[str]:
45
45
  어휘다. 둘은 다르다: 정책이 지금 붙이는 것은 `high` 뿐이지만, 관측값에는
46
46
  다른 티어가 실려 올 수 있다.
47
47
  """
48
- return frozenset({"high", "medium", "low"})
48
+ return frozenset({"high", "medium", "low", "xhigh"})
49
49
 
50
50
 
51
51
  @lru_cache(maxsize=1)
@@ -35,8 +35,8 @@ IMPLEMENTATION_ROLES = frozenset({"executor", "verifier"})
35
35
  # Legacy role-keyed compatibility defaults. Canonical assignments resolve a
36
36
  # provider first and then use ProviderSpec.default_models for that role.
37
37
  ROLE_DEFAULTS = {
38
- "lead": "opus", "claude": "opus", "codex": "gpt-6.1-sol",
39
- "antigravity": "gemini-3.1-pro", "report-writer": "sonnet",
38
+ "lead": "opus", "claude": "opus", "codex": "gpt-6.2-sol",
39
+ "antigravity": "gemini-4-argon", "report-writer": "sonnet",
40
40
  }
41
41
 
42
42
 
@@ -35,10 +35,10 @@
35
35
  - keep factual claims (what the code or an external source does) apart from questions only the user can answer (intent, scope, priority, acceptable risk)
36
36
  - for each alternative direction, state what it requires, what it excludes and the risk it carries, without ranking it into a decision the user has not made
37
37
  - Census aspects:
38
- - task subject-framing: What exactly is the subject and the question to settle, and where does the request leave it ambiguous?
38
+ - task subject-framing [records]: What exactly is the subject and the question to settle, and where does the request leave it ambiguous?
39
39
  - task factual-claims: Which claims about the current code or external facts bear on the decision, and what evidence establishes or refutes each?
40
40
  - task alternative-directions: Which alternative directions exist, and what does each require, exclude and risk?
41
- - task user-decisions: Which questions can only the user answer, and what does each answer change?
41
+ - task user-decisions [records]: Which questions can only the user answer, and what does each answer change?
42
42
  - Cross-verification mode:
43
43
  - Phase 5.5 convergence runs in **adversarial mode** for factual claims. Verifiers try to refute each claim by re-inspecting the cited evidence. A convergence stop ends one verification cycle; it does not end the discussion.
44
44
  - A participant checking its own claim is not an independent refutation.
@@ -20,7 +20,7 @@
20
20
  - **Fix-design boundary:** do not design the implementation fix beyond what is necessary to validate the cause. Record whether the cause is credible and the next diagnostic. The common Phase Routing settles the next phase.
21
21
  - Census aspects:
22
22
  - requirement pass-observation: Which observation would show the symptom resolved for this requirement?
23
- - task symptom-lock: Which single observable failure condition does the reported symptom translate to?
23
+ - task symptom-lock [records]: Which single observable failure condition does the reported symptom translate to?
24
24
  - task reproduction: Was the symptom reproduced, not reproduced, or blocked before reproduction, and on what evidence?
25
25
  - task cause-falsification: For each cause candidate, which evidence that could falsify it was checked?
26
26
  - task next-diagnostic: Which diagnostic should run next, and which signal would confirm or reject the leading cause?
@@ -12,7 +12,7 @@
12
12
  - In `preselected-validation` mode, validate the one preselected direction: its evidence, counterevidence, criterion scores, and requirement mappings, and state the same feasibility verdict with its rationale and counterevidence. The worker must not generate new candidates.
13
13
  - Do not produce detailed file lists, stage maps, execution commands, or a plan approval request.
14
14
  - Census aspects:
15
- - requirement mapping: Which candidate or preselected direction satisfies this requirement, and how?
15
+ - requirement mapping [records]: Which candidate or preselected direction satisfies this requirement, and how?
16
16
  - requirement support: Which inspected evidence supports that mapping?
17
17
  - requirement counter-evidence: What is the strongest evidence against that mapping?
18
18
  - task feasibility: Is each candidate feasible, not feasible, or uncertain on inspected evidence?
@@ -1026,7 +1026,8 @@ def _render_prior_round(entry: object) -> str:
1026
1026
  return "".join(rows)
1027
1027
 
1028
1028
 
1029
- # 검증자의 읽기 범위(`**Read scope:**`)는 `## Inputs` 에 열거된 경로만 허용한다.
1029
+ # The verifier's read scope admits okstra artifacts only when the prompt
1030
+ # enumerates them, as `## Inputs` does here.
1030
1031
  # 이 절이 없으면 P-Req 의 originalRequirementId 를 패킷의 요구 문장으로 되짚을
1031
1032
  # 수 없어 범위를 지킨 검증자는 verification-error 를 낸다.
1032
1033
  _INPUT_FIELDS = (
@@ -695,7 +695,7 @@ applies unchanged: append it verbatim after the response format below.
695
695
  `okstra plan-items prompt` renders the `## Inputs` section itself: a
696
696
  `- Primary analysis packet:` line from the run manifest's `analysisPacketPath`
697
697
  and a `- Plan narrative:` line from its `reportNarrativePath`. The worker's
698
- `**Read scope:**` header admits only paths the prompt enumerates, so these lines
698
+ `**Read scope:**` header admits `.okstra/` artifacts only when the prompt enumerates them, so these lines
699
699
  are what let a verifier read the requirement a selected-direction `P-Req-*` row
700
700
  names by `originalRequirementId`. The lead does not add them by hand.
701
701
 
@@ -26,10 +26,10 @@ Plan for the actual worktree layout before approval. Shared documentation direct
26
26
  - identify requirement gaps and affected interfaces with file:line evidence, resolving codebase-answerable ambiguity before returning findings
27
27
  - surface migration, deployment, cross-project, and approval risks without drafting final-report headings or schema rows
28
28
  - Census aspects:
29
- - requirement plan-linkage: Which planned files and stages realize this requirement?
29
+ - requirement plan-linkage [records]: Which planned files and stages realize this requirement?
30
30
  - requirement interface-impact: Which interfaces does realizing this requirement change, and who calls them?
31
- - requirement validation: Which validation step proves this requirement once the plan is executed?
32
- - task migration-deploy-approval-risk: Which migration, deployment, cross-project, or approval risk does the plan carry?
31
+ - requirement validation [records]: Which validation step proves this requirement once the plan is executed?
32
+ - task migration-deploy-approval-risk [records]: Which migration, deployment, cross-project, or approval risk does the plan carry?
33
33
  - Legacy candidate-comparison-only responsibilities:
34
34
  - **Legacy candidate-comparison procedure** — only a legacy rerun without `selected-direction.json` compares feasible Option Candidates, preserves their trade-offs and Recommended Option, then produces stages, validation, rollback, and requirement coverage. This is the only branch that generates candidates, assigns candidate scores, recommends a direction, or awaits a user candidate choice.
35
35
  - **Spec-settled short-circuit** — when the brief already carries a decision-complete design the reporter has confirmed, do not re-litigate it. Preserve that design as the Recommended Option and its already-weighed alternatives as the remaining Option Candidates.
@@ -16,16 +16,16 @@
16
16
  - state the reporter's rejection criteria, missing routing inputs, and the evidence boundary behind each recommendation
17
17
  - Census aspects:
18
18
  - requirement interpretation: What does this requirement ask for, read against the brief and the code it touches?
19
- - requirement scope-boundary: Where does this requirement stop, and which nearby behaviour does it leave out?
19
+ - requirement scope-boundary [records]: Where does this requirement stop, and which nearby behaviour does it leave out?
20
20
  - requirement dependency: What must exist or happen first for this requirement, in code or in a related task?
21
21
  - requirement verification-method: How would a later phase observe that this requirement is met?
22
- - requirement human-decision: Does this requirement need a decision only a person can make? Name it, or cite the code that settles it.
22
+ - requirement human-decision [records]: Does this requirement need a decision only a person can make? Name it, or cite the code that settles it.
23
23
  - task classification: Which work category (bugfix, feature, improvement, refactor, ops) does the evidence support?
24
- - task rejection-criteria: Which delivered outcome would the reporter reject?
25
- - task missing-materials: Which missing material blocks reliable routing?
24
+ - task rejection-criteria [records]: Which delivered outcome would the reporter reject?
25
+ - task missing-materials [records]: Which missing material blocks reliable routing?
26
26
  - task terminology: Which fuzzy or overloaded terms need one canonical form, and what decides it?
27
27
  - task existing-reuse: Which existing code path, export, test seam or helper should this work reuse instead of adding a new one?
28
- - task related-work: Which related, follow-up or blocking task does this work overlap, and which units stay in or out of this split?
28
+ - task related-work [records]: Which related, follow-up or blocking task does this work overlap, and which units stay in or out of this split?
29
29
  - task input-consistency: Where do the brief, packet and recorded decisions contradict each other or the code?
30
30
  - task shared-impact: Which shared type, model, package or consumer outside the stated scope does this change reach?
31
31
  - Primary focus areas:
@@ -13,7 +13,7 @@ from ..json_boundary import JsonBoundaryError, load_owned_object
13
13
  from .factory_loader import FactoryLoadError, load_relative_factory
14
14
 
15
15
 
16
- _PROVIDER_DISPLAY_ORDER = ("claude", "codex", "grok", "antigravity", "zai", "kimi")
16
+ _PROVIDER_DISPLAY_ORDER = ("claude", "codex", "grok", "antigravity", "zai", "kimi", "qwen")
17
17
 
18
18
 
19
19
  def provider_display_order(provider_id: str) -> tuple[int, str]: