okstra 0.231.0 → 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.
- package/README.md +15 -3
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.mjs.map +1 -1
- package/dist/lib/memory-auto-register.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +113 -0
- package/dist/lib/memory-auto-register.mjs.map +1 -0
- package/dist/lib/memory-entry-contract.d.mts +12 -0
- package/dist/lib/memory-entry-contract.mjs +46 -0
- package/dist/lib/memory-entry-contract.mjs.map +1 -0
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +3 -2
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/record-secrets.d.mts +1 -0
- package/dist/lib/record-secrets.mjs +28 -0
- package/dist/lib/record-secrets.mjs.map +1 -0
- package/dist/lib/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +129 -2
- package/docs/architecture.md +11 -2
- package/docs/cli.md +234 -0
- package/docs/project-structure-overview.md +2 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- package/runtime/agents/roles/verifier.json +2 -4
- package/runtime/bin/okstra-provider-exec.py +10 -4
- package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
- package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
- package/runtime/prompts/coding-preflight/clean-code.md +85 -281
- package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
- package/runtime/prompts/coding-preflight/languages/java.md +3 -5
- package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
- package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
- package/runtime/prompts/coding-preflight/languages/python.md +2 -7
- package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
- package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
- package/runtime/prompts/coding-preflight/overview.md +25 -38
- package/runtime/prompts/coding-preflight/review-rules.json +30 -0
- package/runtime/prompts/duties/code-reviewer.json +15 -18
- package/runtime/prompts/duties/implementation-verifier.json +1 -0
- package/runtime/prompts/lead/convergence.md +3 -3
- package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
- package/runtime/prompts/lead/report-writer.md +1 -1
- package/runtime/prompts/lead/team-contract.md +1 -1
- package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
- package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
- package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
- package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
- package/runtime/python/okstra_ctl/code_review_census.py +71 -7
- package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
- package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
- package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
- package/runtime/python/okstra_ctl/code_review_target.py +85 -11
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/convergence.py +112 -20
- package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
- package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
- package/runtime/python/okstra_ctl/correction_round.py +6 -1
- package/runtime/python/okstra_ctl/design_review.py +207 -0
- package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
- package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
- package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
- package/runtime/python/okstra_ctl/doctor.py +8 -25
- package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
- package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
- package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
- package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
- package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
- package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
- package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
- package/runtime/python/okstra_ctl/json_boundary.py +21 -2
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +26 -0
- package/runtime/python/okstra_ctl/manager_registration.py +29 -0
- package/runtime/python/okstra_ctl/manager_sync.py +3 -22
- package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +12 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +39 -11
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/report_assembly.py +15 -0
- package/runtime/python/okstra_ctl/report_narrative.py +3 -0
- package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -2
- package/runtime/python/okstra_ctl/review_policy.py +359 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
- package/runtime/python/okstra_ctl/run.py +24 -1
- package/runtime/python/okstra_ctl/stage_done.py +11 -0
- package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
- package/runtime/python/okstra_ctl/team.py +3 -1
- package/runtime/python/okstra_ctl/verification_generation.py +23 -1
- package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
- package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
- package/runtime/python/okstra_ctl/verification_target.py +2 -0
- package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
- package/runtime/python/okstra_ctl/write_policy.py +34 -1
- package/runtime/python/okstra_project/__init__.py +2 -0
- package/runtime/python/okstra_project/dirs.py +18 -0
- package/runtime/python/okstra_project/state.py +25 -20
- package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
- package/runtime/schemas/doyouknow-v1.schema.json +65 -0
- package/runtime/schemas/final-report-v2.0.schema.json +157 -0
- package/runtime/schemas/final-report-v3.0.schema.json +157 -0
- package/runtime/schemas/memory-entry-contract-v1.json +11 -0
- package/runtime/schemas/record-secret-patterns.json +41 -0
- package/runtime/skills/okstra-code-review/SKILL.md +71 -123
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
- package/runtime/skills/okstra-manager/SKILL.md +7 -0
- package/runtime/skills/okstra-memory/SKILL.md +7 -0
- package/runtime/templates/implementation-worker-preamble.md +4 -9
- package/runtime/templates/worker-prompt-preamble.md +4 -12
- package/runtime/validators/validate-run.py +17 -8
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
"""Bind standalone reviews to selected frozen rules and source integrity."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from dataclasses import dataclass, replace
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import TYPE_CHECKING, Mapping
|
|
7
|
+
|
|
8
|
+
from .json_boundary import load_owned_object, load_owned_object_snapshot
|
|
9
|
+
from .qa_procedures import content_digest
|
|
10
|
+
from .review_policy import (
|
|
11
|
+
code_review_guidance_paths,
|
|
12
|
+
review_policy_context,
|
|
13
|
+
render_review_rule_catalog,
|
|
14
|
+
render_selected_review_policy,
|
|
15
|
+
review_policy_errors,
|
|
16
|
+
select_review_policy,
|
|
17
|
+
)
|
|
18
|
+
from .review_verdicts import _head_tree, parse_review_census
|
|
19
|
+
|
|
20
|
+
if TYPE_CHECKING:
|
|
21
|
+
from .agent.invocation import AgentInvocationRequest
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
@dataclass(frozen=True)
|
|
25
|
+
class CodeReviewInputs:
|
|
26
|
+
policy_path: Path
|
|
27
|
+
census_path: Path
|
|
28
|
+
base: str
|
|
29
|
+
head: str
|
|
30
|
+
resources: tuple[str, ...] = ()
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _validate_census_binding(text: str, inputs: CodeReviewInputs, digest: str) -> None:
|
|
34
|
+
digest_lines = [line for line in text.splitlines() if line.startswith("Review policy digest: ")]
|
|
35
|
+
expected = "Review policy digest: " + digest
|
|
36
|
+
if digest_lines != [expected]:
|
|
37
|
+
raise ValueError("assigned census and shared review policy digest differ")
|
|
38
|
+
resource_lines = [line.removeprefix("Review resources: ").strip()
|
|
39
|
+
for line in text.splitlines() if line.startswith("Review resources: ")]
|
|
40
|
+
if len(resource_lines) != 1:
|
|
41
|
+
raise ValueError("assigned census requires one explicit resource selection")
|
|
42
|
+
declared = [] if resource_lines == ["-"] else [part.strip() for part in resource_lines[0].split(";")]
|
|
43
|
+
if len(set(declared)) != len(declared) or sorted(declared) != sorted(inputs.resources):
|
|
44
|
+
raise ValueError("review resource selection differs from the assigned census")
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _review_payload(request: AgentInvocationRequest) -> dict:
|
|
48
|
+
inputs = request.review_inputs
|
|
49
|
+
if inputs is None:
|
|
50
|
+
raise ValueError("standalone code review requires frozen policy, census, base and head")
|
|
51
|
+
root = request.project_root.resolve()
|
|
52
|
+
for path in (inputs.policy_path, inputs.census_path):
|
|
53
|
+
path.resolve(strict=True).relative_to(root)
|
|
54
|
+
tree = _head_tree(root, inputs.head)
|
|
55
|
+
base = _head_tree(root, inputs.base).commit
|
|
56
|
+
if tree._git("merge-base", "--is-ancestor", base, tree.commit).returncode:
|
|
57
|
+
raise ValueError("review base is not an ancestor of head")
|
|
58
|
+
census_text = inputs.census_path.read_text(encoding="utf-8")
|
|
59
|
+
stored_policy = load_owned_object_snapshot(
|
|
60
|
+
inputs.policy_path, artifact="shared frozen review policy",
|
|
61
|
+
schema={"type": "object"}, validate_cross_fields=review_policy_errors,
|
|
62
|
+
)
|
|
63
|
+
_validate_census_binding(census_text, inputs, content_digest(stored_policy.raw_bytes))
|
|
64
|
+
census = parse_review_census(census_text)
|
|
65
|
+
targets = tuple(dict.fromkeys(cell.target.partition(":")[0] for cell in census.cells.values()))
|
|
66
|
+
paths, manifests = review_policy_context(root, tree.commit, targets, base=base)
|
|
67
|
+
for target in targets:
|
|
68
|
+
exists_at_head = tree._git("cat-file", "-e", f"{tree.commit}:{target}").returncode == 0
|
|
69
|
+
(tree if exists_at_head else _head_tree(root, base)).line_count(target)
|
|
70
|
+
policy = stored_policy.value
|
|
71
|
+
guidance = code_review_guidance_paths(policy)
|
|
72
|
+
if len(guidance) != 3:
|
|
73
|
+
raise ValueError("frozen code-review protocol guidance is incomplete")
|
|
74
|
+
selected = select_review_policy(
|
|
75
|
+
policy, targets, project_paths=paths, manifest_contents=manifests,
|
|
76
|
+
guidance_paths=guidance,
|
|
77
|
+
resources=inputs.resources,
|
|
78
|
+
)
|
|
79
|
+
canonical = parse_review_census(
|
|
80
|
+
render_review_rule_catalog(selected) + "\n## Cells\n", allow_empty=True,
|
|
81
|
+
)
|
|
82
|
+
for group, rules in census.rules.items():
|
|
83
|
+
for rule in rules:
|
|
84
|
+
references = [part.strip() for part in census.references[rule].split(";")]
|
|
85
|
+
if (rule not in canonical.rules.get(group, ())
|
|
86
|
+
or canonical.references[rule] not in references):
|
|
87
|
+
raise ValueError(f"assigned census weakens the frozen rule catalog: {rule}")
|
|
88
|
+
return {"schemaVersion": 1, "base": base, "head": tree.commit,
|
|
89
|
+
"census": census_text, "policy": selected}
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def bind_review_invocation(request: AgentInvocationRequest) -> AgentInvocationRequest:
|
|
93
|
+
from .agent.invocation import (
|
|
94
|
+
AgentInstructionSource, AgentInvocationError, _canonical_json, _publish_or_reuse_exact,
|
|
95
|
+
)
|
|
96
|
+
if request.run_manifest_path is not None or request.audience != "code-reviewer":
|
|
97
|
+
if request.review_inputs is not None:
|
|
98
|
+
raise AgentInvocationError("frozen code-review inputs require a standalone code reviewer")
|
|
99
|
+
return request
|
|
100
|
+
if request.purpose != "code-review":
|
|
101
|
+
raise AgentInvocationError("code reviewer requires purpose code-review")
|
|
102
|
+
from .code_review_integrity import capture_review_source
|
|
103
|
+
|
|
104
|
+
try:
|
|
105
|
+
payload = _review_payload(request)
|
|
106
|
+
root = request.project_root.resolve()
|
|
107
|
+
policy_path = request.prompt_path.parent / f"{request.invocation_id}.review-policy.json"
|
|
108
|
+
metadata = {"invocationId": request.invocation_id, "audience": request.audience,
|
|
109
|
+
"contractSource": {"dutyRootPath": request.duty_root.resolve().relative_to(root).as_posix()},
|
|
110
|
+
"instruction": {"sourcePaths": [{"kind": row.kind, "path": row.path}
|
|
111
|
+
for row in request.instruction.source_paths]}}
|
|
112
|
+
baseline_path, baseline_digest = capture_review_source(
|
|
113
|
+
root, request.prompt_path, request.metadata_path, metadata,
|
|
114
|
+
)
|
|
115
|
+
payload.update(sourceSnapshotPath=baseline_path, sourceSnapshotDigest=baseline_digest)
|
|
116
|
+
raw = _canonical_json(payload)
|
|
117
|
+
_publish_or_reuse_exact(policy_path, raw)
|
|
118
|
+
relative = policy_path.resolve().relative_to(root).as_posix()
|
|
119
|
+
supplement = (
|
|
120
|
+
"\n\n## Frozen code-review inputs\n\n"
|
|
121
|
+
f"Frozen code-review policy: {relative}\n"
|
|
122
|
+
f"Frozen code-review policy digest: {content_digest(raw)}\n"
|
|
123
|
+
f"Frozen source base: {payload['base']}\nFrozen source head: {payload['head']}\n"
|
|
124
|
+
"Apply the captured rule bodies below. Source paths identify provenance; "
|
|
125
|
+
"do not replace these bodies with live installed files.\n"
|
|
126
|
+
+ render_selected_review_policy(payload["policy"])
|
|
127
|
+
+ "\n## Assigned review census\n\n" + payload["census"]
|
|
128
|
+
)
|
|
129
|
+
instruction = replace(
|
|
130
|
+
request.instruction, body=request.instruction.body.rstrip() + supplement,
|
|
131
|
+
source_paths=(*request.instruction.source_paths,
|
|
132
|
+
AgentInstructionSource("project", relative),
|
|
133
|
+
AgentInstructionSource("project", baseline_path)),
|
|
134
|
+
)
|
|
135
|
+
return replace(request, instruction=instruction)
|
|
136
|
+
except (OSError, ValueError, KeyError) as exc:
|
|
137
|
+
raise AgentInvocationError(f"cannot bind frozen code-review inputs: {exc}") from exc
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def review_policy_path(project: Path, metadata: Mapping) -> Path | None:
|
|
141
|
+
identity = metadata["invocationId"]
|
|
142
|
+
relative = f".okstra/agent-invocations/code-review/{identity}.review-policy.json"
|
|
143
|
+
sources = metadata["instruction"]["sourcePaths"]
|
|
144
|
+
if not any(row["kind"] == "project" and row["path"] == relative for row in sources):
|
|
145
|
+
return None
|
|
146
|
+
if metadata["audience"] != "code-reviewer" or metadata["contractSource"]["mode"] != "standalone":
|
|
147
|
+
raise ValueError("frozen code-review policy is bound to the wrong invocation")
|
|
148
|
+
return project / relative
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def read_invocation_review_policy(project: Path, metadata: Mapping) -> dict | None:
|
|
152
|
+
path = review_policy_path(project, metadata)
|
|
153
|
+
if path is None:
|
|
154
|
+
return None
|
|
155
|
+
payload = load_owned_object(path, artifact="invocation frozen review policy")
|
|
156
|
+
fields = {"schemaVersion", "base", "head", "census", "policy",
|
|
157
|
+
"sourceSnapshotPath", "sourceSnapshotDigest"}
|
|
158
|
+
if (set(payload) != fields or payload["schemaVersion"] != 1
|
|
159
|
+
or review_policy_errors(payload["policy"])):
|
|
160
|
+
raise ValueError("invocation frozen review policy is invalid")
|
|
161
|
+
expected = path.with_name(f"{metadata['invocationId']}.review-source.json").relative_to(project).as_posix()
|
|
162
|
+
if payload["sourceSnapshotPath"] != expected:
|
|
163
|
+
raise ValueError("review source snapshot path is not canonical")
|
|
164
|
+
raw = (project / expected).read_bytes()
|
|
165
|
+
if content_digest(raw) != payload["sourceSnapshotDigest"]:
|
|
166
|
+
raise ValueError("review source snapshot digest changed")
|
|
167
|
+
return payload
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def review_policy_errors_for_prompt(project: Path, metadata: Mapping, prompt: bytes) -> list[str]:
|
|
171
|
+
try:
|
|
172
|
+
path = review_policy_path(project, metadata)
|
|
173
|
+
if path is None:
|
|
174
|
+
return []
|
|
175
|
+
read_invocation_review_policy(project, metadata)
|
|
176
|
+
line = f"Frozen code-review policy digest: {content_digest(path.read_bytes())}"
|
|
177
|
+
if prompt.decode("utf-8").splitlines().count(line) != 1:
|
|
178
|
+
return ["frozen code-review policy differs from the prompt"]
|
|
179
|
+
except (OSError, ValueError, KeyError) as exc:
|
|
180
|
+
return [f"frozen code-review inputs are invalid: {exc}"]
|
|
181
|
+
return []
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
def complete_review_audit(project: Path, metadata_path: Path, metadata: Mapping) -> str | None:
|
|
185
|
+
from .code_review_integrity import finalize_review_integrity
|
|
186
|
+
|
|
187
|
+
payload = read_invocation_review_policy(project, metadata)
|
|
188
|
+
if payload is None:
|
|
189
|
+
return None
|
|
190
|
+
return finalize_review_integrity(
|
|
191
|
+
project, metadata_path, metadata,
|
|
192
|
+
payload["sourceSnapshotPath"], payload["sourceSnapshotDigest"],
|
|
193
|
+
)
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def verify_review_completion(
|
|
197
|
+
project: Path, metadata_path: Path, metadata: Mapping, completion: Mapping,
|
|
198
|
+
) -> None:
|
|
199
|
+
from .code_review_integrity import verify_review_integrity
|
|
200
|
+
|
|
201
|
+
payload = read_invocation_review_policy(project, metadata)
|
|
202
|
+
if payload is None:
|
|
203
|
+
if completion["schemaVersion"] != 1:
|
|
204
|
+
raise ValueError("unexpected review integrity completion")
|
|
205
|
+
return
|
|
206
|
+
if completion["schemaVersion"] != 2:
|
|
207
|
+
raise ValueError("frozen code review requires integrity-bound completion")
|
|
208
|
+
verify_review_integrity(
|
|
209
|
+
project, metadata_path, metadata,
|
|
210
|
+
payload["sourceSnapshotPath"], payload["sourceSnapshotDigest"],
|
|
211
|
+
completion["reviewAuditDigest"],
|
|
212
|
+
)
|
|
@@ -5,13 +5,17 @@ import hashlib
|
|
|
5
5
|
import re
|
|
6
6
|
from dataclasses import dataclass
|
|
7
7
|
from pathlib import Path, PurePosixPath
|
|
8
|
+
from collections.abc import Sequence
|
|
8
9
|
|
|
9
10
|
from .agent.invocation import verify_standalone_completion
|
|
10
11
|
from .fixed_text import scalar
|
|
11
|
-
from .code_review_coverage import
|
|
12
|
-
|
|
13
|
-
read_review_census,
|
|
12
|
+
from .code_review_coverage import check_review_coverage
|
|
13
|
+
from .review_verdicts import (
|
|
14
|
+
ReviewCensus, _HeadTree, _head_tree, _table_fields, read_review_census,
|
|
14
15
|
)
|
|
16
|
+
from .verification_input_types import FrozenReviewPolicy
|
|
17
|
+
from .qa_procedures import canonical_json_digest
|
|
18
|
+
from .review_policy import select_review_policy
|
|
15
19
|
|
|
16
20
|
|
|
17
21
|
@dataclass(frozen=True)
|
|
@@ -30,21 +34,35 @@ class ReviewScope:
|
|
|
30
34
|
)
|
|
31
35
|
|
|
32
36
|
|
|
33
|
-
def _rule_digest(
|
|
37
|
+
def _rule_digest(
|
|
38
|
+
census: ReviewCensus, policies: list[Path], policy: FrozenReviewPolicy | None = None,
|
|
39
|
+
resources: Sequence[str] = (),
|
|
40
|
+
) -> str:
|
|
34
41
|
digest = hashlib.sha256()
|
|
35
42
|
values = [repr(census.rules), repr(census.references)]
|
|
43
|
+
if resources:
|
|
44
|
+
values.append(repr(tuple(resources)))
|
|
45
|
+
if policy is not None:
|
|
46
|
+
values.append(canonical_json_digest(policy))
|
|
36
47
|
for reference in census.references.values():
|
|
37
48
|
for location in reference.split(";"):
|
|
38
49
|
name = re.sub(r":\d+(?:-\d+)?$", "", location.strip().partition("#")[0])
|
|
39
|
-
values.append(
|
|
40
|
-
|
|
41
|
-
)
|
|
42
|
-
values.extend(hashlib.sha256(path.read_bytes()).hexdigest() for path in policies)
|
|
50
|
+
values.append(_policy_source_digest(Path(name).expanduser(), policy))
|
|
51
|
+
values.extend(_policy_source_digest(path, policy) for path in policies)
|
|
43
52
|
for value in values:
|
|
44
53
|
digest.update(value.encode() + b"\0")
|
|
45
54
|
return digest.hexdigest()
|
|
46
55
|
|
|
47
56
|
|
|
57
|
+
def _policy_source_digest(path: Path, policy: FrozenReviewPolicy | None) -> str:
|
|
58
|
+
if policy is None:
|
|
59
|
+
return hashlib.sha256(path.read_bytes()).hexdigest()
|
|
60
|
+
source = policy["sources"].get(str(path.absolute()))
|
|
61
|
+
if source is None:
|
|
62
|
+
raise ValueError(f"review reference was not captured in the frozen policy: {path}")
|
|
63
|
+
return source["digest"]
|
|
64
|
+
|
|
65
|
+
|
|
48
66
|
def _dependencies(body: str, census: ReviewCensus) -> dict[str, set[str]]:
|
|
49
67
|
dependencies: dict[str, set[str]] = {}
|
|
50
68
|
section = ""
|
|
@@ -86,13 +104,22 @@ def review_scope(
|
|
|
86
104
|
root: Path, census_path: Path, base: str, head: str, policies: list[Path], *,
|
|
87
105
|
previous_head: str = "", previous_census: Path | None = None,
|
|
88
106
|
completions: list[Path] | None = None,
|
|
107
|
+
policy: FrozenReviewPolicy | None = None,
|
|
89
108
|
) -> ReviewScope:
|
|
90
109
|
census = read_review_census(census_path)
|
|
110
|
+
selections = [line.removeprefix("Review resources: ")
|
|
111
|
+
for line in census_path.read_text(encoding="utf-8").splitlines()
|
|
112
|
+
if line.startswith("Review resources: ")]
|
|
113
|
+
if len(selections) > 1:
|
|
114
|
+
raise ValueError("review census repeats its resource selection")
|
|
115
|
+
resources = tuple(part.strip() for part in selections[0].split(";")) if selections and selections[0] != "-" else ()
|
|
116
|
+
if policy is not None:
|
|
117
|
+
select_review_policy(policy, resources=resources)
|
|
91
118
|
current = _head_tree(root, head)
|
|
92
119
|
base_commit = _head_tree(root, base).commit
|
|
93
120
|
if current._git("merge-base", "--is-ancestor", base_commit, current.commit).returncode:
|
|
94
121
|
raise ValueError("review base is not an ancestor of head")
|
|
95
|
-
rules = _rule_digest(census, policies)
|
|
122
|
+
rules = _rule_digest(census, policies, policy, resources)
|
|
96
123
|
baseline = (
|
|
97
124
|
f"Review base: {base_commit}\nReview head: {current.commit}\n"
|
|
98
125
|
f"Review rules: {rules}\n"
|
|
@@ -93,7 +93,8 @@ _CLI_EPILOG = r"""Usage:
|
|
|
93
93
|
okstra code-review target --task-key <k> --stage <N> [--base <ref>] [--project-root <dir>] [--cwd <dir>] --json
|
|
94
94
|
okstra code-review target --branch <name> --base <ref> [--date <YYYY-MM-DD>] [--project-root <dir>] --json
|
|
95
95
|
okstra code-review check-coverage --head <ref> [--base <ref>] --census <table-path> --completion <completion-path> [--completion ...] [--project-root <dir>]
|
|
96
|
-
okstra code-review
|
|
96
|
+
okstra code-review census --base <ref> --head <ref> --rules <review-rules.json> --out <artifact-path> [--policy <path> ...] [--run-manifest <path>] [--resource <pack-relative-resource> ...]
|
|
97
|
+
okstra code-review scope --base <ref> --head <ref> --census <path> --review-policy <shared-policy-path> [--policy <captured-path> ...] [--previous-head <ref> --previous-census <path> --completion <path> ...]
|
|
97
98
|
okstra code-review check-lines --base <ref> --head <ref> --cite <path:line> [--cite ...] [--project-root <dir>]
|
|
98
99
|
|
|
99
100
|
Output: JSON { ok, mode, worktreePath, branch, baseCommit, headCommit,
|
|
@@ -107,9 +108,13 @@ instead of a checked-out tree. This is read-only — it never creates
|
|
|
107
108
|
directories or files. `check-coverage` reads head evidence at `--head` and explicit
|
|
108
109
|
base evidence at `--base`, never the working tree, prints covered cells, missing rules and unknown cells, and exits
|
|
109
110
|
1 for incomplete coverage and 2 for invalid input or completion evidence.
|
|
110
|
-
`census` writes the range's census to `--out
|
|
111
|
-
`--
|
|
112
|
-
|
|
111
|
+
`census` writes the range's census to `--out` and keeps IDs from
|
|
112
|
+
`--previous-census`. It publishes one immutable policy at <out>.policy.json,
|
|
113
|
+
prints its Review policy path/digest, and selects its shared catalog with the
|
|
114
|
+
captured architecture. --run-manifest reuses frozen implementation rules;
|
|
115
|
+
--policy captures additional applied standards. It exits 1 when changed
|
|
116
|
+
non-Python code still needs function cells added by hand. Scope reads frozen
|
|
117
|
+
policy bodies; legacy scope without --review-policy requires --policy files.
|
|
113
118
|
"""
|
|
114
119
|
|
|
115
120
|
|
|
@@ -147,10 +152,14 @@ def _build_parser() -> argparse.ArgumentParser:
|
|
|
147
152
|
parser.add_argument("--previous-census", default="",
|
|
148
153
|
help="scope, census: previous full census")
|
|
149
154
|
parser.add_argument("--rules", default="",
|
|
150
|
-
help="census:
|
|
155
|
+
help="census: canonical shared review-rules.json provenance")
|
|
151
156
|
parser.add_argument("--out", default="", help="census: file to write the census to")
|
|
152
157
|
parser.add_argument("--policy", action="append", default=[],
|
|
153
|
-
help="scope: policy
|
|
158
|
+
help="census: additional policy to freeze; scope: captured policy to fingerprint")
|
|
159
|
+
parser.add_argument("--review-policy", default="", help="scope: shared frozen review policy")
|
|
160
|
+
parser.add_argument("--run-manifest", default="", help="census: reuse this run's frozen review policy")
|
|
161
|
+
parser.add_argument("--resource", action="append", default=[],
|
|
162
|
+
help="census: additional captured pack-relative rule resource")
|
|
154
163
|
parser.add_argument("--date", default="", help="YYYY-MM-DD for branch result naming")
|
|
155
164
|
parser.add_argument("--project-root", default="", help="explicit project root")
|
|
156
165
|
parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
|
|
@@ -385,41 +394,106 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
385
394
|
def _census(args: argparse.Namespace, project_root: Path) -> int:
|
|
386
395
|
from .code_review_census import build_review_census
|
|
387
396
|
from .code_review_coverage import read_review_census
|
|
397
|
+
from .review_policy import render_review_rule_catalog, select_review_policy
|
|
388
398
|
|
|
389
399
|
if not (args.base and args.head and args.rules and args.out):
|
|
390
400
|
print("census: pass --base, --head, --rules and --out", file=sys.stderr)
|
|
391
401
|
return 2
|
|
392
402
|
try:
|
|
403
|
+
if Path(args.rules).name != "review-rules.json":
|
|
404
|
+
raise ValueError("census requires the shared review-rules.json; add project standards with --policy")
|
|
405
|
+
out = Path(args.out).absolute()
|
|
406
|
+
policy_path, policy, digest = _census_review_policy(args, project_root, out)
|
|
407
|
+
changed = changed_lines(project_root, args.base, args.head)
|
|
408
|
+
from .review_policy import review_policy_context
|
|
409
|
+
|
|
410
|
+
paths, manifests = review_policy_context(project_root, args.head, tuple(changed), base=args.base)
|
|
411
|
+
selected = select_review_policy(
|
|
412
|
+
policy, tuple(changed), project_paths=paths, manifest_contents=manifests,
|
|
413
|
+
resources=args.resource,
|
|
414
|
+
)
|
|
393
415
|
result = build_review_census(
|
|
394
416
|
project_root, args.base, args.head, Path(args.rules),
|
|
395
|
-
|
|
417
|
+
changed, frozen_rules=render_review_rule_catalog(selected),
|
|
396
418
|
previous=Path(args.previous_census) if args.previous_census else None,
|
|
397
419
|
)
|
|
398
|
-
|
|
399
|
-
|
|
420
|
+
selection = (f"Review policy digest: {digest}\nReview resources: "
|
|
421
|
+
+ ("; ".join(args.resource) or "-") + "\n")
|
|
422
|
+
out.write_text(selection + result.text, encoding="utf-8")
|
|
400
423
|
read_review_census(out)
|
|
401
424
|
except (OSError, ValueError, SyntaxError, StateError,
|
|
402
425
|
subprocess.CalledProcessError) as exc:
|
|
403
426
|
print(f"census: {exc}", file=sys.stderr)
|
|
404
427
|
return 2
|
|
428
|
+
print(f"Review policy: {policy_path}")
|
|
429
|
+
print(selection, end="")
|
|
405
430
|
print(result.text, end="")
|
|
406
431
|
return 1 if result.unresolved else 0
|
|
407
432
|
|
|
408
433
|
|
|
434
|
+
def _census_review_policy(
|
|
435
|
+
args: argparse.Namespace, project: Path, out: Path,
|
|
436
|
+
) -> tuple[Path, dict, str]:
|
|
437
|
+
from .qa_procedures import canonical_json_digest, load_qa_config, content_digest, safe_qa_path
|
|
438
|
+
from .review_policy import capture_code_review_policy, publish_review_policy, read_review_policy
|
|
439
|
+
from .verification_input_ref import VerificationInputReference
|
|
440
|
+
from .verification_inputs import read_verification_inputs
|
|
441
|
+
from .json_boundary import load_owned_object
|
|
442
|
+
|
|
443
|
+
destination = Path(str(out) + ".policy.json")
|
|
444
|
+
if not destination.is_relative_to(project.absolute() / ".okstra"):
|
|
445
|
+
raise ValueError("review census and policy must remain in project artifacts")
|
|
446
|
+
safe_qa_path(project, destination.relative_to(project.absolute()).as_posix())
|
|
447
|
+
extra = tuple(Path(path).expanduser().absolute() for path in args.policy)
|
|
448
|
+
frozen = None
|
|
449
|
+
if args.run_manifest:
|
|
450
|
+
manifest = load_owned_object(Path(args.run_manifest), artifact="run manifest")
|
|
451
|
+
reference = VerificationInputReference.required_from_artifact_fields(manifest)
|
|
452
|
+
inputs = read_verification_inputs(safe_qa_path(project, reference.relative_path), reference.digest)
|
|
453
|
+
if "reviewPolicy" not in inputs:
|
|
454
|
+
raise ValueError("the selected run has no frozen review policy")
|
|
455
|
+
frozen = inputs["reviewPolicy"]
|
|
456
|
+
if destination.exists():
|
|
457
|
+
policy = read_review_policy(destination)
|
|
458
|
+
if any(str(path) not in policy["sources"] for path in extra):
|
|
459
|
+
raise ValueError("additional policy is absent from the immutable review policy")
|
|
460
|
+
if frozen is not None:
|
|
461
|
+
if "authorPolicyDigest" not in policy:
|
|
462
|
+
raise ValueError("immutable review policy has no author policy identity; use a new census output")
|
|
463
|
+
if policy["authorPolicyDigest"] != canonical_json_digest(frozen):
|
|
464
|
+
raise ValueError("the selected run differs from the immutable review policy")
|
|
465
|
+
return destination, policy, content_digest(destination.read_bytes())
|
|
466
|
+
policy = capture_code_review_policy(project, {} if frozen is not None else load_qa_config(project),
|
|
467
|
+
additional_sources=extra, policy=frozen)
|
|
468
|
+
path, digest = publish_review_policy(project, destination, policy)
|
|
469
|
+
return path, policy, digest
|
|
470
|
+
|
|
471
|
+
|
|
409
472
|
def _scope(args: argparse.Namespace, project_root: Path) -> int:
|
|
410
473
|
from .agent.invocation import AgentInvocationError
|
|
411
474
|
from .code_review_scope import review_scope
|
|
412
475
|
|
|
413
|
-
if not (args.base and args.head and args.census and args.policy):
|
|
414
|
-
print("scope: pass --base, --head, --census and --policy", file=sys.stderr)
|
|
476
|
+
if not (args.base and args.head and args.census and (args.policy or args.review_policy)):
|
|
477
|
+
print("scope: pass --base, --head, --census and --review-policy or --policy", file=sys.stderr)
|
|
415
478
|
return 2
|
|
416
479
|
try:
|
|
480
|
+
from .review_policy import read_review_policy
|
|
481
|
+
from .qa_procedures import content_digest
|
|
482
|
+
|
|
483
|
+
policy_path = Path(args.review_policy) if args.review_policy else None
|
|
484
|
+
if policy_path is not None:
|
|
485
|
+
digests = [row.removeprefix("Review policy digest: ")
|
|
486
|
+
for row in Path(args.census).read_text(encoding="utf-8").splitlines()
|
|
487
|
+
if row.startswith("Review policy digest: ")]
|
|
488
|
+
if digests != [content_digest(policy_path.read_bytes())]:
|
|
489
|
+
raise ValueError("census review policy digest is missing or differs from the shared policy")
|
|
417
490
|
result = review_scope(
|
|
418
491
|
project_root, Path(args.census), args.base, args.head,
|
|
419
492
|
[Path(path).expanduser() for path in args.policy],
|
|
420
493
|
previous_head=args.previous_head,
|
|
421
494
|
previous_census=Path(args.previous_census) if args.previous_census else None,
|
|
422
495
|
completions=[Path(path) for path in args.completion],
|
|
496
|
+
policy=read_review_policy(policy_path) if policy_path is not None else None,
|
|
423
497
|
)
|
|
424
498
|
except (OSError, ValueError, AgentInvocationError) as exc:
|
|
425
499
|
print(f"scope: {exc}", file=sys.stderr)
|
|
@@ -141,6 +141,10 @@ def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
|
|
|
141
141
|
status, force_reappend,
|
|
142
142
|
fields.get("head_commit"),
|
|
143
143
|
fields.get("source")):
|
|
144
|
+
if status == "done" and not fields.get("reconciled"):
|
|
145
|
+
from .design_review_evidence import validate_design_completion
|
|
146
|
+
|
|
147
|
+
validate_design_completion(plan_run_root, impl_task_key, stage, str(fields.get("head_commit") or ""))
|
|
144
148
|
record: Dict[str, Any] = {
|
|
145
149
|
"impl_task_key": impl_task_key,
|
|
146
150
|
"stage": stage,
|
|
@@ -432,15 +436,14 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
|
|
|
432
436
|
carry_path = str(cf.relative_to(task_root))
|
|
433
437
|
except ValueError:
|
|
434
438
|
carry_path = str(cf)
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
)
|
|
439
|
+
try:
|
|
440
|
+
append_consumer(
|
|
441
|
+
plan_run_root, impl_task_key=impl_key, stage=stage, status="done",
|
|
442
|
+
head_commit=head, carry_path=carry_path, source="carry-backfill",
|
|
443
|
+
)
|
|
444
|
+
except ValueError:
|
|
445
|
+
# expected-miss: a pending or invalid design review leaves the stage unsettled.
|
|
446
|
+
continue
|
|
444
447
|
settled_stages.add(stage)
|
|
445
448
|
recovered += 1
|
|
446
449
|
return recovered
|