okstra 0.232.0 → 0.234.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 (205) hide show
  1. package/README.md +19 -283
  2. package/dist/cli-registry.mjs +14 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/trace/capacity.d.mts +12 -0
  10. package/dist/commands/trace/capacity.mjs +21 -0
  11. package/dist/commands/trace/capacity.mjs.map +1 -0
  12. package/dist/commands/trace/model.d.mts +89 -0
  13. package/dist/commands/trace/model.mjs +251 -0
  14. package/dist/commands/trace/model.mjs.map +1 -0
  15. package/dist/commands/trace/progression.d.mts +11 -0
  16. package/dist/commands/trace/progression.mjs +194 -0
  17. package/dist/commands/trace/progression.mjs.map +1 -0
  18. package/dist/commands/trace/review.d.mts +7 -0
  19. package/dist/commands/trace/review.mjs +51 -0
  20. package/dist/commands/trace/review.mjs.map +1 -0
  21. package/dist/commands/trace/task-link.d.mts +18 -0
  22. package/dist/commands/trace/task-link.mjs +72 -0
  23. package/dist/commands/trace/task-link.mjs.map +1 -0
  24. package/dist/commands/trace/trace.d.mts +1 -0
  25. package/dist/commands/trace/trace.mjs +293 -0
  26. package/dist/commands/trace/trace.mjs.map +1 -0
  27. package/dist/lib/bounded-file.d.mts +1 -0
  28. package/dist/lib/bounded-file.mjs +36 -0
  29. package/dist/lib/bounded-file.mjs.map +1 -0
  30. package/dist/lib/config-store.d.mts +34 -0
  31. package/dist/lib/config-store.mjs +70 -0
  32. package/dist/lib/config-store.mjs.map +1 -0
  33. package/dist/lib/file-lock.mjs +4 -5
  34. package/dist/lib/file-lock.mjs.map +1 -1
  35. package/dist/lib/input-limit.d.mts +4 -0
  36. package/dist/lib/input-limit.mjs +8 -0
  37. package/dist/lib/input-limit.mjs.map +1 -0
  38. package/dist/lib/memory-auto-register.mjs +2 -17
  39. package/dist/lib/memory-auto-register.mjs.map +1 -1
  40. package/dist/lib/report-language-tag.d.mts +1 -0
  41. package/dist/lib/report-language-tag.mjs +4 -0
  42. package/dist/lib/report-language-tag.mjs.map +1 -0
  43. package/dist/lib/report-language.d.mts +1 -0
  44. package/dist/lib/report-language.mjs +50 -0
  45. package/dist/lib/report-language.mjs.map +1 -0
  46. package/dist/lib/skill-catalog.mjs +3 -0
  47. package/dist/lib/skill-catalog.mjs.map +1 -1
  48. package/docs/architecture/storage-model.md +55 -5
  49. package/docs/architecture.md +10 -4
  50. package/docs/cli.md +320 -3
  51. package/docs/contributor-change-matrix.md +1 -2
  52. package/docs/project-structure-overview.md +34 -43
  53. package/package.json +1 -1
  54. package/runtime/BUILD.json +2 -2
  55. package/runtime/agents/operations/trace-interface-review.json +6 -0
  56. package/runtime/agents/operations/trace-scope-review.json +6 -0
  57. package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
  58. package/runtime/prompts/coding-preflight/clean-code.md +18 -20
  59. package/runtime/prompts/coding-preflight/overview.md +1 -1
  60. package/runtime/prompts/duties/code-reviewer.json +1 -1
  61. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  62. package/runtime/prompts/host-orchestration/README.md +18 -9
  63. package/runtime/prompts/launch.template.md +3 -2
  64. package/runtime/prompts/lead/context-loader.md +2 -0
  65. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  66. package/runtime/prompts/lead/report-writer.md +6 -6
  67. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
  68. package/runtime/prompts/profiles/_common-contract.md +1 -1
  69. package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
  70. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
  71. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  72. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
  73. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  74. package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
  75. package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
  76. package/runtime/python/okstra_ctl/business_flow/cli.py +60 -6
  77. package/runtime/python/okstra_ctl/business_flow/contracts.py +12 -1
  78. package/runtime/python/okstra_ctl/business_flow/engine.py +17 -5
  79. package/runtime/python/okstra_ctl/business_flow/history.py +60 -0
  80. package/runtime/python/okstra_ctl/business_flow/source.py +35 -2
  81. package/runtime/python/okstra_ctl/business_flow/store.py +51 -14
  82. package/runtime/python/okstra_ctl/business_flow/sweep.py +124 -0
  83. package/runtime/python/okstra_ctl/code_review_census.py +93 -2
  84. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  85. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  86. package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
  87. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  88. package/runtime/python/okstra_ctl/code_review_target.py +140 -15
  89. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  90. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  91. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  92. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  93. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  94. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  95. package/runtime/python/okstra_ctl/doyouknow/cli.py +9 -9
  96. package/runtime/python/okstra_ctl/doyouknow/config.py +2 -2
  97. package/runtime/python/okstra_ctl/doyouknow/group_view.py +152 -0
  98. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +4 -3
  99. package/runtime/python/okstra_ctl/doyouknow/source_store.py +2 -2
  100. package/runtime/python/okstra_ctl/doyouknow/sources/business.py +116 -0
  101. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
  102. package/runtime/python/okstra_ctl/doyouknow/sync.py +34 -9
  103. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  104. package/runtime/python/okstra_ctl/fixed_text.py +10 -0
  105. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  106. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  107. package/runtime/python/okstra_ctl/json_boundary.py +33 -6
  108. package/runtime/python/okstra_ctl/manager_cli.py +122 -1
  109. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  110. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  111. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  112. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  113. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  114. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  115. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  116. package/runtime/python/okstra_ctl/manager_sync.py +42 -3
  117. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  118. package/runtime/python/okstra_ctl/material.py +2 -0
  119. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  120. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  121. package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
  122. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  123. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  124. package/runtime/python/okstra_ctl/paths.py +6 -1
  125. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  126. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  127. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
  128. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  129. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  130. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  131. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
  132. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  133. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  134. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
  135. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  136. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  137. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  138. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  139. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  140. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  141. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  142. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  143. package/runtime/python/okstra_ctl/project_group.py +175 -0
  144. package/runtime/python/okstra_ctl/project_group_cli.py +62 -0
  145. package/runtime/python/okstra_ctl/render.py +28 -2
  146. package/runtime/python/okstra_ctl/report_assembly.py +38 -11
  147. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  148. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  149. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  150. package/runtime/python/okstra_ctl/report_language.py +4 -1
  151. package/runtime/python/okstra_ctl/report_narrative.py +179 -7
  152. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  153. package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
  154. package/runtime/python/okstra_ctl/run.py +43 -35
  155. package/runtime/python/okstra_ctl/run_context.py +10 -1
  156. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  157. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  158. package/runtime/python/okstra_ctl/task_query.py +239 -0
  159. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  160. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  161. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  162. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  163. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  164. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  165. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  166. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  167. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  168. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  169. package/runtime/python/okstra_project/state.py +20 -0
  170. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  171. package/runtime/python/okstra_token_usage/cli.py +23 -10
  172. package/runtime/python/okstra_token_usage/collect.py +25 -22
  173. package/runtime/python/okstra_token_usage/policy.py +193 -0
  174. package/runtime/schemas/business-flow-v1.schema.json +3 -0
  175. package/runtime/schemas/doyouknow-config-v1.schema.json +1 -1
  176. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  177. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  178. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  179. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  180. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  181. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  182. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  183. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  184. package/runtime/skills/okstra-code-review/SKILL.md +58 -50
  185. package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
  186. package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
  187. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  188. package/runtime/skills/okstra-explain-flow/SKILL.md +33 -4
  189. package/runtime/skills/okstra-manager/SKILL.md +24 -0
  190. package/runtime/skills/okstra-memory/SKILL.md +1 -1
  191. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  192. package/runtime/skills/okstra-run/SKILL.md +55 -183
  193. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  194. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  195. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  196. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  197. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  198. package/runtime/templates/doyouknow/group-view.css +103 -0
  199. package/runtime/templates/doyouknow/group-view.js +317 -0
  200. package/runtime/templates/doyouknow/group-view.template.html +72 -0
  201. package/runtime/templates/manager/view.template.html +4 -0
  202. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  203. package/runtime/templates/trace/trace.template.md +42 -0
  204. package/runtime/validators/checks/fixtures-02.py +25 -33
  205. package/runtime/validators/validate-run.py +93 -36
@@ -0,0 +1,239 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ from dataclasses import dataclass
5
+ from pathlib import Path
6
+ from typing import TypedDict
7
+
8
+ from okstra_project import StateError, parse_task_key, resolve_task_root_read_only
9
+ from okstra_project.dirs import TASK_CATALOG_RELATIVE
10
+ from okstra_project.state import derived_task_status
11
+
12
+ from .doyouknow.contracts import DoyouknowError, reject_secrets
13
+ from .doyouknow.sources.io import safe_source_path
14
+ from .json_boundary import JsonBoundaryError, PageBudgetExhausted, ReadBudget, load_owned_object
15
+ from .trace_tasks import TRACE_METADATA_LIST_LIMITS, TRACE_METADATA_TEXT_LIMITS, read_task_trace
16
+
17
+ QUERY_CATALOG_BYTES = 4 * 1024 * 1024
18
+ QUERY_SOURCE_BYTES = 2 * 1024 * 1024
19
+ QUERY_OUTPUT_BYTES = 256 * 1024
20
+ QUERY_PAGE_SOURCE_BYTES = 16 * 1024 * 1024
21
+ QUERY_CATALOG_ENTRIES = 1000
22
+ QUERY_PAGE_TASKS = 64
23
+ QUERY_PREVIEW_CHARS = 160
24
+ QUERY_TEXT_CHARS = 256
25
+ QUERY_MAX_RESULTS = 100
26
+ QUERY_KEY_CHARS = 384
27
+ QUERY_TITLE_CHARS = TRACE_METADATA_TEXT_LIMITS["title"]
28
+ QUERY_LABEL_CHARS = 64
29
+ QUERY_METADATA_LIMITS = TRACE_METADATA_LIST_LIMITS
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class TaskDocument:
34
+ key: str
35
+ title: str
36
+ status: str
37
+ execution_kind: str
38
+ trace_path: str
39
+ record_path: str
40
+ text: str
41
+ links: frozenset[str]
42
+ tags: frozenset[str]
43
+ files: frozenset[str]
44
+ references: frozenset[str]
45
+
46
+
47
+ class SearchMetadata(TypedDict):
48
+ title: str
49
+ summary: str
50
+ links: frozenset[str]
51
+ tags: frozenset[str]
52
+ files: frozenset[str]
53
+ references: frozenset[str]
54
+
55
+
56
+ class TaskQueryError(Exception):
57
+ pass
58
+
59
+
60
+ def _regular_source_path(root: Path, path: str | Path) -> Path:
61
+ source = safe_source_path(root, path)
62
+ if not source.is_file():
63
+ raise TaskQueryError("source-unavailable")
64
+ return source
65
+
66
+
67
+ def _read_object(root: Path, path: str | Path, maximum: int = QUERY_SOURCE_BYTES, *, budget: ReadBudget | None = None) -> dict:
68
+ value = load_owned_object(_regular_source_path(root, path), artifact="task query source", max_bytes=maximum, budget=budget)
69
+ reject_secrets(json.dumps(value, ensure_ascii=False))
70
+ return value
71
+
72
+
73
+ def _string_values(value: object, maximum: int | None, item_chars: int) -> frozenset[str]:
74
+ if value is None:
75
+ return frozenset()
76
+ if not isinstance(value, list) or (maximum is not None and len(value) > maximum) or any(not isinstance(item, str) or len(item) > item_chars for item in value):
77
+ raise TaskQueryError("source-unavailable")
78
+ return frozenset(value)
79
+
80
+
81
+ def _read_owned_manifest(root: Path, project: str, entry: dict, catalog: list[dict], budget: ReadBudget) -> tuple[Path, dict]:
82
+ key = entry["taskKey"]
83
+ owner, group, task = parse_task_key(key)
84
+ if owner != project:
85
+ raise TaskQueryError("source-unavailable")
86
+ task_root = resolve_task_root_read_only(root, key, catalog=catalog)
87
+ if task_root is None:
88
+ raise TaskQueryError("source-unavailable")
89
+ task_root = safe_source_path(root, task_root)
90
+ manifest = _read_object(task_root, "task-manifest.json", budget=budget)
91
+ if (manifest.get("taskKey"), manifest.get("projectId"), manifest.get("taskGroup"), manifest.get("taskId")) != (key, project, group, task):
92
+ raise TaskQueryError("source-unavailable")
93
+ return task_root, manifest
94
+
95
+
96
+ def _normalize_search_metadata(manifest: dict, entry: dict) -> SearchMetadata:
97
+ metadata = manifest.get("traceMetadata", {})
98
+ if not isinstance(metadata, dict) or any(
99
+ field in metadata and (not isinstance(metadata[field], str) or len(metadata[field]) > maximum)
100
+ for field, maximum in TRACE_METADATA_TEXT_LIMITS.items()
101
+ ):
102
+ raise TaskQueryError("source-unavailable")
103
+ return {
104
+ "title": str(metadata.get("title") or manifest.get("title") or entry.get("title") or manifest["taskId"]),
105
+ "summary": str(metadata.get("summary") or manifest.get("workStatusNote") or ""),
106
+ "links": _string_values(manifest.get("relatedTasks"), None, QUERY_KEY_CHARS) | _string_values(metadata.get("relatedTasks"), *QUERY_METADATA_LIMITS["relatedTasks"]),
107
+ "tags": _string_values(metadata.get("tags", manifest.get("tags")), *QUERY_METADATA_LIMITS["tags"]),
108
+ "files": _string_values(metadata.get("changedFiles", manifest.get("changedFiles")), *QUERY_METADATA_LIMITS["changedFiles"]),
109
+ "references": _string_values(metadata.get("references", manifest.get("references")), *QUERY_METADATA_LIMITS["references"]),
110
+ }
111
+
112
+
113
+ def _read_linked_search_sources(root: Path, task_root: Path, manifest: dict, key: str, budget: ReadBudget) -> tuple[str, str]:
114
+ trace_path = manifest.get("implementationTracePath", "")
115
+ trace_text, record_summary = "", ""
116
+ if trace_path:
117
+ _regular_source_path(root, trace_path)
118
+ trace_text = read_task_trace(root, trace_path, key, budget=budget).text
119
+ reject_secrets(trace_text)
120
+ record_path = manifest.get("latestWorkRecordPath", "")
121
+ if record_path:
122
+ record = _read_object(task_root, safe_source_path(root, record_path), budget=budget)
123
+ if record.get("taskKey") != key:
124
+ raise TaskQueryError("source-unavailable")
125
+ record_summary = " " + str(record.get("summary") or "")
126
+ return trace_text, record_summary
127
+
128
+
129
+ def _read_document(root: Path, project: str, entry: dict, catalog: list[dict], budget: ReadBudget) -> TaskDocument:
130
+ task_root, manifest = _read_owned_manifest(root, project, entry, catalog, budget)
131
+ metadata = _normalize_search_metadata(manifest, entry)
132
+ trace_text, record_summary = _read_linked_search_sources(root, task_root, manifest, entry["taskKey"], budget)
133
+ text = "\n".join((metadata["title"], metadata["summary"] + record_summary,
134
+ *sorted(metadata["tags"]), *sorted(metadata["files"]), *sorted(metadata["references"]), *sorted(metadata["links"]), trace_text))
135
+ return TaskDocument(
136
+ key=entry["taskKey"], title=metadata["title"],
137
+ status=derived_task_status(manifest).get("workStatus", ""),
138
+ execution_kind=str(manifest.get("executionKind") or ""),
139
+ trace_path=manifest.get("implementationTracePath", ""),
140
+ record_path=manifest.get("latestWorkRecordPath", ""), text=text,
141
+ links=metadata["links"], tags=metadata["tags"], files=metadata["files"], references=metadata["references"],
142
+ )
143
+
144
+
145
+ def _relation_reasons(origin: TaskDocument, candidate: TaskDocument) -> list[dict]:
146
+ reasons = []
147
+ if candidate.key in origin.links or origin.key in candidate.links:
148
+ reasons.append({"kind": "related-task", "reason": "An explicit related-task link connects these tasks.", "standing": "user-stated", "evidence": [origin.key, candidate.key]})
149
+ for kind, shared in (("tag", origin.tags & candidate.tags), ("changed-file", origin.files & candidate.files), ("reference", origin.references & candidate.references)):
150
+ if shared:
151
+ reasons.append({"kind": kind, "reason": f"Tasks share {kind} metadata.", "standing": "candidate", "evidence": sorted(shared)})
152
+ return reasons
153
+
154
+
155
+ def _result(document: TaskDocument, terms: list[str], reasons: list[dict]) -> dict:
156
+ preview = document.text
157
+ if terms:
158
+ start = preview.casefold().find(terms[0])
159
+ preview = preview[max(0, start):]
160
+ return {"taskKey": document.key, "title": document.title[:QUERY_TITLE_CHARS], "workStatus": document.status[:QUERY_LABEL_CHARS],
161
+ "executionKind": document.execution_kind[:QUERY_LABEL_CHARS], "implementationTracePath": document.trace_path, "latestWorkRecordPath": document.record_path,
162
+ "preview": " ".join(preview.split())[:QUERY_PREVIEW_CHARS], "reasons": reasons}
163
+
164
+
165
+ def query_project_tasks(root: Path, *, query: str = "", related_to: str = "", after: str = "", limit: int = 20,
166
+ task_type: str = "", latest_run_status: str = "", task_group: str = "") -> dict:
167
+ if len(query) > QUERY_TEXT_CHARS or not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= QUERY_MAX_RESULTS:
168
+ raise TaskQueryError("invalid-query")
169
+ try:
170
+ project = _read_object(root, ".okstra/project.json")["projectId"]
171
+ catalog_path = safe_source_path(root, TASK_CATALOG_RELATIVE)
172
+ catalog = _read_object(root, catalog_path, QUERY_CATALOG_BYTES).get("tasks", []) if catalog_path.exists() else []
173
+ if not isinstance(catalog, list) or len(catalog) > QUERY_CATALOG_ENTRIES:
174
+ raise TaskQueryError("source-unavailable")
175
+ if any(not isinstance(row, dict) or not isinstance(row.get("taskKey"), str) for row in catalog):
176
+ raise TaskQueryError("source-unavailable")
177
+ entries = sorted(catalog, key=lambda row: row["taskKey"])
178
+ keys = [row["taskKey"] for row in entries]
179
+ if len(set(keys)) != len(keys) or any(len(key) > QUERY_KEY_CHARS or parse_task_key(key)[0] != project for key in keys):
180
+ raise TaskQueryError("source-unavailable")
181
+ for token in (after, related_to):
182
+ if token and (len(token) > QUERY_KEY_CHARS or parse_task_key(token)[0] != project):
183
+ raise TaskQueryError("invalid-query")
184
+ budget = ReadBudget(QUERY_PAGE_SOURCE_BYTES)
185
+ origin = None
186
+ if related_to:
187
+ selected = next((entry for entry in entries if entry["taskKey"] == related_to), None)
188
+ if selected is None:
189
+ raise TaskQueryError("source-unavailable")
190
+ origin = _read_document(root, project, selected, catalog, budget)
191
+ return _query_page(root, project, entries, catalog, query, origin, after, limit, task_type, latest_run_status, task_group, budget)
192
+ except (OSError, UnicodeError, JsonBoundaryError, DoyouknowError, StateError, KeyError, TypeError, ValueError, RecursionError) as exc:
193
+ raise TaskQueryError("source-unavailable") from exc
194
+
195
+
196
+ def _append_page_item(payload: dict, field: str, item: dict, cursor: str) -> bool:
197
+ trial = {**payload, field: [*payload[field], item], "truncated": True, "nextCursor": item["taskKey"]}
198
+ if len(json.dumps(trial, ensure_ascii=False).encode("utf-8")) > QUERY_OUTPUT_BYTES:
199
+ payload.update(truncated=True, nextCursor=cursor)
200
+ return False
201
+ payload[field].append(item)
202
+ return True
203
+
204
+
205
+ def _query_page(root: Path, project: str, entries: list[dict], catalog: list[dict], query: str,
206
+ origin: TaskDocument | None, after: str, limit: int, task_type: str,
207
+ latest_run_status: str, task_group: str, budget: ReadBudget) -> dict:
208
+ terms = query.casefold().split()
209
+ remaining = [entry for entry in entries if entry["taskKey"] > after]
210
+ payload = {"ok": True, "projectRoot": str(root), "tasks": [], "unavailable": [], "truncated": False, "nextCursor": None}
211
+ cursor = after
212
+ for inspected, entry in enumerate(remaining):
213
+ if inspected >= QUERY_PAGE_TASKS - int(origin is not None) or len(payload["tasks"]) >= limit:
214
+ payload.update(truncated=True, nextCursor=cursor)
215
+ break
216
+ key = entry["taskKey"]
217
+ if origin and key == origin.key:
218
+ cursor = key
219
+ continue
220
+ try:
221
+ document = _read_document(root, project, entry, catalog, budget)
222
+ except PageBudgetExhausted:
223
+ payload.update(truncated=True, nextCursor=cursor)
224
+ break
225
+ except (OSError, UnicodeError, JsonBoundaryError, DoyouknowError, StateError, TaskQueryError, KeyError, TypeError, RecursionError, ValueError):
226
+ if not _append_page_item(payload, "unavailable", {"taskKey": key, "reason": "source-unavailable"}, cursor):
227
+ break
228
+ cursor = key
229
+ continue
230
+ reasons = _relation_reasons(origin, document) if origin else []
231
+ folded = document.text.casefold()
232
+ matched = (not origin or (key != origin.key and bool(reasons))) and all(term in folded for term in terms)
233
+ selected = (not task_type or entry.get("taskType") == task_type) and (not latest_run_status or entry.get("latestRunStatus") == latest_run_status) and (not task_group or entry.get("taskGroup") == task_group)
234
+ if matched and selected:
235
+ result = _result(document, terms, reasons)
236
+ if not _append_page_item(payload, "tasks", result, cursor):
237
+ break
238
+ cursor = key
239
+ return payload
@@ -0,0 +1,264 @@
1
+ """Independent reviewer selection and verdict verification for implementation traces.
2
+
3
+ The TypeScript `okstra trace` command owns trace state. This module owns the two
4
+ facts it cannot check itself: which registered models may review a step, and
5
+ whether a reviewer's standalone completion is authentic, bound to the reviewed
6
+ section and carries a verdict.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import json
12
+ import re
13
+ import sys
14
+ from collections.abc import Sequence
15
+ from dataclasses import dataclass
16
+ from pathlib import Path
17
+
18
+ from .agent.invocation import AgentInvocationError, verify_standalone_completion
19
+ from .domain.host import HostNotRegistered
20
+ from .json_boundary import load_owned_object
21
+ from .model_pool import ModelPool
22
+ from .operation_invocation import (
23
+ OperationPreparationError,
24
+ operation_ceiling,
25
+ operation_contract_root,
26
+ resolve_operation_slots,
27
+ slot_payload,
28
+ )
29
+ from .registry.host_registry import default_host_registry
30
+ from .registry.provider_registry import default_provider_registry
31
+
32
+ PURPOSE = "trace-review"
33
+ STEP_OPERATIONS = {
34
+ "analysis-review": "trace-scope-review",
35
+ "spec-review": "trace-scope-review",
36
+ "interface-review": "trace-interface-review",
37
+ }
38
+ _DIGEST_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
39
+ _VERDICT_RE = re.compile(r"^Trace review verdict: (pass|fail)[ \t]*$", re.MULTILINE)
40
+ _ANY_VERDICT_RE = re.compile(r"^Trace review verdict:", re.MULTILINE)
41
+
42
+
43
+ class TraceReviewError(ValueError):
44
+ def __init__(self, code: str, message: str) -> None:
45
+ super().__init__(message)
46
+ self.code = code
47
+
48
+
49
+ @dataclass(frozen=True)
50
+ class ReviewTarget:
51
+ project_root: Path
52
+ trace_path: str
53
+ step: str
54
+ round: int
55
+ section_digest: str
56
+ host_runtime: str
57
+
58
+
59
+ @dataclass(frozen=True)
60
+ class ReviewerRecord:
61
+ invocation_id: str
62
+ provider: str
63
+ model: str
64
+ runner: str
65
+ duty_id: str
66
+ verdict: str
67
+
68
+ def to_payload(self) -> dict[str, str]:
69
+ """The `TraceReviewer` shape `okstra trace` validates and stores."""
70
+ return {
71
+ "invocationId": self.invocation_id, "provider": self.provider, "model": self.model,
72
+ "runner": self.runner, "dutyId": self.duty_id, "verdict": self.verdict,
73
+ }
74
+
75
+
76
+ def binding_text(target: ReviewTarget) -> str:
77
+ return "\n".join((
78
+ "Trace review binding",
79
+ f"- Trace: {target.trace_path}",
80
+ f"- Step: {target.step}",
81
+ f"- Round: {target.round}",
82
+ f"- Section digest: {target.section_digest}",
83
+ f"- Host runtime: {target.host_runtime}",
84
+ ))
85
+
86
+
87
+ def _operation(step: str) -> str:
88
+ operation = STEP_OPERATIONS.get(step)
89
+ if operation is None:
90
+ raise TraceReviewError("STEP_MISMATCH", f"Not a review step: {step}")
91
+ return operation
92
+
93
+
94
+ def _contract_root() -> Path:
95
+ try:
96
+ return operation_contract_root()
97
+ except OperationPreparationError as exc:
98
+ raise TraceReviewError("REVIEW_UNAVAILABLE", "operation contracts not found") from exc
99
+
100
+
101
+ def _native_provider(host_runtime: str) -> str:
102
+ try:
103
+ return default_host_registry().resolve(host_runtime).descriptor.native_provider_id
104
+ except HostNotRegistered as exc:
105
+ raise TraceReviewError("INVALID_ARGUMENT", f"unknown host runtime {host_runtime!r}: {exc}") from exc
106
+
107
+
108
+ def _ceiling(operation: str) -> int:
109
+ try:
110
+ return operation_ceiling(operation, contract_root=_contract_root())
111
+ except OperationPreparationError as exc:
112
+ raise TraceReviewError("REVIEW_UNAVAILABLE", str(exc)) from exc
113
+
114
+
115
+ def _independence(native: str, providers: Sequence[str]) -> str:
116
+ return "cross-provider" if any(provider != native for provider in providers) else "same-provider"
117
+
118
+
119
+ def plan_reviewers(target: ReviewTarget, count: int) -> dict[str, object]:
120
+ """Resolve reviewer slots, placing models from the host's own provider last."""
121
+ operation = _operation(target.step)
122
+ ceiling = _ceiling(operation)
123
+ if not 1 <= count <= ceiling:
124
+ raise TraceReviewError("INVALID_ARGUMENT", f"--count must be from 1 to {ceiling}, got {count}")
125
+ native = _native_provider(target.host_runtime)
126
+ try:
127
+ slots = resolve_operation_slots(
128
+ operation, contract_root=_contract_root(), pool=ModelPool.from_registry(default_provider_registry()),
129
+ count=count, deprioritized_provider=native,
130
+ )
131
+ except OperationPreparationError as exc:
132
+ raise TraceReviewError("REVIEW_UNAVAILABLE", str(exc)) from exc
133
+ return {
134
+ "operation": operation,
135
+ "dutyId": slots[0].duty_id,
136
+ "roleId": slots[0].role_id,
137
+ "binding": binding_text(target),
138
+ "independence": _independence(native, [slot.provider_id for slot in slots]),
139
+ "slots": [slot_payload(slot) for slot in slots],
140
+ }
141
+
142
+
143
+ def _verdict(body: str, invocation_id: str) -> str:
144
+ matches = _VERDICT_RE.findall(body)
145
+ if len(matches) != 1 or len(_ANY_VERDICT_RE.findall(body)) != 1:
146
+ raise TraceReviewError(
147
+ "REVIEW_REJECTED",
148
+ f"{invocation_id}: the returned body needs exactly one 'Trace review verdict: pass|fail' line",
149
+ )
150
+ return matches[0]
151
+
152
+
153
+ def _verify_completion(target: ReviewTarget, completion: Path, duty_id: str) -> ReviewerRecord:
154
+ try:
155
+ verified = verify_standalone_completion(completion, project_root=target.project_root, expected_purpose=PURPOSE)
156
+ metadata = load_owned_object(verified.prompt_metadata_path, artifact="agent invocation metadata")
157
+ except (AgentInvocationError, OSError, ValueError) as exc:
158
+ raise TraceReviewError("REVIEW_REJECTED", f"{completion}: {exc}") from exc
159
+ invocation_id = verified.invocation_id
160
+ if metadata.get("audience") != duty_id:
161
+ raise TraceReviewError(
162
+ "REVIEW_REJECTED",
163
+ f"{invocation_id}: reviewer duty {metadata.get('audience')!r} does not review {target.step} ({duty_id})",
164
+ )
165
+ assignment = metadata.get("modelAssignment")
166
+ if not isinstance(assignment, dict):
167
+ raise TraceReviewError("REVIEW_REJECTED", f"{invocation_id}: model assignment is missing")
168
+ if assignment.get("hostRuntime") != target.host_runtime:
169
+ raise TraceReviewError(
170
+ "REVIEW_REJECTED",
171
+ f"{invocation_id}: reviewer host runtime {assignment.get('hostRuntime')!r} differs from {target.host_runtime!r}",
172
+ )
173
+ prompt = verified.prompt_metadata_path.with_name(f"{invocation_id}.prompt.md").read_text(encoding="utf-8")
174
+ if binding_text(target) not in prompt:
175
+ raise TraceReviewError(
176
+ "REVIEW_STALE",
177
+ f"{invocation_id}: the prompt lacks the current binding; the trace, step, round, section content or host differs, or the binding was not copied verbatim",
178
+ )
179
+ return ReviewerRecord(
180
+ invocation_id=invocation_id,
181
+ provider=str(assignment.get("provider", "")),
182
+ model=str(assignment.get("model", "")),
183
+ runner=str(assignment.get("runner", "")),
184
+ duty_id=duty_id,
185
+ verdict=_verdict(verified.returned_body, invocation_id),
186
+ )
187
+
188
+
189
+ def _require_independent(native: str, role_id: str, reviewers: Sequence[ReviewerRecord]) -> None:
190
+ pool = ModelPool.from_registry(default_provider_registry())
191
+ if _independence(native, [row.provider for row in reviewers]) == "same-provider" and any(
192
+ model.provider_id != native for model in pool.default_candidates(role_id)
193
+ ):
194
+ raise TraceReviewError(
195
+ "REVIEWER_NOT_INDEPENDENT",
196
+ f"a model outside provider {native!r} is registered for role {role_id!r}; at least one reviewer must use it",
197
+ )
198
+
199
+
200
+ def verify_reviews(target: ReviewTarget, completions: Sequence[Path]) -> dict[str, object]:
201
+ """Authenticate each completion and derive the combined verdict."""
202
+ operation = _operation(target.step)
203
+ if not _DIGEST_RE.fullmatch(target.section_digest) or target.round < 1:
204
+ raise TraceReviewError("INVALID_ARGUMENT", "section digest or round is invalid")
205
+ if not completions:
206
+ raise TraceReviewError("REVIEW_REQUIRED", "supply at least one reviewer completion")
207
+ ceiling = _ceiling(operation)
208
+ if len(completions) > ceiling:
209
+ raise TraceReviewError("INVALID_ARGUMENT", f"{operation} allows at most {ceiling} reviewer completions")
210
+ native = _native_provider(target.host_runtime)
211
+ try:
212
+ slot = resolve_operation_slots(
213
+ operation, contract_root=_contract_root(), pool=ModelPool.from_registry(default_provider_registry()), count=1,
214
+ )[0]
215
+ except OperationPreparationError as exc:
216
+ raise TraceReviewError("REVIEW_UNAVAILABLE", str(exc)) from exc
217
+ reviewers: list[ReviewerRecord] = []
218
+ for completion in completions:
219
+ record = _verify_completion(target, completion, slot.duty_id)
220
+ if any(row.invocation_id == record.invocation_id for row in reviewers):
221
+ raise TraceReviewError("REVIEW_REJECTED", f"{record.invocation_id}: completion supplied twice")
222
+ reviewers.append(record)
223
+ _require_independent(native, slot.role_id, reviewers)
224
+ return {
225
+ "verdict": "pass" if all(row.verdict == "pass" for row in reviewers) else "fail",
226
+ "independence": _independence(native, [row.provider for row in reviewers]),
227
+ "reviewers": [row.to_payload() for row in reviewers],
228
+ }
229
+
230
+
231
+ def _target(args: argparse.Namespace) -> ReviewTarget:
232
+ return ReviewTarget(
233
+ Path(args.project_root).resolve(), args.trace_path, args.step, args.round, args.section_digest, args.host_runtime,
234
+ )
235
+
236
+
237
+ def main(argv: Sequence[str] | None = None) -> int:
238
+ parser = argparse.ArgumentParser(prog="okstra_ctl.trace_review")
239
+ commands = parser.add_subparsers(dest="command", required=True)
240
+ for name in ("plan", "verify"):
241
+ command = commands.add_parser(name)
242
+ command.add_argument("--project-root", required=True)
243
+ command.add_argument("--trace-path", required=True)
244
+ command.add_argument("--step", required=True)
245
+ command.add_argument("--round", required=True, type=int)
246
+ command.add_argument("--section-digest", required=True)
247
+ command.add_argument("--host-runtime", required=True)
248
+ commands.choices["plan"].add_argument("--count", type=int, default=1)
249
+ commands.choices["verify"].add_argument("--completion", action="append", default=[])
250
+ args = parser.parse_args(argv)
251
+ try:
252
+ if args.command == "plan":
253
+ result = plan_reviewers(_target(args), args.count)
254
+ else:
255
+ result = verify_reviews(_target(args), [Path(path) for path in args.completion])
256
+ except TraceReviewError as exc:
257
+ print(json.dumps({"error": {"code": exc.code, "message": str(exc)}}))
258
+ return 1
259
+ print(json.dumps(result))
260
+ return 0
261
+
262
+
263
+ if __name__ == "__main__":
264
+ sys.exit(main())