okstra 0.234.1 → 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 (171) hide show
  1. package/dist/cli-registry.mjs +7 -0
  2. package/dist/cli-registry.mjs.map +1 -1
  3. package/dist/commands/implementation-report/implementation-report.d.mts +1 -0
  4. package/dist/commands/implementation-report/implementation-report.mjs +73 -0
  5. package/dist/commands/implementation-report/implementation-report.mjs.map +1 -0
  6. package/dist/commands/trace/comparison.d.mts +39 -0
  7. package/dist/commands/trace/comparison.mjs +138 -0
  8. package/dist/commands/trace/comparison.mjs.map +1 -0
  9. package/dist/commands/trace/document.d.mts +8 -0
  10. package/dist/commands/trace/document.mjs +37 -0
  11. package/dist/commands/trace/document.mjs.map +1 -0
  12. package/dist/commands/trace/line-counts.d.mts +15 -0
  13. package/dist/commands/trace/line-counts.mjs +107 -0
  14. package/dist/commands/trace/line-counts.mjs.map +1 -0
  15. package/dist/commands/trace/model.d.mts +2 -1
  16. package/dist/commands/trace/model.mjs +13 -1
  17. package/dist/commands/trace/model.mjs.map +1 -1
  18. package/dist/commands/trace/progression.mjs +7 -3
  19. package/dist/commands/trace/progression.mjs.map +1 -1
  20. package/dist/commands/trace/task-link.d.mts +3 -0
  21. package/dist/commands/trace/task-link.mjs.map +1 -1
  22. package/dist/commands/trace/trace.mjs +64 -44
  23. package/dist/commands/trace/trace.mjs.map +1 -1
  24. package/dist/lib/host-registry-client.d.mts +9 -2
  25. package/dist/lib/host-registry-client.mjs +29 -3
  26. package/dist/lib/host-registry-client.mjs.map +1 -1
  27. package/dist/lib/python-helper.d.mts +1 -1
  28. package/dist/lib/python-helper.mjs +11 -5
  29. package/dist/lib/python-helper.mjs.map +1 -1
  30. package/dist/lib/runtime-payload.mjs +1 -0
  31. package/dist/lib/runtime-payload.mjs.map +1 -1
  32. package/dist/lib/types.d.mts +1 -0
  33. package/docs/architecture/storage-model.md +50 -0
  34. package/docs/architecture.md +1 -1
  35. package/docs/cli.md +37 -15
  36. package/docs/project-structure-overview.md +6 -1
  37. package/package.json +1 -1
  38. package/runtime/BUILD.json +2 -2
  39. package/runtime/agents/operations/trace-tests-review.json +6 -0
  40. package/runtime/bin/lib/okstra/usage.sh +8 -8
  41. package/runtime/bin/okstra-qwen-exec.sh +5 -0
  42. package/runtime/prompts/duties/test-reviewer.json +32 -0
  43. package/runtime/prompts/lead/convergence.md +4 -1
  44. package/runtime/prompts/lead/okstra-lead-contract.md +3 -3
  45. package/runtime/prompts/lead/report-writer.md +13 -1
  46. package/runtime/prompts/profiles/_common-contract.md +10 -1
  47. package/runtime/prompts/wizard/prompts.ko.json +16 -4
  48. package/runtime/python/okstra_ctl/adapters/providers/antigravity/adapter.py +10 -2
  49. package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py +16 -1
  50. package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +20 -5
  51. package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py +17 -9
  52. package/runtime/python/okstra_ctl/adapters/providers/qwen/adapter.py +88 -0
  53. package/runtime/python/okstra_ctl/adapters/providers/qwen/manifest.json +1 -0
  54. package/runtime/python/okstra_ctl/adapters/providers/qwen/settings.json +12 -0
  55. package/runtime/python/okstra_ctl/adapters/providers/zai/adapter.py +8 -2
  56. package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
  57. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
  58. package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
  59. package/runtime/python/okstra_ctl/business_flow/contracts.py +11 -0
  60. package/runtime/python/okstra_ctl/business_flow/engine.py +90 -32
  61. package/runtime/python/okstra_ctl/business_flow/hooks.py +4 -2
  62. package/runtime/python/okstra_ctl/business_flow/source.py +39 -7
  63. package/runtime/python/okstra_ctl/business_flow/store.py +94 -28
  64. package/runtime/python/okstra_ctl/code_review_census.py +38 -0
  65. package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
  66. package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
  67. package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
  68. package/runtime/python/okstra_ctl/code_review_target.py +16 -6
  69. package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
  70. package/runtime/python/okstra_ctl/consumers.py +6 -1
  71. package/runtime/python/okstra_ctl/convergence.py +95 -5
  72. package/runtime/python/okstra_ctl/convergence_critic_verify_prompt.py +11 -10
  73. package/runtime/python/okstra_ctl/convergence_engine.py +30 -15
  74. package/runtime/python/okstra_ctl/convergence_reverify_prompt.py +9 -2
  75. package/runtime/python/okstra_ctl/coverage_census.py +75 -12
  76. package/runtime/python/okstra_ctl/design_review.py +6 -26
  77. package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
  78. package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
  79. package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
  80. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  81. package/runtime/python/okstra_ctl/entrypoints/hosts.py +1 -1
  82. package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
  83. package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
  84. package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
  85. package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
  86. package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
  87. package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
  88. package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
  89. package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
  90. package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
  91. package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
  92. package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
  93. package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
  94. package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
  95. package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
  96. package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
  97. package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
  98. package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
  99. package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
  100. package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
  101. package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
  102. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
  103. package/runtime/python/okstra_ctl/json_boundary.py +28 -8
  104. package/runtime/python/okstra_ctl/lead_progress.py +1 -1
  105. package/runtime/python/okstra_ctl/model_discovery.py +1 -1
  106. package/runtime/python/okstra_ctl/models.py +2 -2
  107. package/runtime/python/okstra_ctl/paths.py +7 -4
  108. package/runtime/python/okstra_ctl/phases/discussion/profile.md +2 -2
  109. package/runtime/python/okstra_ctl/phases/error_analysis/profile.md +1 -1
  110. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  111. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +2 -1
  112. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  113. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +3 -3
  114. package/runtime/python/okstra_ctl/phases/requirements_discovery/profile.md +5 -5
  115. package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
  116. package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
  117. package/runtime/python/okstra_ctl/registry/provider_registry.py +1 -1
  118. package/runtime/python/okstra_ctl/render.py +4 -0
  119. package/runtime/python/okstra_ctl/render_final_report.py +1 -1
  120. package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
  121. package/runtime/python/okstra_ctl/report_finalize.py +18 -4
  122. package/runtime/python/okstra_ctl/report_html/render.py +46 -7
  123. package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
  124. package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
  125. package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
  126. package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
  127. package/runtime/python/okstra_ctl/run.py +17 -1
  128. package/runtime/python/okstra_ctl/run_context.py +18 -3
  129. package/runtime/python/okstra_ctl/schema_excerpt.py +14 -9
  130. package/runtime/python/okstra_ctl/stage_done.py +11 -3
  131. package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
  132. package/runtime/python/okstra_ctl/stage_map.py +3 -3
  133. package/runtime/python/okstra_ctl/trace_review.py +1 -0
  134. package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
  135. package/runtime/python/okstra_ctl/verdict_blocks.py +7 -2
  136. package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
  137. package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
  138. package/runtime/python/okstra_ctl/verification_generation.py +3 -2
  139. package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
  140. package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
  141. package/runtime/python/okstra_ctl/wizard/engine.py +28 -1
  142. package/runtime/python/okstra_ctl/wizard/ids.py +8 -0
  143. package/runtime/python/okstra_ctl/wizard/picker_navigation.py +64 -2
  144. package/runtime/python/okstra_ctl/wizard/roles.py +194 -45
  145. package/runtime/python/okstra_ctl/wizard/sources.py +10 -1
  146. package/runtime/python/okstra_ctl/wizard/state.py +67 -20
  147. package/runtime/python/okstra_ctl/wizard/steps_roles.py +6 -3
  148. package/runtime/python/okstra_ctl/wizard/worker_settings.py +129 -25
  149. package/runtime/python/okstra_ctl/worker_audit_ledger.py +44 -8
  150. package/runtime/python/okstra_ctl/worker_prompt_body.py +26 -2
  151. package/runtime/python/okstra_ctl/worker_prompt_headers.py +12 -9
  152. package/runtime/python/okstra_token_usage/claude.py +5 -1
  153. package/runtime/python/okstra_token_usage/collect.py +3 -3
  154. package/runtime/python/okstra_token_usage/pricing.py +1 -0
  155. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
  156. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  157. package/runtime/skills/okstra-code-review/SKILL.md +1 -1
  158. package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
  159. package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
  160. package/runtime/skills/okstra-discussion/SKILL.md +1 -1
  161. package/runtime/skills/okstra-run/SKILL.md +33 -2
  162. package/runtime/skills/okstra-tdd/SKILL.md +74 -13
  163. package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
  164. package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
  165. package/runtime/templates/reports/html/i18n/en.json +113 -0
  166. package/runtime/templates/reports/html/i18n/ko.json +113 -0
  167. package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
  168. package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
  169. package/runtime/templates/trace/trace.template.md +2 -0
  170. package/runtime/templates/worker-prompt-preamble.md +12 -2
  171. package/runtime/validators/validate-report-views.py +4 -36
@@ -0,0 +1,134 @@
1
+ """Read the current completed implementation generation and its consumed inputs."""
2
+ from __future__ import annotations
3
+
4
+ from dataclasses import dataclass
5
+ from pathlib import Path
6
+ from typing import Callable, Iterable, Mapping
7
+
8
+ from .agent.invocation import reserved_invocation_metadata_path, verify_agent_invocation
9
+ from .conformance_evidence import BoundInvocation, RunVerifiers, bound_attempt, evidence_read_errors, load_run_verifiers
10
+ from .execution_identity import Invocation
11
+ from .json_boundary import ArtifactByteReader, PageBudgetExhausted, ReadBudget, read_bounded_bytes
12
+ from .qa_procedures import project_artifact_relative_path, read_fingerprinted_artifact, safe_qa_path
13
+ from .verification_dispatch import implementation_generation_frontier, read_completed_attempt_result, verification_generation_number
14
+ from .verification_evidence import implementation_verifier_roster, roster_verifier_role_execution_ref
15
+ from .verification_generation import VerificationGenerationRecord
16
+ from .verification_invocation import VerificationGenerationReference, read_invocation_generation, verification_generation_required
17
+
18
+ SETTLED_ARTIFACT_BYTES = 16 * 1024 * 1024
19
+ SETTLED_READ_BYTES = 192 * 1024 * 1024
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class SettledImplementationGeneration:
24
+ reference: VerificationGenerationReference | None
25
+ record: VerificationGenerationRecord | None
26
+ limitations: tuple[str, ...]
27
+ attempts: tuple[tuple[str, int], ...]
28
+ fingerprints: Mapping[str, str | None]
29
+
30
+
31
+ def _selected_implementation_attempts(
32
+ run: RunVerifiers, frontier: int,
33
+ ) -> tuple[Invocation, int, list[tuple[BoundInvocation, int]]]:
34
+ execution = run.execution
35
+ if execution is None or execution.legacy:
36
+ raise ValueError("current implementation generation requires execution identity v2")
37
+ executors = [(index, row) for index, row in enumerate(execution.invocations)
38
+ if row.duty_id == "implementation-executor"]
39
+ if not executors:
40
+ raise ValueError("current implementation generation has no executor invocation")
41
+ executor_index, executor = executors[-1]
42
+ if verification_generation_number(executor.dispatch_kind) != frontier:
43
+ raise ValueError("current executor and verifiers name different generations")
44
+ executor_attempt = run.latest_attempt.get(executor.invocation_ref)
45
+ if executor_attempt is None:
46
+ raise ValueError("current implementation executor has no attempt")
47
+ executor_row = next(row for row in execution.attempts
48
+ if (row.invocation_ref, row.attempt) == (executor.invocation_ref, executor_attempt))
49
+ if executor_row.status != "ok" or executor_row.finished_at is None:
50
+ raise ValueError("current implementation executor attempt is incomplete or failed")
51
+ if executor_attempt > 1:
52
+ raise ValueError("generation does not record which executor retry its verifiers observed")
53
+ selected = []
54
+ for worker in implementation_verifier_roster(run.manifest):
55
+ role = roster_verifier_role_execution_ref(run.manifest, worker)
56
+ if role is None:
57
+ raise ValueError(f"{worker} has no bound verifier role execution")
58
+ bindings = run.verifiers.get(role, [])
59
+ current = bound_attempt(run, role, frontier)
60
+ latest = max(bindings, key=lambda binding: binding.index, default=None)
61
+ if current is None or current[0] != latest:
62
+ raise ValueError(f"{worker} has no current bound verifier attempt")
63
+ binding, attempt = current
64
+ if binding.index <= executor_index:
65
+ raise ValueError(f"{worker} verification predates the current executor attempt")
66
+ selected.append(current)
67
+ if len({binding.invocation.role_execution_ref for binding, _ in selected}) != len(selected):
68
+ raise ValueError("current implementation verifier roles are not distinct")
69
+ return executor, executor_attempt, selected
70
+
71
+
72
+ def read_settled_implementation_generation(
73
+ project: Path, manifest_path: Path, *, reader: ArtifactByteReader | None = None,
74
+ directory_entries: Callable[[Path], Iterable[Path]] | None = None,
75
+ ) -> SettledImplementationGeneration:
76
+ """Read the current completed implementation generation, without approving its verdict."""
77
+ project = project.resolve()
78
+ fingerprints: dict[str, str | None] = {}
79
+ budget = ReadBudget(SETTLED_READ_BYTES)
80
+ attempts: tuple[tuple[str, int], ...] = ()
81
+
82
+ def read_input(path: Path) -> bytes:
83
+ path = safe_qa_path(project, path.relative_to(project).as_posix())
84
+ return reader(path) if reader is not None else read_bounded_bytes(
85
+ path, max_bytes=SETTLED_ARTIFACT_BYTES, artifact="implementation generation input", budget=budget,
86
+ )
87
+
88
+ def observed(path: Path) -> bytes:
89
+ return read_fingerprinted_artifact(project, path, read_input, fingerprints)
90
+
91
+ try:
92
+ with evidence_read_errors():
93
+ manifest_path = project / project_artifact_relative_path(project, manifest_path)
94
+ run = load_run_verifiers(project, manifest_path, reader=observed)
95
+ if run.manifest.get("taskType") != "implementation":
96
+ raise ValueError("settled implementation generation requires an implementation run")
97
+ if not verification_generation_required(run.manifest, "implementation-verifier"):
98
+ raise ValueError("historical run has no verification evidence generation contract")
99
+ if run.execution is None:
100
+ raise ValueError("implementation execution snapshot is unavailable")
101
+ frontier = implementation_generation_frontier(run.execution)
102
+ if frontier is None:
103
+ raise ValueError("implementation has no dispatched generation")
104
+ executor, number, verifiers = _selected_implementation_attempts(run, frontier)
105
+ attempts = ((executor.invocation_ref, number), *((binding.invocation.invocation_ref, attempt)
106
+ for binding, attempt in verifiers))
107
+ record = None
108
+ reference = None
109
+ selected = [(executor, number), *((binding.invocation, attempt) for binding, attempt in verifiers)]
110
+ for invocation, attempt in selected:
111
+ metadata = reserved_invocation_metadata_path(project, run.manifest, invocation.invocation_ref, attempt, reader=observed)
112
+ if metadata is None:
113
+ raise ValueError("current implementation attempt has no reserved metadata")
114
+ errors = verify_agent_invocation(
115
+ metadata, project_root=project, expected_run_manifest_path=manifest_path,
116
+ expected_audience=invocation.duty_id, expected_invocation_ref=invocation.invocation_ref,
117
+ expected_role_execution_ref=invocation.role_execution_ref,
118
+ expected_participant_ref=invocation.participant_ref, reader=observed,
119
+ directory_entries=directory_entries,
120
+ )
121
+ if errors:
122
+ raise ValueError("implementation invocation: " + "; ".join(errors))
123
+ read_completed_attempt_result(project, run.execution, invocation.invocation_ref, attempt, reader=observed)
124
+ for binding, _ in verifiers:
125
+ current = VerificationGenerationReference.from_payload(binding.generation_ref)
126
+ if reference is not None and current != reference:
127
+ raise ValueError("current implementation verifiers bind different generation references")
128
+ reference = current
129
+ record = read_invocation_generation(project, manifest_path, run.manifest, current, "implementation-verifier", reader=observed)
130
+ if record is None or record["generation"] != frontier:
131
+ raise ValueError("current verification generation differs from its dispatch")
132
+ return SettledImplementationGeneration(reference, record, (), attempts, dict(fingerprints))
133
+ except (OSError, ValueError, KeyError, TypeError, PageBudgetExhausted) as exc:
134
+ return SettledImplementationGeneration(None, None, (str(exc),), attempts, dict(fingerprints))
@@ -59,7 +59,7 @@ def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
59
59
  carries = [_load_carry(task_root, stage) for stage in sorted(required_stages)]
60
60
  if any(carry is None for carry in carries):
61
61
  return ImplementationOutcome(completed=False, reason="carry sidecar missing")
62
- if any(not _carry_passed(carry) for carry in carries if carry is not None):
62
+ if any(not carry_is_pass_grade(carry) for carry in carries if carry is not None):
63
63
  return ImplementationOutcome(completed=False, reason="carry sidecar is not pass-grade")
64
64
 
65
65
  latest_stage = max(required_stages)
@@ -136,7 +136,7 @@ def _load_carry(task_root: Path, stage: int) -> dict[str, Any] | None:
136
136
  return data or None
137
137
 
138
138
 
139
- def _carry_passed(carry: dict[str, Any]) -> bool:
139
+ def carry_is_pass_grade(carry: dict[str, Any]) -> bool:
140
140
  status = str(carry.get("status") or "").lower()
141
141
  if status in FAILED_CARRY_STATUSES:
142
142
  return False
@@ -829,6 +829,7 @@ def _materialize_report_writer_packet(
829
829
  try:
830
830
  _, markdown_path = materialize_report_synthesis_packet(
831
831
  project_root=context.project_root,
832
+ manifest_path=context.request.run_manifest_path,
832
833
  manifest=context.manifest,
833
834
  active_context=context.active_context,
834
835
  team_state=context.team_state,
@@ -13,6 +13,7 @@ from .final_report_schema import SchemaError, validate as validate_schema
13
13
 
14
14
 
15
15
  OUTSIDE_WORKER_RESULT_LANES = "outside worker result lanes"
16
+ ArtifactByteReader = Callable[[Path], bytes]
16
17
 
17
18
 
18
19
  class JsonBoundaryError(ValueError):
@@ -218,6 +219,7 @@ def load_owned_object(
218
219
  validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
219
220
  max_bytes: int | None = None,
220
221
  budget: ReadBudget | None = None,
222
+ reader: ArtifactByteReader | None = None,
221
223
  ) -> dict[str, Any]:
222
224
  """Load and validate one okstra-owned JSON object."""
223
225
  return load_owned_object_snapshot(
@@ -227,6 +229,7 @@ def load_owned_object(
227
229
  validate_cross_fields=validate_cross_fields,
228
230
  max_bytes=max_bytes,
229
231
  budget=budget,
232
+ reader=reader,
230
233
  ).value
231
234
 
232
235
 
@@ -238,28 +241,45 @@ def load_owned_object_snapshot(
238
241
  validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
239
242
  max_bytes: int | None = None,
240
243
  budget: ReadBudget | None = None,
244
+ reader: ArtifactByteReader | None = None,
241
245
  ) -> OwnedJsonSnapshot:
242
- """한 번 읽은 바이트에서 객체를 파싱·검증해 함께 반환한다."""
246
+ """Read and validate one snapshot; injected readers own I/O limits."""
243
247
  if budget is not None and max_bytes is None:
244
248
  max_bytes = budget.max_bytes
245
249
  try:
246
- raw_bytes = path.read_bytes() if max_bytes is None else read_bounded_bytes(
247
- path, max_bytes=max_bytes, artifact=artifact, budget=budget,
248
- )
250
+ if reader is not None:
251
+ raw_bytes = reader(path)
252
+ elif max_bytes is None:
253
+ raw_bytes = path.read_bytes()
254
+ else:
255
+ raw_bytes = read_bounded_bytes(path, max_bytes=max_bytes, artifact=artifact, budget=budget)
256
+ except FileNotFoundError as exc:
257
+ raise JsonBoundaryError(path, artifact, "missing") from exc
258
+ except OSError as exc:
259
+ raise JsonBoundaryError(path, artifact, f"I/O error while reading ({exc})") from exc
260
+ return parse_owned_snapshot(
261
+ path, raw_bytes, artifact=artifact, schema=schema,
262
+ validate_cross_fields=validate_cross_fields,
263
+ )
264
+
265
+
266
+ def parse_owned_snapshot(
267
+ path: Path, raw_bytes: bytes, *, artifact: str,
268
+ schema: Mapping[str, Any] | None = None,
269
+ validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
270
+ ) -> OwnedJsonSnapshot:
271
+ """Validate exactly the bytes supplied by an artifact reader."""
272
+ try:
249
273
  value = json.loads(
250
274
  raw_bytes.decode("utf-8"),
251
275
  parse_constant=_reject_nonstandard_json_constant,
252
276
  )
253
- except FileNotFoundError as exc:
254
- raise JsonBoundaryError(path, artifact, "missing") from exc
255
277
  except UnicodeDecodeError as exc:
256
278
  raise JsonBoundaryError(path, artifact, "invalid JSON encoding") from exc
257
279
  except _NonstandardJsonConstant as exc:
258
280
  raise JsonBoundaryError(path, artifact, str(exc)) from exc
259
281
  except json.JSONDecodeError as exc:
260
282
  raise JsonBoundaryError(path, artifact, "invalid JSON") from exc
261
- except OSError as exc:
262
- raise JsonBoundaryError(path, artifact, f"I/O error while reading ({exc})") from exc
263
283
  return OwnedJsonSnapshot(
264
284
  value=_validate_owned(
265
285
  value,
@@ -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
 
@@ -15,7 +15,7 @@ from __future__ import annotations
15
15
 
16
16
  import os
17
17
  import re
18
- from collections.abc import Callable, Mapping, Sequence
18
+ from collections.abc import Callable, Iterable, Mapping, Sequence
19
19
  from dataclasses import dataclass, replace
20
20
  from pathlib import Path
21
21
  from typing import Any, Optional
@@ -266,20 +266,23 @@ class RunRef:
266
266
 
267
267
  def latest_verification_check_run(
268
268
  self, invocation_ref: str, attempt: int, check_ref: str,
269
+ *, directory_entries: Callable[[Path], Iterable[Path]] | None = None,
269
270
  ) -> int | None:
270
271
  runs = self.verification_check_dir(invocation_ref, attempt, check_ref)
272
+ entries = Path.iterdir if directory_entries is None else directory_entries
271
273
  numbers = [int(match.group(1)) for match in (
272
274
  _CHECK_RUN_RE.fullmatch(path.name)
273
- for path in (runs.iterdir() if runs.is_dir() else ())
275
+ for path in (entries(runs) if runs.is_dir() else ())
274
276
  ) if match]
275
277
  return max(numbers, default=None)
276
278
 
277
- def verification_check_refs(self, invocation_ref: str, attempt: int) -> list[str]:
279
+ def verification_check_refs(self, invocation_ref: str, attempt: int, *, directory_entries: Callable[[Path], Iterable[Path]] | None = None) -> list[str]:
278
280
  """The checks (`kind:id`) one attempt ran, sorted."""
279
281
  attempt_dir = self._verification_attempt_dir(invocation_ref, attempt)
282
+ entries = Path.iterdir if directory_entries is None else directory_entries
280
283
  return sorted(
281
284
  path.name.replace("-", ":", 1)
282
- for path in (attempt_dir.iterdir() if attempt_dir.is_dir() else ())
285
+ for path in (entries(attempt_dir) if attempt_dir.is_dir() else ())
283
286
  if path.is_dir() and "-" in path.name
284
287
  and _EXECUTION_SEGMENT_RE.fullmatch(path.name)
285
288
  )
@@ -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 __future__ import annotations
13
13
 
14
14
  import re
15
15
  from pathlib import Path
16
- from typing import NamedTuple
16
+ from typing import Callable, Iterable, NamedTuple
17
17
 
18
18
  from .prepare_error import PrepareError
19
19
 
@@ -36,12 +36,16 @@ def implementation_planning_report_seq(report: Path) -> int:
36
36
  return int(match.group(1))
37
37
 
38
38
 
39
- def list_implementation_planning_reports(reports_dir: Path) -> list[Path]:
39
+ def list_implementation_planning_reports(
40
+ reports_dir: Path, *,
41
+ directory_entries: Callable[[Path], Iterable[Path]] | None = None,
42
+ ) -> list[Path]:
40
43
  """Return numbered implementation-planning reports in latest-first order."""
41
44
  numbered: list[tuple[int, Path]] = []
42
- for report in reports_dir.glob(
45
+ reports = reports_dir.glob(
43
46
  "final-report-implementation-planning-*.data.json"
44
- ):
47
+ ) if directory_entries is None else directory_entries(reports_dir)
48
+ for report in reports:
45
49
  match = _FINAL_REPORT_RE.fullmatch(report.name)
46
50
  if match:
47
51
  numbered.append((int(match.group(1)), report))
@@ -7,13 +7,13 @@ import os
7
7
  import tempfile
8
8
  from functools import cache
9
9
  from pathlib import Path
10
- from typing import Any, Callable, Literal, Mapping
10
+ from typing import Any, Callable, Literal, Mapping, MutableMapping
11
11
 
12
12
  from okstra_project import project_json_path
13
13
  from okstra_project.dirs import OKSTRA_DIR_NAME, json_lock_path, registry_lock
14
14
 
15
15
  from .analysis_packet import _heading_lines
16
- from .json_boundary import load_owned_object, write_owned_object_atomic
16
+ from .json_boundary import ArtifactByteReader, load_owned_object, write_owned_object_atomic
17
17
  from .qa_commands import (
18
18
  QA_RELATIVE_PATH_DESCRIPTION, qa_relative_path_valid, validate_qa_commands,
19
19
  )
@@ -59,6 +59,37 @@ def safe_qa_path(root: Path, relative: str) -> Path:
59
59
  return path
60
60
 
61
61
 
62
+ def project_artifact_relative_path(root: Path, path: Path) -> str:
63
+ """Resolve a project-root alias without erasing links below that root."""
64
+ root = root.resolve()
65
+ candidate = path.absolute()
66
+ if candidate.is_relative_to(root):
67
+ return candidate.relative_to(root).as_posix()
68
+ for ancestor in reversed(candidate.parents):
69
+ if ancestor.resolve() == root:
70
+ return candidate.relative_to(ancestor).as_posix()
71
+ raise ValueError(f"Artifact path must remain within its project root: {path}")
72
+
73
+
74
+ def read_fingerprinted_artifact(
75
+ root: Path, path: Path, reader: ArtifactByteReader,
76
+ fingerprints: MutableMapping[str, str | None],
77
+ ) -> bytes:
78
+ relative = project_artifact_relative_path(root, path)
79
+ try:
80
+ raw = reader(root.resolve() / relative)
81
+ except (OSError, ValueError) as exc:
82
+ if relative in fingerprints and fingerprints[relative] is not None:
83
+ raise ValueError(f"Evidence input could not be read again: {relative}: {exc}") from exc
84
+ fingerprints[relative] = None
85
+ raise
86
+ digest = content_digest(raw)
87
+ if relative in fingerprints and fingerprints[relative] != digest:
88
+ raise ValueError(f"Evidence input changed while being read: {relative}")
89
+ fingerprints[relative] = digest
90
+ return raw
91
+
92
+
62
93
  def existing_qa_file(root: Path, relative: str) -> Path:
63
94
  path = safe_qa_path(root, relative)
64
95
  if not path.is_file():
@@ -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]:
@@ -2005,6 +2005,10 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
2005
2005
  )
2006
2006
  if _lead_runtime(ctx) == "claude-code":
2007
2007
  payload["claudeSessionId"] = ctx.get("CLAUDE_SESSION_ID", "")
2008
+ if "IMPLEMENTATION_COMPARISON_JSON" in ctx:
2009
+ payload["implementationComparison"] = json.loads(ctx["IMPLEMENTATION_COMPARISON_JSON"])
2010
+ elif "implementationComparison" in existing_run_manifest:
2011
+ payload["implementationComparison"] = existing_run_manifest["implementationComparison"]
2008
2012
  payload.update(execution_identity)
2009
2013
  _guard_invocation_manifest_rewrite(existing_run_manifest, payload)
2010
2014
  _write_json(Path(run_manifest_path), payload)
@@ -484,7 +484,7 @@ def _enforce_schema(data: dict) -> dict | None:
484
484
  # 구체버전 계열로 돌았는지" 가독성만 준다. CLI 가 실제 고른 버전과 다를 수
485
485
  # 있으나 표시이므로 실행에는 무해하다. 새 버전이 나오면 여기만 갱신한다.
486
486
  _DISPLAY_CONCRETE_CLAUDE = {
487
- "fable": "claude-fable-5-1",
487
+ "fable": "claude-fable-5-2",
488
488
  "opus": "claude-opus-5",
489
489
  "sonnet": "claude-sonnet-5",
490
490
  "haiku": "claude-haiku-5-5",