okstra 0.234.1 → 0.235.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 (108) 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/python-helper.d.mts +1 -1
  25. package/dist/lib/python-helper.mjs +11 -5
  26. package/dist/lib/python-helper.mjs.map +1 -1
  27. package/dist/lib/types.d.mts +1 -0
  28. package/docs/architecture/storage-model.md +50 -0
  29. package/docs/cli.md +31 -15
  30. package/docs/project-structure-overview.md +6 -1
  31. package/package.json +1 -1
  32. package/runtime/BUILD.json +2 -2
  33. package/runtime/agents/operations/trace-tests-review.json +6 -0
  34. package/runtime/prompts/duties/test-reviewer.json +32 -0
  35. package/runtime/prompts/lead/report-writer.md +13 -1
  36. package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
  37. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
  38. package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
  39. package/runtime/python/okstra_ctl/code_review_census.py +38 -0
  40. package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
  41. package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
  42. package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
  43. package/runtime/python/okstra_ctl/code_review_target.py +16 -6
  44. package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
  45. package/runtime/python/okstra_ctl/consumers.py +6 -1
  46. package/runtime/python/okstra_ctl/design_review.py +6 -26
  47. package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
  48. package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
  49. package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
  50. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  51. package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
  52. package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
  53. package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
  54. package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
  55. package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
  56. package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
  57. package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
  58. package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
  59. package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
  60. package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
  61. package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
  62. package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
  63. package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
  64. package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
  65. package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
  66. package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
  67. package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
  68. package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
  69. package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
  70. package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
  71. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
  72. package/runtime/python/okstra_ctl/json_boundary.py +28 -8
  73. package/runtime/python/okstra_ctl/paths.py +7 -4
  74. package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
  75. package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
  76. package/runtime/python/okstra_ctl/render.py +4 -0
  77. package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
  78. package/runtime/python/okstra_ctl/report_finalize.py +18 -4
  79. package/runtime/python/okstra_ctl/report_html/render.py +46 -7
  80. package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
  81. package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
  82. package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
  83. package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
  84. package/runtime/python/okstra_ctl/run.py +16 -0
  85. package/runtime/python/okstra_ctl/stage_done.py +11 -3
  86. package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
  87. package/runtime/python/okstra_ctl/stage_map.py +3 -3
  88. package/runtime/python/okstra_ctl/trace_review.py +1 -0
  89. package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
  90. package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
  91. package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
  92. package/runtime/python/okstra_ctl/verification_generation.py +3 -2
  93. package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
  94. package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
  95. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
  96. package/runtime/skills/okstra-code-review/SKILL.md +1 -1
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
  99. package/runtime/skills/okstra-run/SKILL.md +31 -0
  100. package/runtime/skills/okstra-tdd/SKILL.md +74 -13
  101. package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
  102. package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
  103. package/runtime/templates/reports/html/i18n/en.json +113 -0
  104. package/runtime/templates/reports/html/i18n/ko.json +113 -0
  105. package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
  106. package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
  107. package/runtime/templates/trace/trace.template.md +2 -0
  108. package/runtime/validators/validate-report-views.py +4 -36
@@ -6,13 +6,15 @@ from dataclasses import dataclass, replace
6
6
  from datetime import datetime, timezone
7
7
  import fcntl
8
8
  import hashlib
9
+ import io
9
10
  import json
11
+ from itertools import chain
10
12
  import os
11
13
  from pathlib import Path
12
14
  from pathlib import PurePosixPath
13
15
  import re
14
16
  import tempfile
15
- from typing import TYPE_CHECKING, Any, Iterator, Literal, Mapping, get_args
17
+ from typing import TYPE_CHECKING, Any, Callable, Iterable, Iterator, Literal, Mapping, get_args
16
18
 
17
19
  from ..domain.role import RoleCatalogError, role_for_duty
18
20
  from ..verification_invocation import (
@@ -20,6 +22,7 @@ from ..verification_invocation import (
20
22
  select_verification_generation_header_lines, verification_generation_headers,
21
23
  )
22
24
  from ..json_boundary import (
25
+ ArtifactByteReader,
23
26
  JsonBoundaryError,
24
27
  external_invocation_json_source,
25
28
  load_external_json,
@@ -49,6 +52,7 @@ AgentAudience = Literal[
49
52
  "code-reviewer",
50
53
  "schedule-verifier",
51
54
  "interface-reviewer",
55
+ "test-reviewer",
52
56
  "business-flow-investigator",
53
57
  ]
54
58
 
@@ -540,7 +544,7 @@ def _render_contract_body(
540
544
  return "\n".join(lines).rstrip("\n") + "\n"
541
545
 
542
546
 
543
- def _load_contract_payload(path: Path) -> Mapping[str, Any]:
547
+ def _load_contract_payload(path: Path, *, reader: ArtifactByteReader | None = None) -> Mapping[str, Any]:
544
548
  if not path.is_file() and path.with_suffix(".md").is_file():
545
549
  # 이 run 은 Markdown 직무를 동결했다(contractFormatVersion 1). 그 형식의
546
550
  # 파서는 제거됐으므로 여기서 멈추고 원인을 이름한다 — 없는 파일 이름만
@@ -549,7 +553,7 @@ def _load_contract_payload(path: Path) -> Mapping[str, Any]:
549
553
  f"run froze markdown duty contracts and cannot be resumed: {path.parent}"
550
554
  )
551
555
  try:
552
- payload = load_owned_object(path, artifact="agent contract")
556
+ payload = load_owned_object(path, artifact="agent contract", reader=reader)
553
557
  except JsonBoundaryError as exc:
554
558
  raise AgentInvocationError(f"invalid agent contract: {path}: {exc}") from exc
555
559
  except OSError as exc:
@@ -559,10 +563,10 @@ def _load_contract_payload(path: Path) -> Mapping[str, Any]:
559
563
  return payload
560
564
 
561
565
 
562
- def load_common_duty_contract(duty_root: Path) -> DutyContract:
566
+ def load_common_duty_contract(duty_root: Path, *, reader: ArtifactByteReader | None = None) -> DutyContract:
563
567
  """Load the common fragment, which is deliberately outside the role catalog."""
564
568
  path = duty_root / "common.json"
565
- payload = _load_contract_payload(path)
569
+ payload = _load_contract_payload(path, reader=reader)
566
570
  if payload.get("id") != "common":
567
571
  raise AgentInvocationError(f"invalid common contract id: {path}")
568
572
  return DutyContract(
@@ -600,33 +604,38 @@ def load_duty_catalog(duty_root: Path) -> dict[AgentAudience, DutyContract]:
600
604
  return catalog
601
605
 
602
606
 
603
- def load_role_duty_contract(duty_root: Path, audience: AgentAudience) -> DutyContract:
607
+ def load_role_duty_contract(duty_root: Path, audience: AgentAudience, *, reader: ArtifactByteReader | None = None) -> DutyContract:
604
608
  """현재 호출의 지침만 읽어 이후 추가된 역할을 기존 실행에 요구하지 않는다."""
605
609
  if audience not in _SUPPORTED_AUDIENCES:
606
610
  raise AgentInvocationError(f"unknown duty audience: {audience}")
607
- duty = _load_role_duty(duty_root / f"{audience}.json")
611
+ duty = _load_role_duty(duty_root / f"{audience}.json", reader=reader)
608
612
  if duty.applies_to != audience:
609
613
  raise AgentInvocationError(f"duty audience does not match requested audience: {audience}")
610
614
  return duty
611
615
 
612
616
 
613
- def digest_duty_catalog(duty_root: Path) -> str:
617
+ def digest_duty_catalog(duty_root: Path, *, reader: ArtifactByteReader | None = None,
618
+ directory_entries: Callable[[Path], Iterable[Path]] | None = None) -> str:
614
619
  """Return the canonical digest of every contract file in a snapshot.
615
620
 
616
621
  역할 계약은 하위 `roles/` 에 둔다 — `report-writer` 는 직무
617
622
  id 이면서 역할 id 라, 한 폴더에 두면 두 계약이 같은 파일 이름을 두고 겹친다.
618
623
  """
624
+ if directory_entries is None:
625
+ paths = chain(duty_root.glob("*.json"), (duty_root / "roles").glob("*.json"))
626
+ else:
627
+ paths = chain(directory_entries(duty_root), directory_entries(duty_root / "roles"))
619
628
  names = [
620
629
  path.relative_to(duty_root).as_posix()
621
- for path in (*duty_root.glob("*.json"), *(duty_root / "roles").glob("*.json"))
630
+ for path in paths if path.name.endswith(".json")
622
631
  ]
623
- return _digest_framed_files(duty_root, names)
632
+ return _digest_framed_files(duty_root, names, reader=reader)
624
633
 
625
634
 
626
- def load_role_contract(duty_root: Path, role_id: str) -> DutyContract:
635
+ def load_role_contract(duty_root: Path, role_id: str, *, reader: ArtifactByteReader | None = None) -> DutyContract:
627
636
  """이 호출의 역할 계약. 직무가 `roleId` 로 이름한 역할 하나만 읽는다."""
628
637
  path = duty_root / "roles" / f"{role_id}.json"
629
- payload = _load_contract_payload(path)
638
+ payload = _load_contract_payload(path, reader=reader)
630
639
  if payload.get("id") != role_id:
631
640
  raise AgentInvocationError(f"role contract id does not match its file: {path}")
632
641
  identity = payload.get("identity")
@@ -853,9 +862,11 @@ def verify_agent_invocation(
853
862
  expected_participant_ref: str | None = None,
854
863
  expected_role_execution_ref: str | None = None,
855
864
  expected_invocation_ref: str | None = None,
865
+ reader: ArtifactByteReader | None = None,
866
+ directory_entries: Callable[[Path], Iterable[Path]] | None = None,
856
867
  ) -> list[str]:
857
868
  """Return every deterministic violation found in a published invocation."""
858
- metadata = _read_metadata(metadata_path)
869
+ metadata = _read_metadata(metadata_path, reader=reader)
859
870
  if metadata is None or not _metadata_schema_is_exact(metadata):
860
871
  return ["agent invocation metadata schema is invalid"]
861
872
  errors = _verify_expected_identity(
@@ -868,7 +879,7 @@ def verify_agent_invocation(
868
879
  expected_role_execution_ref=expected_role_execution_ref,
869
880
  expected_invocation_ref=expected_invocation_ref,
870
881
  )
871
- errors.extend(_verify_prompt_file(metadata, project_root))
882
+ errors.extend(_verify_prompt_file(metadata, project_root, reader=reader))
872
883
  errors.extend(_verify_assignment(metadata, expected_assignment))
873
884
  errors.extend(
874
885
  _verify_contract_source(
@@ -876,6 +887,8 @@ def verify_agent_invocation(
876
887
  metadata_path=metadata_path,
877
888
  project_root=project_root,
878
889
  expected_run_manifest_path=expected_run_manifest_path,
890
+ reader=reader,
891
+ directory_entries=directory_entries,
879
892
  )
880
893
  )
881
894
  return _deduplicate(errors)
@@ -2031,23 +2044,25 @@ def _verify_expected_identity(
2031
2044
  def _verify_prompt_file(
2032
2045
  metadata: Mapping[str, object],
2033
2046
  project_root: Path,
2047
+ *, reader: ArtifactByteReader | None = None,
2034
2048
  ) -> list[str]:
2035
2049
  prompt = metadata["prompt"]
2036
2050
  digests = metadata["digests"]
2037
2051
  assert isinstance(prompt, dict)
2038
2052
  assert isinstance(digests, dict)
2053
+ resolve_path = _project_path if reader is None else _project_candidate_path
2039
2054
  try:
2040
- path = _project_path(project_root, prompt["path"], must_exist=True)
2055
+ path = resolve_path(project_root, prompt["path"], must_exist=True)
2041
2056
  except AgentInvocationError:
2042
2057
  return ["prompt path is invalid or missing"]
2043
- body = path.read_bytes()
2058
+ body = path.read_bytes() if reader is None else reader(path)
2044
2059
  if digests["promptDigest"] != _sha256(body):
2045
2060
  return ["prompt digest does not match prompt file"]
2046
2061
  errors = []
2047
2062
  errors.extend(_verify_instruction_digest(metadata, body))
2048
2063
  errors.extend(_verify_model_header(metadata, body))
2049
2064
  errors.extend(_verify_execution_delivery(metadata, path, body))
2050
- errors.extend(_verify_generation_reference(metadata, project_root, body))
2065
+ errors.extend(_verify_generation_reference(metadata, project_root, body, reader=reader))
2051
2066
  from ..code_review_invocation import review_policy_errors_for_prompt
2052
2067
 
2053
2068
  errors.extend(review_policy_errors_for_prompt(project_root, metadata, body))
@@ -2056,12 +2071,14 @@ def _verify_prompt_file(
2056
2071
 
2057
2072
  def _verify_generation_reference(
2058
2073
  metadata: Mapping[str, object], project_root: Path, prompt_bytes: bytes,
2074
+ *, reader: ArtifactByteReader | None = None,
2059
2075
  ) -> list[str]:
2060
2076
  try:
2061
2077
  reference = metadata_generation_reference(metadata)
2062
- manifest_path, manifest = _metadata_run_manifest(metadata, project_root)
2078
+ manifest_path, manifest = _metadata_run_manifest(metadata, project_root, reader=reader)
2063
2079
  _require_sealed_generation(
2064
2080
  project_root, manifest_path, manifest, reference, metadata["audience"],
2081
+ reader=reader,
2065
2082
  )
2066
2083
  return _prompt_generation_header_errors(prompt_bytes, reference)
2067
2084
  except (AgentInvocationError, OSError, ValueError) as exc:
@@ -2081,6 +2098,7 @@ def metadata_generation_reference(
2081
2098
  def reserved_generation_reference(
2082
2099
  project_root: Path, manifest: Mapping[str, object], invocation_ref: str,
2083
2100
  attempt: int,
2101
+ *, reader: ArtifactByteReader | None = None,
2084
2102
  ) -> VerificationGenerationReference | None:
2085
2103
  """The generation the metadata of one reserved v2 attempt is bound to; None
2086
2104
  when the run reserved no such attempt or bound it to no generation.
@@ -2088,28 +2106,30 @@ def reserved_generation_reference(
2088
2106
  The reservation names the metadata, so a reader does not take a generation
2089
2107
  file on the strength of the path its dispatch kind computes.
2090
2108
  """
2091
- metadata_path = reserved_invocation_metadata_path(project_root, manifest, invocation_ref, attempt)
2109
+ metadata_path = reserved_invocation_metadata_path(project_root, manifest, invocation_ref, attempt, reader=reader)
2092
2110
  if metadata_path is None:
2093
2111
  return None
2094
- metadata = _load_json_object(metadata_path, "agent invocation metadata")
2112
+ metadata = _load_json_object(metadata_path, "agent invocation metadata", reader=reader)
2095
2113
  return metadata_generation_reference(metadata)
2096
2114
 
2097
2115
 
2098
2116
  def reserved_invocation_metadata_path(
2099
2117
  project_root: Path, manifest: Mapping[str, object], invocation_ref: str, attempt: int,
2118
+ *, reader: ArtifactByteReader | None = None,
2100
2119
  ) -> Path | None:
2101
2120
  contract = manifest.get("agentContract")
2102
2121
  if not isinstance(contract, Mapping):
2103
2122
  return None
2104
- root = _project_path(
2123
+ resolve_path = _project_path if reader is None else _project_candidate_path
2124
+ root = resolve_path(
2105
2125
  project_root, contract.get("invocationReservationRootPath"), must_exist=False,
2106
2126
  )
2107
2127
  path = _reservation_path(root, _attempt_invocation_id(invocation_ref, attempt))
2108
2128
  if not path.is_file():
2109
2129
  return None
2110
- reservation = _load_json_object(path, "invocation reservation")
2111
- metadata_path = _project_path(project_root, reservation.get("metadataPath"), must_exist=True)
2112
- metadata = _load_json_object(metadata_path, "agent invocation metadata")
2130
+ reservation = _load_json_object(path, "invocation reservation", reader=reader)
2131
+ metadata_path = resolve_path(project_root, reservation.get("metadataPath"), must_exist=True)
2132
+ metadata = _load_json_object(metadata_path, "agent invocation metadata", reader=reader)
2113
2133
  for payload in (reservation, metadata):
2114
2134
  if (payload.get("invocationRef"), payload.get("attempt")) != (
2115
2135
  invocation_ref, attempt):
@@ -2132,12 +2152,14 @@ def _reservation_path(root: Path, invocation_id: str) -> Path:
2132
2152
 
2133
2153
  def _metadata_run_manifest(
2134
2154
  metadata: Mapping[str, object], project_root: Path,
2155
+ *, reader: ArtifactByteReader | None = None,
2135
2156
  ) -> tuple[Path | None, dict[str, object]]:
2136
2157
  value = metadata["contractSource"].get("runManifestPath")
2137
2158
  if not value:
2138
2159
  return None, {}
2139
- manifest_path = _project_path(project_root, value, must_exist=True)
2140
- return manifest_path, _load_json_object(manifest_path, "run manifest")
2160
+ resolve_path = _project_path if reader is None else _project_candidate_path
2161
+ manifest_path = resolve_path(project_root, value, must_exist=True)
2162
+ return manifest_path, _load_json_object(manifest_path, "run manifest", reader=reader)
2141
2163
 
2142
2164
 
2143
2165
  def _prompt_generation_header_errors(
@@ -2154,9 +2176,11 @@ def _prompt_generation_header_errors(
2154
2176
  def _require_sealed_generation(
2155
2177
  project_root: Path, manifest_path: Path | None, manifest: Mapping[str, object],
2156
2178
  reference: VerificationGenerationReference | None, audience: str,
2179
+ *, reader: ArtifactByteReader | None = None,
2157
2180
  ) -> None:
2158
2181
  read_invocation_generation(
2159
2182
  project_root, manifest_path, manifest, reference, audience,
2183
+ **({"reader": reader} if reader is not None else {}),
2160
2184
  )
2161
2185
 
2162
2186
 
@@ -2316,6 +2340,8 @@ def _verify_contract_source(
2316
2340
  metadata_path: Path,
2317
2341
  project_root: Path,
2318
2342
  expected_run_manifest_path: Path | None,
2343
+ reader: ArtifactByteReader | None = None,
2344
+ directory_entries: Callable[[Path], Iterable[Path]] | None = None,
2319
2345
  ) -> list[str]:
2320
2346
  source = metadata["contractSource"]
2321
2347
  assert isinstance(source, dict)
@@ -2324,7 +2350,7 @@ def _verify_contract_source(
2324
2350
  if expected_run_manifest_path is not None:
2325
2351
  return ["standalone invocation cannot use a run manifest"]
2326
2352
  errors = _verify_metadata_adjacency(metadata, metadata_path, project_root)
2327
- errors.extend(_verify_duty_snapshot(metadata, project_root, None))
2353
+ errors.extend(_verify_duty_snapshot(metadata, project_root, None, reader=reader, directory_entries=directory_entries))
2328
2354
  return errors
2329
2355
  if mode != "run":
2330
2356
  return ["contract source mode is invalid"]
@@ -2336,6 +2362,7 @@ def _verify_contract_source(
2336
2362
  metadata,
2337
2363
  project_root=project_root,
2338
2364
  expected_run_manifest_path=expected_run_manifest_path,
2365
+ reader=reader, directory_entries=directory_entries,
2339
2366
  )
2340
2367
  )
2341
2368
  return errors
@@ -2363,27 +2390,31 @@ def _verify_run_contract(
2363
2390
  *,
2364
2391
  project_root: Path,
2365
2392
  expected_run_manifest_path: Path,
2393
+ reader: ArtifactByteReader | None = None,
2394
+ directory_entries: Callable[[Path], Iterable[Path]] | None = None,
2366
2395
  ) -> list[str]:
2367
2396
  source = metadata["contractSource"]
2368
2397
  assert isinstance(source, dict)
2398
+ resolve_path = _project_path if reader is None else _project_candidate_path
2369
2399
  try:
2370
- recorded = _project_path(
2400
+ recorded = resolve_path(
2371
2401
  project_root,
2372
2402
  source["runManifestPath"],
2373
2403
  must_exist=True,
2374
2404
  )
2375
- expected = expected_run_manifest_path.resolve(strict=True)
2405
+ expected = expected_run_manifest_path.absolute() if reader is not None else expected_run_manifest_path.resolve(strict=True)
2406
+ same_manifest = recorded.resolve(strict=True) == expected.resolve(strict=True)
2376
2407
  except (AgentInvocationError, OSError):
2377
2408
  return ["run manifest path is invalid"]
2378
- if recorded != expected:
2409
+ if not same_manifest:
2379
2410
  return ["run manifest path does not match expected run manifest"]
2380
2411
  try:
2381
- manifest = _load_json_object(expected, "run manifest")
2412
+ manifest = _load_json_object(expected, "run manifest", reader=reader)
2382
2413
  except AgentInvocationError:
2383
2414
  return ["run manifest is invalid"]
2384
2415
  errors = _verify_run_manifest_contract(metadata, manifest, project_root)
2385
- errors.extend(_verify_duty_snapshot(metadata, project_root, manifest))
2386
- errors.extend(_verify_reservation(metadata, manifest, project_root))
2416
+ errors.extend(_verify_duty_snapshot(metadata, project_root, manifest, reader=reader, directory_entries=directory_entries))
2417
+ errors.extend(_verify_reservation(metadata, manifest, project_root, reader=reader))
2387
2418
  return errors
2388
2419
 
2389
2420
 
@@ -2458,6 +2489,8 @@ def _verify_duty_snapshot(
2458
2489
  metadata: Mapping[str, object],
2459
2490
  project_root: Path,
2460
2491
  manifest: Mapping[str, object] | None,
2492
+ *, reader: ArtifactByteReader | None = None,
2493
+ directory_entries: Callable[[Path], Iterable[Path]] | None = None,
2461
2494
  ) -> list[str]:
2462
2495
  source = metadata["contractSource"]
2463
2496
  duty_contract = metadata["dutyContract"]
@@ -2465,14 +2498,16 @@ def _verify_duty_snapshot(
2465
2498
  assert isinstance(source, dict)
2466
2499
  assert isinstance(duty_contract, dict)
2467
2500
  assert isinstance(digests, dict)
2501
+ resolve_path = _project_path if reader is None else _project_candidate_path
2468
2502
  try:
2469
- root = _project_path(project_root, source["dutyRootPath"], must_exist=True)
2470
- common = load_common_duty_contract(root)
2471
- duty = load_role_duty_contract(root, duty_contract["id"])
2503
+ root = resolve_path(project_root, source["dutyRootPath"], must_exist=True)
2504
+ common = load_common_duty_contract(root, **({"reader": reader} if reader is not None else {}))
2505
+ duty = load_role_duty_contract(root, duty_contract["id"], **({"reader": reader} if reader is not None else {}))
2472
2506
  except (AgentInvocationError, KeyError):
2473
2507
  return ["duty snapshot is invalid"]
2474
2508
  errors = _verify_duty_metadata(duty_contract, duty)
2475
- actual_catalog = digest_duty_catalog(root)
2509
+ actual_catalog = digest_duty_catalog(root, **({"reader": reader} if reader is not None else {}),
2510
+ **({"directory_entries": directory_entries} if directory_entries is not None else {}))
2476
2511
  expected_catalog = (
2477
2512
  manifest["agentContract"]["catalogDigest"]
2478
2513
  if manifest is not None
@@ -2482,12 +2517,12 @@ def _verify_duty_snapshot(
2482
2517
  errors.append("catalog digest does not match run duty snapshot")
2483
2518
  return errors
2484
2519
  actual_duty = _digest_framed_files(
2485
- root, ["common.json", f"roles/{duty.role_id}.json", duty.source_path.name]
2520
+ root, ["common.json", f"roles/{duty.role_id}.json", duty.source_path.name], reader=reader,
2486
2521
  )
2487
2522
  if digests["dutyDigest"] != actual_duty:
2488
2523
  errors.append("duty digest does not match run duty snapshot")
2489
2524
  return errors
2490
- errors.extend(_verify_prompt_duty_body(metadata, project_root, common, duty))
2525
+ errors.extend(_verify_prompt_duty_body(metadata, project_root, common, duty, reader=reader))
2491
2526
  return errors
2492
2527
 
2493
2528
 
@@ -2505,23 +2540,29 @@ def _verify_prompt_duty_body(
2505
2540
  project_root: Path,
2506
2541
  common: DutyContract,
2507
2542
  duty: DutyContract,
2543
+ *, reader: ArtifactByteReader | None = None,
2508
2544
  ) -> list[str]:
2509
2545
  prompt_spec = metadata["prompt"]
2510
2546
  assert isinstance(prompt_spec, dict)
2547
+ resolve_path = _project_path if reader is None else _project_candidate_path
2511
2548
  try:
2512
- prompt_path = _project_path(project_root, prompt_spec["path"], must_exist=True)
2513
- prompt = prompt_path.read_text(encoding="utf-8")
2549
+ prompt_path = resolve_path(project_root, prompt_spec["path"], must_exist=True)
2550
+ if reader is None:
2551
+ prompt = prompt_path.read_text(encoding="utf-8")
2552
+ else:
2553
+ with io.TextIOWrapper(io.BytesIO(reader(prompt_path)), encoding="utf-8") as handle:
2554
+ prompt = handle.read()
2514
2555
  _prefix, remainder = prompt.split("\n\n## Duty Contract\n\n", 1)
2515
2556
  rendered_duty, _task = remainder.split("\n\n## Task Instructions\n\n", 1)
2516
2557
  except (AgentInvocationError, OSError, UnicodeDecodeError, ValueError):
2517
2558
  return ["prompt duty contract does not match duty snapshot"]
2518
2559
  role_contract = load_role_contract(
2519
- _project_path(
2560
+ resolve_path(
2520
2561
  project_root,
2521
2562
  str(metadata["contractSource"]["dutyRootPath"]),
2522
2563
  must_exist=True,
2523
2564
  ),
2524
- duty.role_id,
2565
+ duty.role_id, **({"reader": reader} if reader is not None else {}),
2525
2566
  )
2526
2567
  expected = "\n\n".join(
2527
2568
  part.rstrip() for part in (common.body, role_contract.body, duty.body)
@@ -2535,18 +2576,20 @@ def _verify_reservation(
2535
2576
  metadata: Mapping[str, object],
2536
2577
  manifest: Mapping[str, object],
2537
2578
  project_root: Path,
2579
+ *, reader: ArtifactByteReader | None = None,
2538
2580
  ) -> list[str]:
2539
2581
  contract = manifest.get("agentContract")
2540
2582
  if not isinstance(contract, dict):
2541
2583
  return ["run manifest agent contract is missing"]
2584
+ resolve_path = _project_path if reader is None else _project_candidate_path
2542
2585
  try:
2543
- root = _project_path(
2586
+ root = resolve_path(
2544
2587
  project_root,
2545
2588
  contract["invocationReservationRootPath"],
2546
2589
  must_exist=True,
2547
2590
  )
2548
2591
  path = _reservation_path(root, metadata["invocationId"])
2549
- actual = _load_json_object(path, "invocation reservation")
2592
+ actual = _load_json_object(path, "invocation reservation", reader=reader)
2550
2593
  except (AgentInvocationError, KeyError):
2551
2594
  return ["invocation reservation is missing or invalid"]
2552
2595
  prompt = metadata["prompt"]
@@ -2705,6 +2748,15 @@ def _project_path(
2705
2748
  value: object,
2706
2749
  *,
2707
2750
  must_exist: bool,
2751
+ ) -> Path:
2752
+ return _project_candidate_path(project_root, value, must_exist=must_exist).resolve(strict=must_exist)
2753
+
2754
+
2755
+ def _project_candidate_path(
2756
+ project_root: Path,
2757
+ value: object,
2758
+ *,
2759
+ must_exist: bool,
2708
2760
  ) -> Path:
2709
2761
  if not isinstance(value, str) or not value:
2710
2762
  raise AgentInvocationError("project-relative path is invalid")
@@ -2713,7 +2765,7 @@ def _project_path(
2713
2765
  raise AgentInvocationError("project-relative path is invalid")
2714
2766
  candidate = project_root.joinpath(*pure.parts)
2715
2767
  _project_relative(candidate, project_root, must_exist=must_exist)
2716
- return candidate.resolve(strict=must_exist)
2768
+ return candidate.absolute()
2717
2769
 
2718
2770
 
2719
2771
  def _is_relative_to(path: Path, root: Path) -> bool:
@@ -2724,11 +2776,12 @@ def _is_relative_to(path: Path, root: Path) -> bool:
2724
2776
  return True
2725
2777
 
2726
2778
 
2727
- def _digest_framed_files(root: Path, relative_names: list[str]) -> str:
2779
+ def _digest_framed_files(root: Path, relative_names: list[str], *, reader: ArtifactByteReader | None = None) -> str:
2728
2780
  framed = bytearray(b"okstra-digest-v1\0")
2729
2781
  for name in sorted(relative_names):
2730
2782
  name_bytes = name.encode("utf-8")
2731
- body = (root / name).read_bytes()
2783
+ path = root / name
2784
+ body = path.read_bytes() if reader is None else reader(path)
2732
2785
  framed.extend(len(name_bytes).to_bytes(8, "big"))
2733
2786
  framed.extend(name_bytes)
2734
2787
  framed.extend(len(body).to_bytes(8, "big"))
@@ -2756,31 +2809,31 @@ def _pretty_json(value: object) -> bytes:
2756
2809
  ).encode("utf-8")
2757
2810
 
2758
2811
 
2759
- def _load_json_object(path: Path, label: str) -> dict[str, object]:
2760
- value = _read_json_if_object(path)
2812
+ def _load_json_object(path: Path, label: str, *, reader: ArtifactByteReader | None = None) -> dict[str, object]:
2813
+ value = _read_json_if_object(path, reader=reader)
2761
2814
  if value is None:
2762
2815
  raise AgentInvocationError(f"{label} is missing or invalid: {path}")
2763
2816
  return value
2764
2817
 
2765
2818
 
2766
- def _read_json_if_object(path: Path) -> dict[str, object] | None:
2819
+ def _read_json_if_object(path: Path, *, reader: ArtifactByteReader | None = None) -> dict[str, object] | None:
2767
2820
  try:
2768
- value = load_owned_object(path, artifact="agent invocation metadata")
2821
+ value = load_owned_object(path, artifact="agent invocation metadata", reader=reader)
2769
2822
  except JsonBoundaryError:
2770
2823
  return None
2771
2824
  return value if isinstance(value, dict) else None
2772
2825
 
2773
2826
 
2774
- def _read_metadata(path: Path) -> dict[str, object] | None:
2775
- return _read_json_if_object(path)
2827
+ def _read_metadata(path: Path, *, reader: ArtifactByteReader | None = None) -> dict[str, object] | None:
2828
+ return _read_json_if_object(path, reader=reader)
2776
2829
 
2777
2830
 
2778
2831
  def _deduplicate(errors: list[str]) -> list[str]:
2779
2832
  return list(dict.fromkeys(errors))
2780
2833
 
2781
2834
 
2782
- def _load_role_duty(path: Path) -> DutyContract:
2783
- payload = _load_contract_payload(path)
2835
+ def _load_role_duty(path: Path, *, reader: ArtifactByteReader | None = None) -> DutyContract:
2836
+ payload = _load_contract_payload(path, reader=reader)
2784
2837
  audience = payload.get("id")
2785
2838
  if not isinstance(audience, str) or audience not in _SUPPORTED_AUDIENCES:
2786
2839
  raise AgentInvocationError(f"unknown duty audience: {audience}")
@@ -9,6 +9,7 @@
9
9
  from __future__ import annotations
10
10
 
11
11
  import argparse
12
+ import json
12
13
  import os
13
14
  from pathlib import Path
14
15
  import shlex
@@ -359,6 +360,7 @@ def _materialize_run(
359
360
  project_root,
360
361
  manifest,
361
362
  active_context,
363
+ manifest_path=manifest_path,
362
364
  narrative_path=result_path,
363
365
  ),
364
366
  )
@@ -374,6 +376,7 @@ def _materialize_run(
374
376
  active_context,
375
377
  body,
376
378
  narrative_path=result_path,
379
+ manifest_path=manifest_path,
377
380
  )
378
381
  elif getattr(args, "corrections", None):
379
382
  if args.audience != "report-writer":
@@ -565,6 +568,7 @@ def _with_report_writer_sections(
565
568
  body: str,
566
569
  *,
567
570
  narrative_path: Path,
571
+ manifest_path: Path | None = None,
568
572
  ) -> str:
569
573
  """run 갈래 report-writer 프롬프트의 okstra 소유 절을 본문 끝에 렌더한다.
570
574
 
@@ -614,6 +618,17 @@ def _with_report_writer_sections(
614
618
  body = "## Inputs\n\nCorrection-only task: use the checked field values and evidence below."
615
619
  sections.extend(_render_correction_application(args, project_root, narrative_path, corrections_path, check))
616
620
  sections.append("")
621
+ if manifest_path is not None:
622
+ from ...implementation_comparison.run_integration import read_run_comparison
623
+ from ...report_synthesis_packet import comparison_authoring_instructions
624
+
625
+ comparison = read_run_comparison(project_root, manifest_path)
626
+ if comparison is not None:
627
+ sections.extend([
628
+ "## Implementation Comparison", "",
629
+ *comparison_authoring_instructions(comparison),
630
+ "```json", json.dumps(comparison, ensure_ascii=False, indent=2), "```", "",
631
+ ])
617
632
  else:
618
633
  _refuse_free_form_correction(project_root, narrative_path, manifest)
619
634
  preserved = _preserve_reauthored_narrative(
@@ -872,6 +887,7 @@ def _report_writer_input_lines(
872
887
  active_context: Mapping[str, Any],
873
888
  *,
874
889
  narrative_path: Path,
890
+ manifest_path: Path | None = None,
875
891
  ) -> list[str]:
876
892
  """report-writer 의 `## Inputs` 줄. 로스터 경로(`worker_prompt_body`)와 같은 규칙.
877
893
 
@@ -887,6 +903,7 @@ def _report_writer_input_lines(
887
903
  try:
888
904
  _, markdown_path = materialize_report_synthesis_packet(
889
905
  project_root=project_root,
906
+ manifest_path=manifest_path,
890
907
  manifest=manifest,
891
908
  active_context=active_context,
892
909
  team_state=team_state,
@@ -17,6 +17,7 @@ from .execution_identity import (
17
17
  from .execution_manifest import read_execution_manifest
18
18
  from .execution_manifest import _replace_manifest, _write_manifest_over_existing
19
19
  from .jsonl import append_jsonl
20
+ from .json_boundary import ArtifactByteReader
20
21
  from .run_context import task_mutex
21
22
 
22
23
 
@@ -164,11 +165,13 @@ def _stream_payload(path: Path) -> dict[str, Any]:
164
165
  }
165
166
 
166
167
 
167
- def read_sealed_artifact(seal: AttemptEvidenceSeal, path: Path) -> bytes:
168
+ def read_sealed_artifact(
169
+ seal: AttemptEvidenceSeal, path: Path, *, reader: ArtifactByteReader | None = None,
170
+ ) -> bytes:
168
171
  row = next((row for row in seal.artifacts if row.get("normalizedPath") == str(path)), None)
169
172
  if row is None or path.is_symlink() or not path.is_file():
170
173
  raise AttemptEvidenceError(f"artifact is absent from the attempt seal: {path}")
171
- data = path.read_bytes()
174
+ data = path.read_bytes() if reader is None else reader(path)
172
175
  if len(data) != row.get("byteLength") or _sha(data) != row.get("sha256"):
173
176
  raise AttemptEvidenceError(f"sealed artifact bytes changed: {path}")
174
177
  return data
@@ -9,6 +9,7 @@ from dataclasses import dataclass
9
9
  from pathlib import Path, PurePosixPath
10
10
  from collections.abc import Mapping, Sequence
11
11
 
12
+ from .json_boundary import load_owned_object, write_owned_object_atomic
12
13
  from .review_verdicts import _table_fields, parse_review_census, read_review_census
13
14
 
14
15
  _GROUPS = ("structural", "semantic", "state-and-tests", "general")
@@ -114,6 +115,43 @@ def render_rule_catalog(text: str, parent: Path, *, include_architecture: bool =
114
115
  return "\n".join(rows)
115
116
 
116
117
 
118
+ def load_or_create_function_inventory(
119
+ path: Path, base: str, head: str, unresolved: tuple[str, ...],
120
+ ) -> dict[str, object]:
121
+ """The lead's function spans for the files whose boundaries the census cannot read.
122
+
123
+ A missing file is written as a template naming those files, and the call fails
124
+ until the lead fills it.
125
+ """
126
+ if not path.exists():
127
+ write_owned_object_atomic(path, {"base": base, "head": head,
128
+ "files": {name: None for name in unresolved}},
129
+ artifact="function inventory")
130
+ raise ValueError(f"complete the function inventory before dispatch: {path}")
131
+ payload = load_owned_object(path, artifact="function inventory")
132
+ if (set(payload) != {"base", "head", "files"} or payload["base"] != base
133
+ or payload["head"] != head or not isinstance(payload["files"], dict)
134
+ or set(payload["files"]) != set(unresolved)):
135
+ raise ValueError(f"function inventory must match this base, head and unresolved files: {path}")
136
+ return payload["files"]
137
+
138
+
139
+ def build_review_census_with_inventory(
140
+ repo: Path, base: str, head: str, rules_source: Path, changed: dict[str, set[int]],
141
+ inventory_path: Path | None, **inputs: object,
142
+ ) -> tuple[CensusResult, dict[str, object]]:
143
+ """The census, rebuilt with the lead's function inventory when boundaries are unresolved.
144
+
145
+ Returns the census and the inventory it used (empty when none was needed).
146
+ """
147
+ result = build_review_census(repo, base, head, rules_source, changed, **inputs)
148
+ if not result.unresolved or inventory_path is None:
149
+ return result, {}
150
+ inventory = load_or_create_function_inventory(inventory_path, base, head, result.unresolved)
151
+ return build_review_census(repo, base, head, rules_source, changed, inventory=inventory,
152
+ **inputs), inventory
153
+
154
+
117
155
  def _supplement_functions(
118
156
  repo: Path, head: str, path: str, lines: set[int], entry: object,
119
157
  ) -> list[str]: