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.
- package/README.md +19 -283
- package/dist/cli-registry.mjs +14 -1
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/render-bundle.d.mts +6 -1
- package/dist/commands/execute/render-bundle.mjs +139 -32
- package/dist/commands/execute/render-bundle.mjs.map +1 -1
- package/dist/commands/lifecycle/config.mjs +6 -74
- package/dist/commands/lifecycle/config.mjs.map +1 -1
- package/dist/commands/trace/capacity.d.mts +12 -0
- package/dist/commands/trace/capacity.mjs +21 -0
- package/dist/commands/trace/capacity.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +89 -0
- package/dist/commands/trace/model.mjs +251 -0
- package/dist/commands/trace/model.mjs.map +1 -0
- package/dist/commands/trace/progression.d.mts +11 -0
- package/dist/commands/trace/progression.mjs +194 -0
- package/dist/commands/trace/progression.mjs.map +1 -0
- package/dist/commands/trace/review.d.mts +7 -0
- package/dist/commands/trace/review.mjs +51 -0
- package/dist/commands/trace/review.mjs.map +1 -0
- package/dist/commands/trace/task-link.d.mts +18 -0
- package/dist/commands/trace/task-link.mjs +72 -0
- package/dist/commands/trace/task-link.mjs.map +1 -0
- package/dist/commands/trace/trace.d.mts +1 -0
- package/dist/commands/trace/trace.mjs +293 -0
- package/dist/commands/trace/trace.mjs.map +1 -0
- package/dist/lib/bounded-file.d.mts +1 -0
- package/dist/lib/bounded-file.mjs +36 -0
- package/dist/lib/bounded-file.mjs.map +1 -0
- package/dist/lib/config-store.d.mts +34 -0
- package/dist/lib/config-store.mjs +70 -0
- package/dist/lib/config-store.mjs.map +1 -0
- package/dist/lib/file-lock.mjs +4 -5
- package/dist/lib/file-lock.mjs.map +1 -1
- package/dist/lib/input-limit.d.mts +4 -0
- package/dist/lib/input-limit.mjs +8 -0
- package/dist/lib/input-limit.mjs.map +1 -0
- package/dist/lib/memory-auto-register.mjs +2 -17
- package/dist/lib/memory-auto-register.mjs.map +1 -1
- package/dist/lib/report-language-tag.d.mts +1 -0
- package/dist/lib/report-language-tag.mjs +4 -0
- package/dist/lib/report-language-tag.mjs.map +1 -0
- package/dist/lib/report-language.d.mts +1 -0
- package/dist/lib/report-language.mjs +50 -0
- package/dist/lib/report-language.mjs.map +1 -0
- package/dist/lib/skill-catalog.mjs +3 -0
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/docs/architecture/storage-model.md +55 -5
- package/docs/architecture.md +10 -4
- package/docs/cli.md +320 -3
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +34 -43
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/trace-interface-review.json +6 -0
- package/runtime/agents/operations/trace-scope-review.json +6 -0
- package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
- package/runtime/prompts/coding-preflight/clean-code.md +18 -20
- package/runtime/prompts/coding-preflight/overview.md +1 -1
- package/runtime/prompts/duties/code-reviewer.json +1 -1
- package/runtime/prompts/duties/interface-reviewer.json +32 -0
- package/runtime/prompts/host-orchestration/README.md +18 -9
- package/runtime/prompts/launch.template.md +3 -2
- package/runtime/prompts/lead/context-loader.md +2 -0
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +6 -6
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
- package/runtime/prompts/profiles/_common-contract.md +1 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
- package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
- package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
- package/runtime/python/okstra_ctl/business_flow/cli.py +60 -6
- package/runtime/python/okstra_ctl/business_flow/contracts.py +12 -1
- package/runtime/python/okstra_ctl/business_flow/engine.py +17 -5
- package/runtime/python/okstra_ctl/business_flow/history.py +60 -0
- package/runtime/python/okstra_ctl/business_flow/source.py +35 -2
- package/runtime/python/okstra_ctl/business_flow/store.py +51 -14
- package/runtime/python/okstra_ctl/business_flow/sweep.py +124 -0
- package/runtime/python/okstra_ctl/code_review_census.py +93 -2
- package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
- package/runtime/python/okstra_ctl/code_review_run.py +384 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
- package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
- package/runtime/python/okstra_ctl/code_review_target.py +140 -15
- package/runtime/python/okstra_ctl/coverage_census.py +11 -2
- package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
- package/runtime/python/okstra_ctl/direct_work.py +45 -3
- package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
- package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +9 -9
- package/runtime/python/okstra_ctl/doyouknow/config.py +2 -2
- package/runtime/python/okstra_ctl/doyouknow/group_view.py +152 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +4 -3
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +2 -2
- package/runtime/python/okstra_ctl/doyouknow/sources/business.py +116 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
- package/runtime/python/okstra_ctl/doyouknow/sync.py +34 -9
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/fixed_text.py +10 -0
- package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
- package/runtime/python/okstra_ctl/json_boundary.py +33 -6
- package/runtime/python/okstra_ctl/manager_cli.py +122 -1
- package/runtime/python/okstra_ctl/manager_journal.py +126 -0
- package/runtime/python/okstra_ctl/manager_launch.py +3 -3
- package/runtime/python/okstra_ctl/manager_log.py +221 -0
- package/runtime/python/okstra_ctl/manager_paths.py +8 -0
- package/runtime/python/okstra_ctl/manager_resume.py +59 -0
- package/runtime/python/okstra_ctl/manager_split.py +2 -2
- package/runtime/python/okstra_ctl/manager_store.py +116 -17
- package/runtime/python/okstra_ctl/manager_sync.py +42 -3
- package/runtime/python/okstra_ctl/manager_view.py +35 -2
- package/runtime/python/okstra_ctl/material.py +2 -0
- package/runtime/python/okstra_ctl/model_cli.py +64 -14
- package/runtime/python/okstra_ctl/model_defaults.py +22 -0
- package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
- package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
- package/runtime/python/okstra_ctl/path_hints.py +14 -3
- package/runtime/python/okstra_ctl/paths.py +6 -1
- package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
- package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
- package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
- package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
- package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
- package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
- package/runtime/python/okstra_ctl/project_group.py +175 -0
- package/runtime/python/okstra_ctl/project_group_cli.py +62 -0
- package/runtime/python/okstra_ctl/render.py +28 -2
- package/runtime/python/okstra_ctl/report_assembly.py +38 -11
- package/runtime/python/okstra_ctl/report_contract.py +26 -0
- package/runtime/python/okstra_ctl/report_corrections.py +36 -20
- package/runtime/python/okstra_ctl/report_inputs.py +1 -0
- package/runtime/python/okstra_ctl/report_language.py +4 -1
- package/runtime/python/okstra_ctl/report_narrative.py +179 -7
- package/runtime/python/okstra_ctl/report_projections.py +64 -18
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
- package/runtime/python/okstra_ctl/run.py +43 -35
- package/runtime/python/okstra_ctl/run_context.py +10 -1
- package/runtime/python/okstra_ctl/set_work_status.py +4 -15
- package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
- package/runtime/python/okstra_ctl/task_query.py +239 -0
- package/runtime/python/okstra_ctl/trace_review.py +264 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
- package/runtime/python/okstra_ctl/user_authorization.py +14 -0
- package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
- package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
- package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
- package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
- package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
- package/runtime/python/okstra_ctl/wizard/render.py +8 -0
- package/runtime/python/okstra_ctl/wizard/state.py +2 -1
- package/runtime/python/okstra_project/state.py +20 -0
- package/runtime/python/okstra_token_usage/blocks.py +74 -0
- package/runtime/python/okstra_token_usage/cli.py +23 -10
- package/runtime/python/okstra_token_usage/collect.py +25 -22
- package/runtime/python/okstra_token_usage/policy.py +193 -0
- package/runtime/schemas/business-flow-v1.schema.json +3 -0
- package/runtime/schemas/doyouknow-config-v1.schema.json +1 -1
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
- package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
- package/runtime/skills/_fragments/wizard-preflight.md +1 -1
- package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
- package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
- package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
- package/runtime/skills/okstra-code-review/SKILL.md +58 -50
- package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
- package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
- package/runtime/skills/okstra-discussion/SKILL.md +22 -38
- package/runtime/skills/okstra-explain-flow/SKILL.md +33 -4
- package/runtime/skills/okstra-manager/SKILL.md +24 -0
- package/runtime/skills/okstra-memory/SKILL.md +1 -1
- package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +55 -183
- package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
- package/runtime/skills/okstra-setup/SKILL.md +3 -2
- package/runtime/skills/okstra-setup/references/project-config.md +2 -4
- package/runtime/skills/okstra-tdd/SKILL.md +187 -0
- package/runtime/skills/okstra-user-response/SKILL.md +4 -2
- package/runtime/templates/doyouknow/group-view.css +103 -0
- package/runtime/templates/doyouknow/group-view.js +317 -0
- package/runtime/templates/doyouknow/group-view.template.html +72 -0
- package/runtime/templates/manager/view.template.html +4 -0
- package/runtime/templates/report-writer-prompt-preamble.md +15 -3
- package/runtime/templates/trace/trace.template.md +42 -0
- package/runtime/validators/checks/fixtures-02.py +25 -33
- 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())
|