okstra 0.231.1 → 0.232.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 (126) hide show
  1. package/README.md +12 -0
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/memory/memory.mjs +9 -55
  5. package/dist/commands/memory/memory.mjs.map +1 -1
  6. package/dist/lib/memory-auto-register.d.mts +1 -0
  7. package/dist/lib/memory-auto-register.mjs +113 -0
  8. package/dist/lib/memory-auto-register.mjs.map +1 -0
  9. package/dist/lib/memory-entry-contract.d.mts +12 -0
  10. package/dist/lib/memory-entry-contract.mjs +46 -0
  11. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  12. package/dist/lib/python-helper.d.mts +1 -1
  13. package/dist/lib/python-helper.mjs +3 -2
  14. package/dist/lib/python-helper.mjs.map +1 -1
  15. package/dist/lib/record-secrets.d.mts +1 -0
  16. package/dist/lib/record-secrets.mjs +28 -0
  17. package/dist/lib/record-secrets.mjs.map +1 -0
  18. package/dist/lib/types.d.mts +2 -1
  19. package/docs/architecture/storage-model.md +127 -0
  20. package/docs/architecture.md +7 -0
  21. package/docs/cli.md +234 -0
  22. package/docs/project-structure-overview.md +2 -1
  23. package/package.json +1 -1
  24. package/runtime/BUILD.json +2 -2
  25. package/runtime/agents/common.json +8 -8
  26. package/runtime/agents/roles/verifier.json +2 -4
  27. package/runtime/bin/okstra-provider-exec.py +10 -4
  28. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  29. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  30. package/runtime/prompts/coding-preflight/clean-code.md +85 -281
  31. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  32. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  33. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  34. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  35. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  36. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  37. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  38. package/runtime/prompts/coding-preflight/overview.md +25 -38
  39. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  40. package/runtime/prompts/duties/code-reviewer.json +15 -18
  41. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  42. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  43. package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
  44. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
  45. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
  46. package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
  47. package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
  48. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  49. package/runtime/python/okstra_ctl/code_review_census.py +71 -7
  50. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  51. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  52. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  53. package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
  54. package/runtime/python/okstra_ctl/code_review_target.py +85 -11
  55. package/runtime/python/okstra_ctl/consumers.py +12 -9
  56. package/runtime/python/okstra_ctl/design_review.py +207 -0
  57. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  58. package/runtime/python/okstra_ctl/doctor.py +8 -25
  59. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  60. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  61. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  62. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  63. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  64. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  65. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  66. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  67. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  68. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  69. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  70. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
  71. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  72. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  73. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  74. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  75. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  76. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  77. package/runtime/python/okstra_ctl/json_boundary.py +21 -2
  78. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  79. package/runtime/python/okstra_ctl/manager_cli.py +26 -0
  80. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  81. package/runtime/python/okstra_ctl/manager_sync.py +3 -22
  82. package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
  83. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  84. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  85. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
  86. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
  87. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
  88. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
  89. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  90. package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
  91. package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
  92. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
  93. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  94. package/runtime/python/okstra_ctl/report_assembly.py +15 -0
  95. package/runtime/python/okstra_ctl/report_narrative.py +3 -0
  96. package/runtime/python/okstra_ctl/report_synthesis_packet.py +11 -2
  97. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  98. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  99. package/runtime/python/okstra_ctl/run.py +24 -1
  100. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  101. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  102. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  103. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  104. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  105. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  106. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  107. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  108. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  109. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  110. package/runtime/python/okstra_project/__init__.py +2 -0
  111. package/runtime/python/okstra_project/dirs.py +18 -0
  112. package/runtime/python/okstra_project/state.py +25 -20
  113. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  114. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  115. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  116. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  117. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  118. package/runtime/schemas/record-secret-patterns.json +41 -0
  119. package/runtime/skills/okstra-code-review/SKILL.md +71 -123
  120. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  121. package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
  122. package/runtime/skills/okstra-manager/SKILL.md +7 -0
  123. package/runtime/skills/okstra-memory/SKILL.md +7 -0
  124. package/runtime/templates/implementation-worker-preamble.md +4 -9
  125. package/runtime/templates/worker-prompt-preamble.md +4 -12
  126. package/runtime/validators/validate-run.py +14 -2
@@ -12,7 +12,7 @@ from pathlib import Path
12
12
  from pathlib import PurePosixPath
13
13
  import re
14
14
  import tempfile
15
- from typing import Any, Iterator, Literal, Mapping, get_args
15
+ from typing import TYPE_CHECKING, Any, Iterator, Literal, Mapping, get_args
16
16
 
17
17
  from ..domain.role import RoleCatalogError, role_for_duty
18
18
  from ..verification_invocation import (
@@ -26,6 +26,9 @@ from ..json_boundary import (
26
26
  load_owned_object,
27
27
  )
28
28
 
29
+ if TYPE_CHECKING:
30
+ from ..code_review_invocation import CodeReviewInputs
31
+
29
32
 
30
33
  AgentAudience = Literal[
31
34
  "lead",
@@ -190,6 +193,7 @@ class AgentInvocationRequest:
190
193
  # dispatch has used it. See `_publish_or_reuse`.
191
194
  replace_undispatched: bool = False
192
195
  verification_generation: VerificationGenerationReference | None = None
196
+ review_inputs: CodeReviewInputs | None = None
193
197
 
194
198
 
195
199
  @dataclass(frozen=True)
@@ -648,6 +652,9 @@ def prepare_agent_invocation(
648
652
  """Materialize one immutable prompt and its adjacent completion metadata."""
649
653
  request = _bind_generation_request(request)
650
654
  _validate_request(request)
655
+ from ..code_review_invocation import bind_review_invocation
656
+
657
+ request = bind_review_invocation(request)
651
658
  materialized = _materialize(request)
652
659
  if materialized.reservation_root is None:
653
660
  with _exclusive_lock(_prompt_lock_path(request.prompt_path)):
@@ -944,8 +951,9 @@ def publish_standalone_completion(
944
951
  invocation_id=invocation_id,
945
952
  metadata_path=canonical_metadata,
946
953
  )
954
+ review_audit = _complete_standalone_review_audit(project_root, canonical_metadata)
947
955
  completion = {
948
- "schemaVersion": 1,
956
+ "schemaVersion": 2 if review_audit is not None else 1,
949
957
  "purpose": purpose,
950
958
  "invocationId": invocation_id,
951
959
  "status": "completed",
@@ -962,10 +970,34 @@ def publish_standalone_completion(
962
970
  "resultEnvelopeDigest": _sha256(envelope_bytes),
963
971
  "completedAt": completed,
964
972
  }
973
+ if review_audit is not None:
974
+ completion["reviewAuditDigest"] = review_audit
965
975
  _publish_exclusive(completion_path, _canonical_json(completion))
966
976
  return completion_path
967
977
 
968
978
 
979
+ def _complete_standalone_review_audit(project_root: Path, metadata_path: Path) -> str | None:
980
+ from ..code_review_invocation import complete_review_audit
981
+
982
+ try:
983
+ return complete_review_audit(
984
+ project_root, metadata_path,
985
+ _load_json_object(metadata_path, "agent invocation metadata"),
986
+ )
987
+ except (OSError, ValueError, KeyError) as exc:
988
+ raise AgentInvocationError(f"standalone review integrity failed: {exc}") from exc
989
+
990
+
991
+ @dataclass(frozen=True)
992
+ class _StandaloneCompletion:
993
+ payload: Mapping[str, Any]
994
+ invocation_id: str
995
+ root: Path
996
+ metadata_path: Path
997
+ result_path: Path
998
+ completion_path: Path
999
+
1000
+
969
1001
  def verify_standalone_completion(
970
1002
  completion_path: Path,
971
1003
  *,
@@ -973,6 +1005,49 @@ def verify_standalone_completion(
973
1005
  expected_purpose: str,
974
1006
  ) -> VerifiedStandaloneResult:
975
1007
  """Verify a completion marker and return its already-read immutable body."""
1008
+ context = _read_standalone_completion(completion_path, project_root, expected_purpose)
1009
+ with _exclusive_lock(context.root / f"{context.invocation_id}.result.publish.lock"):
1010
+ authority_id, _authority_root, canonical_metadata = _standalone_authority(
1011
+ project_root=project_root,
1012
+ purpose=expected_purpose,
1013
+ metadata_path=context.metadata_path,
1014
+ )
1015
+ if authority_id != context.invocation_id:
1016
+ raise AgentInvocationError("standalone completion identity does not match")
1017
+ envelope_bytes, returned_body = _verified_result_envelope(
1018
+ context.result_path,
1019
+ project_root=project_root,
1020
+ purpose=expected_purpose,
1021
+ invocation_id=context.invocation_id,
1022
+ metadata_path=canonical_metadata,
1023
+ )
1024
+ digest = _sha256(envelope_bytes)
1025
+ if context.payload.get("resultEnvelopeDigest") != digest:
1026
+ raise AgentInvocationError("result envelope digest does not match completion")
1027
+ from ..code_review_invocation import verify_review_completion
1028
+
1029
+ try:
1030
+ verify_review_completion(
1031
+ project_root, canonical_metadata,
1032
+ _load_json_object(canonical_metadata, "agent invocation metadata"),
1033
+ context.payload,
1034
+ )
1035
+ except (OSError, ValueError, KeyError) as exc:
1036
+ raise AgentInvocationError(f"standalone review integrity is invalid: {exc}") from exc
1037
+ return VerifiedStandaloneResult(
1038
+ purpose=expected_purpose,
1039
+ invocation_id=context.invocation_id,
1040
+ prompt_metadata_path=context.metadata_path,
1041
+ result_path=context.result_path,
1042
+ completion_path=context.completion_path,
1043
+ result_envelope_digest=digest,
1044
+ returned_body=returned_body,
1045
+ )
1046
+
1047
+
1048
+ def _read_standalone_completion(
1049
+ completion_path: Path, project_root: Path, expected_purpose: str,
1050
+ ) -> _StandaloneCompletion:
976
1051
  _validate_slug(expected_purpose, "standalone purpose")
977
1052
  completion = _load_json_object(completion_path, "standalone completion")
978
1053
  expected_keys = {
@@ -985,7 +1060,9 @@ def verify_standalone_completion(
985
1060
  "resultEnvelopeDigest",
986
1061
  "completedAt",
987
1062
  }
988
- if set(completion) != expected_keys or completion.get("schemaVersion") != 1:
1063
+ if completion.get("schemaVersion") == 2:
1064
+ expected_keys.add("reviewAuditDigest")
1065
+ if set(completion) != expected_keys or completion.get("schemaVersion") not in (1, 2):
989
1066
  raise AgentInvocationError("standalone completion schema is invalid")
990
1067
  if completion.get("purpose") != expected_purpose:
991
1068
  raise AgentInvocationError("standalone completion purpose does not match")
@@ -1013,32 +1090,8 @@ def verify_standalone_completion(
1013
1090
  must_exist=True,
1014
1091
  ):
1015
1092
  raise AgentInvocationError("standalone completion result path does not match")
1016
- with _exclusive_lock(root / f"{invocation_id}.result.publish.lock"):
1017
- authority_id, _authority_root, canonical_metadata = _standalone_authority(
1018
- project_root=project_root,
1019
- purpose=expected_purpose,
1020
- metadata_path=metadata_path,
1021
- )
1022
- if authority_id != invocation_id:
1023
- raise AgentInvocationError("standalone completion identity does not match")
1024
- envelope_bytes, returned_body = _verified_result_envelope(
1025
- result_path,
1026
- project_root=project_root,
1027
- purpose=expected_purpose,
1028
- invocation_id=invocation_id,
1029
- metadata_path=canonical_metadata,
1030
- )
1031
- digest = _sha256(envelope_bytes)
1032
- if completion.get("resultEnvelopeDigest") != digest:
1033
- raise AgentInvocationError("result envelope digest does not match completion")
1034
- return VerifiedStandaloneResult(
1035
- purpose=expected_purpose,
1036
- invocation_id=invocation_id,
1037
- prompt_metadata_path=metadata_path,
1038
- result_path=result_path,
1039
- completion_path=canonical_completion,
1040
- result_envelope_digest=digest,
1041
- returned_body=returned_body,
1093
+ return _StandaloneCompletion(
1094
+ completion, invocation_id, root, metadata_path, result_path, canonical_completion,
1042
1095
  )
1043
1096
 
1044
1097
 
@@ -1090,6 +1143,8 @@ def _verified_result_envelope(
1090
1143
  invocation_id: str,
1091
1144
  metadata_path: Path,
1092
1145
  ) -> tuple[bytes, str]:
1146
+ project_root = project_root.resolve(strict=True)
1147
+ result_path = result_path.parent.resolve(strict=True) / result_path.name
1093
1148
  try:
1094
1149
  body = result_path.read_bytes()
1095
1150
  envelope = load_external_json(
@@ -1184,11 +1239,30 @@ def _bind_generation_request(request: AgentInvocationRequest) -> AgentInvocation
1184
1239
  try:
1185
1240
  manifest = _load_request_manifest(request)
1186
1241
  reference = _typed_generation_reference(request)
1187
- _require_sealed_generation(
1242
+ generation = read_invocation_generation(
1188
1243
  request.project_root, request.run_manifest_path, manifest,
1189
1244
  reference, request.audience,
1190
1245
  )
1191
- return _with_generation_anchors(request, reference)
1246
+ bound = _with_generation_anchors(request, reference)
1247
+ if generation is not None and "designReview" in generation:
1248
+ from ..design_review import render_design_review
1249
+
1250
+ supplement = render_design_review(generation["designReview"])
1251
+ from ..design_review_evidence import prior_design_review_prompt
1252
+
1253
+ supplement += prior_design_review_prompt(
1254
+ request.project_root, request.run_manifest_path,
1255
+ request.role_execution_ref, generation["generation"],
1256
+ request.invocation_ref, request.attempt,
1257
+ )
1258
+ body = bound.instruction.body
1259
+ if not body.rstrip().endswith(supplement.rstrip()):
1260
+ if "\n## Frozen Design Review\n" in body:
1261
+ raise ValueError("design review body differs from sealed generation")
1262
+ bound = replace(bound, instruction=replace(
1263
+ bound.instruction, body=body.rstrip() + "\n" + supplement,
1264
+ ))
1265
+ return bound
1192
1266
  except (OSError, ValueError) as exc:
1193
1267
  raise AgentInvocationError(str(exc)) from exc
1194
1268
 
@@ -1973,6 +2047,9 @@ def _verify_prompt_file(
1973
2047
  errors.extend(_verify_model_header(metadata, body))
1974
2048
  errors.extend(_verify_execution_delivery(metadata, path, body))
1975
2049
  errors.extend(_verify_generation_reference(metadata, project_root, body))
2050
+ from ..code_review_invocation import review_policy_errors_for_prompt
2051
+
2052
+ errors.extend(review_policy_errors_for_prompt(project_root, metadata, body))
1976
2053
  return errors
1977
2054
 
1978
2055
 
@@ -2010,6 +2087,16 @@ def reserved_generation_reference(
2010
2087
  The reservation names the metadata, so a reader does not take a generation
2011
2088
  file on the strength of the path its dispatch kind computes.
2012
2089
  """
2090
+ metadata_path = reserved_invocation_metadata_path(project_root, manifest, invocation_ref, attempt)
2091
+ if metadata_path is None:
2092
+ return None
2093
+ metadata = _load_json_object(metadata_path, "agent invocation metadata")
2094
+ return metadata_generation_reference(metadata)
2095
+
2096
+
2097
+ def reserved_invocation_metadata_path(
2098
+ project_root: Path, manifest: Mapping[str, object], invocation_ref: str, attempt: int,
2099
+ ) -> Path | None:
2013
2100
  contract = manifest.get("agentContract")
2014
2101
  if not isinstance(contract, Mapping):
2015
2102
  return None
@@ -2020,17 +2107,15 @@ def reserved_generation_reference(
2020
2107
  if not path.is_file():
2021
2108
  return None
2022
2109
  reservation = _load_json_object(path, "invocation reservation")
2023
- metadata = _load_json_object(
2024
- _project_path(project_root, reservation.get("metadataPath"), must_exist=True),
2025
- "agent invocation metadata",
2026
- )
2110
+ metadata_path = _project_path(project_root, reservation.get("metadataPath"), must_exist=True)
2111
+ metadata = _load_json_object(metadata_path, "agent invocation metadata")
2027
2112
  for payload in (reservation, metadata):
2028
2113
  if (payload.get("invocationRef"), payload.get("attempt")) != (
2029
2114
  invocation_ref, attempt):
2030
2115
  raise AgentInvocationError(
2031
2116
  f"invocation reservation {path} names another invocation attempt"
2032
2117
  )
2033
- return metadata_generation_reference(metadata)
2118
+ return metadata_path
2034
2119
 
2035
2120
 
2036
2121
  def _attempt_invocation_id(invocation_ref: str, attempt: int) -> str:
@@ -129,6 +129,12 @@ def _add_materialize_parser(commands: argparse._SubParsersAction) -> None:
129
129
  materialize.add_argument("--model-role", help=standalone_only)
130
130
  materialize.add_argument("--model", default="", help=standalone_only)
131
131
  materialize.add_argument("--purpose", help=standalone_only)
132
+ materialize.add_argument("--review-policy", help=standalone_only + "; frozen shared code-review policy")
133
+ materialize.add_argument("--review-census", help=standalone_only + "; assigned code-review census")
134
+ materialize.add_argument("--review-base", help=standalone_only + "; fixed review base")
135
+ materialize.add_argument("--review-head", help=standalone_only + "; fixed review head")
136
+ materialize.add_argument("--review-resource", action="append", default=[],
137
+ help=standalone_only + "; additional frozen pack-relative resource")
132
138
  materialize.add_argument(
133
139
  "--replace-undispatched",
134
140
  action="store_true",
@@ -32,6 +32,7 @@ from ..invocation import (
32
32
  )
33
33
  from ...assignment_environment import load_assignment_context
34
34
  from ..standalone import StandaloneInvocationRequest, prepare_standalone_invocation
35
+ from ...code_review_invocation import CodeReviewInputs
35
36
  from ...path_hints import hydrate_active_run_context
36
37
  from ...worker_prompt_headers import worker_prompt_headers
37
38
  from ...worker_prompt_contract import (
@@ -134,6 +135,9 @@ def _materialize_run(
134
135
  "model-role": args.model_role,
135
136
  "model": args.model,
136
137
  "purpose": args.purpose,
138
+ **{f"review-{name}": getattr(args, f"review_{name}", None)
139
+ for name in ("policy", "census", "base", "head")},
140
+ "review-resource": getattr(args, "review_resource", ()),
137
141
  }
138
142
  present = [name for name, value in forbidden.items() if value]
139
143
  if present:
@@ -922,10 +926,9 @@ def _roster_result_path(
922
926
  return None
923
927
 
924
928
 
925
- def _materialize_standalone(
926
- args: argparse.Namespace,
927
- project_root: Path,
928
- ) -> PreparedAgentInvocation:
929
+ def _standalone_input_paths(
930
+ args: argparse.Namespace, project_root: Path,
931
+ ) -> tuple[Path, Path]:
929
932
  required = {
930
933
  "host-runtime": args.host_runtime,
931
934
  "provider": args.provider,
@@ -967,15 +970,38 @@ def _materialize_standalone(
967
970
  expected_prompt = root / f"{args.invocation_id}.prompt.md"
968
971
  instruction_path = _exact_path(args.instruction, expected_instruction, True, "instruction")
969
972
  prompt_path = _exact_path(args.prompt, expected_prompt, False, "prompt")
973
+ return instruction_path, prompt_path
974
+
975
+
976
+ def _materialize_standalone(
977
+ args: argparse.Namespace,
978
+ project_root: Path,
979
+ ) -> PreparedAgentInvocation:
980
+ instruction_path, prompt_path = _standalone_input_paths(args, project_root)
970
981
  assignment_context = load_assignment_context(
971
982
  host_runtime=args.host_runtime,
972
983
  terminal_backend=args.terminal_backend or detect_terminal_backend(),
973
984
  execution_provider_ids=(args.provider,),
974
985
  include_native_provider=False,
975
986
  )
987
+ review_values = [getattr(args, f"review_{name}", None)
988
+ for name in ("policy", "census", "base", "head")]
989
+ review_inputs = None
990
+ if args.audience == "code-reviewer" or any(review_values):
991
+ if args.audience != "code-reviewer" or not all(review_values):
992
+ raise AgentPromptCliError(
993
+ "code-reviewer requires --review-policy, --review-census, --review-base and --review-head"
994
+ )
995
+ review_inputs = CodeReviewInputs(
996
+ _project_input(project_root, args.review_policy, "review policy"),
997
+ _project_input(project_root, args.review_census, "review census"),
998
+ args.review_base, args.review_head,
999
+ tuple(getattr(args, "review_resource", ())),
1000
+ )
976
1001
  return prepare_standalone_invocation(StandaloneInvocationRequest(
977
1002
  project_root=project_root, invocation_id=args.invocation_id, audience=args.audience,
978
1003
  purpose=args.purpose, context=assignment_context, provider=args.provider,
979
1004
  model_role=args.model_role, model=args.model, instruction_path=instruction_path,
980
1005
  prompt_path=prompt_path, requested_runner=args.execution_runner,
1006
+ review_inputs=review_inputs,
981
1007
  ))
@@ -7,6 +7,7 @@ from dataclasses import dataclass
7
7
  from pathlib import Path
8
8
 
9
9
  from ..assignment_resolver import AssignmentContext, resolve_dispatch_assignment
10
+ from ..code_review_invocation import CodeReviewInputs
10
11
  from .invocation import (
11
12
  AgentAudience,
12
13
  AgentInstruction,
@@ -33,6 +34,7 @@ class StandaloneInvocationRequest:
33
34
  instruction_path: Path
34
35
  prompt_path: Path
35
36
  requested_runner: str | None = None
37
+ review_inputs: CodeReviewInputs | None = None
36
38
 
37
39
 
38
40
  def prepare_standalone_invocation(
@@ -83,6 +85,7 @@ def prepare_standalone_invocation(
83
85
  duty_id=None,
84
86
  invocation_ref=None,
85
87
  attempt=1,
88
+ review_inputs=request.review_inputs,
86
89
  )
87
90
  )
88
91
 
@@ -5,6 +5,8 @@ import hashlib
5
5
  import re
6
6
  from pathlib import Path
7
7
 
8
+ from okstra_project.dirs import contained_relative_path as project_relative_ref
9
+
8
10
  from . import group_context
9
11
 
10
12
 
@@ -575,25 +577,6 @@ def exceeds_cited_document_limit(size: int) -> bool:
575
577
  return size > MAX_CITED_DOCUMENT_BYTES
576
578
 
577
579
 
578
- def project_relative_ref(ref: str, root: Path) -> str | None:
579
- """The posix path of a Source Material `ref` relative to the resolved `root`.
580
-
581
- None when the ref resolves outside the root, or names the home directory of
582
- a user this machine does not know (`~200` in prose). Every reader and
583
- writer of a `### Source N — file` ref goes through here so they agree on
584
- which file it names.
585
- """
586
- try:
587
- candidate = Path(ref).expanduser()
588
- except RuntimeError:
589
- return None
590
- path = (candidate if candidate.is_absolute() else root / candidate).resolve()
591
- try:
592
- return path.relative_to(root).as_posix()
593
- except ValueError:
594
- return None
595
-
596
-
597
580
  def _by_reference_file_refs(source_material: str) -> list[str]:
598
581
  refs = [ref for ref, fmt in file_source_entries(source_material) if fmt == BY_REFERENCE_FORMAT]
599
582
  return list(dict.fromkeys(refs))
@@ -164,6 +164,16 @@ def _stream_payload(path: Path) -> dict[str, Any]:
164
164
  }
165
165
 
166
166
 
167
+ def read_sealed_artifact(seal: AttemptEvidenceSeal, path: Path) -> bytes:
168
+ row = next((row for row in seal.artifacts if row.get("normalizedPath") == str(path)), None)
169
+ if row is None or path.is_symlink() or not path.is_file():
170
+ raise AttemptEvidenceError(f"artifact is absent from the attempt seal: {path}")
171
+ data = path.read_bytes()
172
+ if len(data) != row.get("byteLength") or _sha(data) != row.get("sha256"):
173
+ raise AttemptEvidenceError(f"sealed artifact bytes changed: {path}")
174
+ return data
175
+
176
+
167
177
  def _build_seal(
168
178
  attempt_ref: str, terminal: TerminalObservation
169
179
  ) -> AttemptEvidenceSeal:
@@ -2,12 +2,14 @@
2
2
  from __future__ import annotations
3
3
 
4
4
  import ast
5
+ import json
5
6
  import re
6
7
  import subprocess
7
8
  from dataclasses import dataclass
8
9
  from pathlib import Path, PurePosixPath
10
+ from collections.abc import Mapping
9
11
 
10
- from .code_review_coverage import read_review_census
12
+ from .review_verdicts import read_review_census
11
13
 
12
14
  _GROUPS = ("structural", "semantic", "state-and-tests", "general")
13
15
  _FILE_GROUPS = {
@@ -20,7 +22,7 @@ _LOCKFILES = {
20
22
  "Cargo.lock", "uv.lock", "Gemfile.lock", "composer.lock",
21
23
  }
22
24
  _GENERATED_ROOTS = ("dist/", "runtime/", "build/")
23
- _DATA_SUFFIXES = {".json", ".yml", ".yaml", ".toml", ".ini", ".cfg", ".csv"}
25
+ _DATA_SUFFIXES = {".csv"}
24
26
  _PROSE_SUFFIXES = {".md", ".markdown", ".rst", ".txt"}
25
27
  _UNPARSED_CODE_SUFFIXES = {
26
28
  ".js", ".mjs", ".cjs", ".ts", ".mts", ".cts", ".tsx", ".jsx", ".sh", ".bash",
@@ -43,8 +45,9 @@ class CensusResult:
43
45
  def build_review_census(
44
46
  repo: Path, base: str, head: str, rules_source: Path,
45
47
  changed: dict[str, set[int]], *, previous: Path | None = None,
48
+ frozen_rules: str | None = None, inventory: Mapping[str, object] | None = None,
46
49
  ) -> CensusResult:
47
- rules = _rules_section(rules_source.read_text(encoding="utf-8"))
50
+ rules = _rules_section(rules_source) if frozen_rules is None else frozen_rules
48
51
  files = _changed_files(repo, base, head)
49
52
  cells: list[tuple[str, str]] = []
50
53
  exclusions: list[tuple[str, str]] = []
@@ -57,13 +60,23 @@ def build_review_census(
57
60
  continue
58
61
  kind = "test" if _TEST_PATH.search(path) else "source"
59
62
  cells.extend((path, group) for group in _FILE_GROUPS[kind])
60
- if kind == "test" or path not in changed:
63
+ if path not in changed:
61
64
  continue
62
65
  suffix = PurePosixPath(path).suffix
63
66
  if suffix == ".py":
64
67
  functions.extend(_changed_functions(repo, head, path, changed[path]))
65
68
  elif suffix in _UNPARSED_CODE_SUFFIXES:
66
- unresolved.append(path)
69
+ if inventory is None or path not in inventory:
70
+ unresolved.append(path)
71
+ else:
72
+ functions.extend(_supplement_functions(repo, head, path, changed[path],
73
+ inventory[path]))
74
+ if inventory is not None:
75
+ eligible = {path for path, _ in files if path in changed
76
+ and PurePosixPath(path).suffix in _UNPARSED_CODE_SUFFIXES
77
+ and _exclusion(path, False) is None}
78
+ if inventory.keys() - eligible:
79
+ raise ValueError("function inventory names files outside the unresolved census")
67
80
  cells.extend((target, "semantic") for target in functions)
68
81
  ordered = sorted(cells, key=lambda cell: _GROUPS.index(cell[1]))
69
82
  ids, retired, new = _assign_ids(ordered, previous)
@@ -72,7 +85,10 @@ def build_review_census(
72
85
  return CensusResult(text, tuple(unresolved))
73
86
 
74
87
 
75
- def _rules_section(text: str) -> str:
88
+ def _rules_section(source: Path) -> str:
89
+ text = source.read_text(encoding="utf-8")
90
+ if source.suffix == ".json":
91
+ return render_rule_catalog(text, source.parent)
76
92
  start = text.find("## Rules")
77
93
  if start < 0:
78
94
  raise ValueError("rules source has no ## Rules table")
@@ -80,6 +96,52 @@ def _rules_section(text: str) -> str:
80
96
  return text[start:] if end < 0 else text[start:end + 1]
81
97
 
82
98
 
99
+ def render_rule_catalog(text: str, parent: Path, *, include_architecture: bool = True) -> str:
100
+ catalog = json.loads(text)
101
+ if (not isinstance(catalog, dict) or catalog.get("schemaVersion") != "1.0"
102
+ or not isinstance(catalog.get("rules"), dict)):
103
+ raise ValueError("unsupported review rule catalog")
104
+ rows = ["## Rules", "| Rule | Group | Reference |", "|---|---|---|"]
105
+ for identity, definition in catalog["rules"].items():
106
+ if (not isinstance(definition, list) or len(definition) != 2
107
+ or not all(isinstance(value, str) for value in definition)):
108
+ raise ValueError(f"invalid review rule: {identity}")
109
+ group, reference = definition
110
+ if not include_architecture and identity in {"S5", "S6", "S7", "S8", "S9", "S10"}:
111
+ continue
112
+ path, _, heading = reference.partition("#")
113
+ rows.append(f"| {identity} | {group} | {parent / path}#{heading} |")
114
+ return "\n".join(rows)
115
+
116
+
117
+ def _supplement_functions(
118
+ repo: Path, head: str, path: str, lines: set[int], entry: object,
119
+ ) -> list[str]:
120
+ if (not isinstance(entry, dict) or set(entry) != {"functions", "rationale"}
121
+ or not isinstance(entry["rationale"], str) or not entry["rationale"].strip()
122
+ or not isinstance(entry["functions"], list)):
123
+ raise ValueError(f"function inventory needs functions and a completeness rationale: {path}")
124
+ source = subprocess.run(["git", "-C", str(repo), "show", f"{head}:{path}"],
125
+ capture_output=True, text=True, check=True).stdout.splitlines()
126
+ targets: list[str] = []
127
+ seen: set[tuple[int, int, str]] = set()
128
+ for row in entry["functions"]:
129
+ if not isinstance(row, dict) or set(row) != {"start", "end", "name"}:
130
+ raise ValueError(f"invalid function inventory row: {path}")
131
+ start, end, name = row["start"], row["end"], row["name"]
132
+ if (type(start) is not int or type(end) is not int
133
+ or not 1 <= start <= end <= len(source)
134
+ or not isinstance(name, str) or not re.fullmatch(r"[\w.$<>:-]+", name)):
135
+ raise ValueError(f"invalid function inventory span or name: {path}")
136
+ identity = (start, end, name)
137
+ if identity in seen:
138
+ raise ValueError(f"duplicate function inventory row: {path}")
139
+ seen.add(identity)
140
+ if lines.intersection(range(start, end + 1)):
141
+ targets.append(f"{path}:{start} {name}")
142
+ return targets
143
+
144
+
83
145
  def _changed_files(repo: Path, base: str, head: str) -> list[tuple[str, bool]]:
84
146
  listed = subprocess.run(
85
147
  ["git", "-C", str(repo), "diff", "--numstat", "-z", "-M", "--no-ext-diff",
@@ -111,8 +173,10 @@ def _exclusion(path: str, binary: bool) -> str | None:
111
173
  return "generated build output"
112
174
  if binary:
113
175
  return "binary file"
176
+ if name in ("AGENTS.md", "CLAUDE.md"):
177
+ return None
114
178
  if suffix in _DATA_SUFFIXES:
115
- return "configuration or data without executable project code"
179
+ return "data without executable project code"
116
180
  if suffix in _PROSE_SUFFIXES:
117
181
  return "prose documentation without executable or agent-directive content"
118
182
  return None