okstra 0.227.0 → 0.228.1
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 +1 -1
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/docs/architecture/storage-model.md +77 -0
- package/docs/cli.md +15 -3
- package/docs/project-structure-overview.md +12 -2
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/prompts/coding-preflight/clean-code.md +24 -18
- package/runtime/prompts/coding-preflight/overview.md +6 -6
- package/runtime/prompts/duties/code-reviewer.json +1 -0
- package/runtime/prompts/lead/convergence.md +5 -19
- package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
- package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +2 -2
- package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
- package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
- package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
- package/runtime/python/okstra_ctl/brief_sources.py +162 -44
- package/runtime/python/okstra_ctl/code_review_coverage.py +11 -1
- package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
- package/runtime/python/okstra_ctl/code_review_target.py +46 -10
- package/runtime/python/okstra_ctl/conformance.py +9 -3
- package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
- package/runtime/python/okstra_ctl/fixed_text.py +31 -9
- package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
- package/runtime/python/okstra_ctl/json_registry.py +3 -18
- package/runtime/python/okstra_ctl/manager_split.py +201 -84
- package/runtime/python/okstra_ctl/model_io/references.py +31 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
- package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
- package/runtime/python/okstra_ctl/path_hints.py +13 -1
- package/runtime/python/okstra_ctl/paths.py +4 -0
- package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +3 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +3 -1
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/plan_items.py +9 -11
- package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
- package/runtime/python/okstra_ctl/prior_planning.py +6 -17
- package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
- package/runtime/python/okstra_ctl/qa_commands.py +66 -1
- package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
- package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
- package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
- package/runtime/python/okstra_ctl/render.py +10 -0
- package/runtime/python/okstra_ctl/report_assembly.py +12 -12
- package/runtime/python/okstra_ctl/run.py +108 -5
- package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
- package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
- package/runtime/python/okstra_ctl/verification_plan.py +116 -0
- package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
- package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
- package/runtime/python/okstra_project/dirs.py +22 -0
- package/runtime/python/okstra_project/resolver.py +10 -0
- package/runtime/schemas/final-report-v3.0.schema.json +5 -1
- package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
- package/runtime/skills/okstra-code-review/SKILL.md +39 -45
- package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
- package/runtime/skills/okstra-code-review/references/review-calibration.md +31 -8
- package/runtime/skills/okstra-manager/SKILL.md +2 -2
- package/runtime/skills/okstra-setup/SKILL.md +2 -0
- package/runtime/skills/okstra-setup/references/project-config.md +2 -0
- package/runtime/validators/validate-brief.py +21 -5
|
@@ -13,7 +13,7 @@ from .build_tools import command_invokes_build_tool
|
|
|
13
13
|
from .design_snapshot import build_design_snapshot
|
|
14
14
|
from .design_surfaces import (
|
|
15
15
|
DesignSurfaceError,
|
|
16
|
-
|
|
16
|
+
detect_design_surfaces_in_unvalidated_plan,
|
|
17
17
|
expected_prep_plan_item_id,
|
|
18
18
|
)
|
|
19
19
|
|
|
@@ -104,7 +104,7 @@ def _item_block(source: str) -> str:
|
|
|
104
104
|
return "record" if source in _RECORD_SOURCES else "execution"
|
|
105
105
|
|
|
106
106
|
|
|
107
|
-
def
|
|
107
|
+
def stage_scope(row: Mapping[str, Any] | None, *coordinates: int) -> list[int] | None:
|
|
108
108
|
"""이 항목이 걸리는 스테이지. 어디에도 안 걸리면 ``None``.
|
|
109
109
|
|
|
110
110
|
게이트 범위를 다음 실행 스테이지로 좁히려면 항목마다 이 값이 있어야 한다.
|
|
@@ -228,7 +228,7 @@ def _extract_standard_items(planning: Mapping[str, Any]) -> list[dict[str, Any]]
|
|
|
228
228
|
{
|
|
229
229
|
"id": item_id,
|
|
230
230
|
"elementId": _natural_element_id(source, prefix, row, item_id),
|
|
231
|
-
"stageScope":
|
|
231
|
+
"stageScope": stage_scope(row),
|
|
232
232
|
"block": _item_block(source),
|
|
233
233
|
"subject": _subject(row, source),
|
|
234
234
|
"sourceSection": section,
|
|
@@ -253,7 +253,7 @@ def _extract_step_items(
|
|
|
253
253
|
# 평면 배열에는 좌표가 없어 위치 id 로 떨어진다.
|
|
254
254
|
"id": f"{prefix}-{index}",
|
|
255
255
|
"elementId": f"{prefix}-{index}",
|
|
256
|
-
"stageScope":
|
|
256
|
+
"stageScope": stage_scope(row),
|
|
257
257
|
"block": "execution", "subject": _subject(row, "stepwiseExecution"),
|
|
258
258
|
"sourceSection": section,
|
|
259
259
|
"ticketId": _ticket_id(row),
|
|
@@ -275,7 +275,7 @@ def _extract_step_items(
|
|
|
275
275
|
{
|
|
276
276
|
"id": f"{prefix}-{stage_number}.{step_number}",
|
|
277
277
|
"elementId": f"step:{stage_number}.{step_number}",
|
|
278
|
-
"stageScope":
|
|
278
|
+
"stageScope": stage_scope(None, stage_number),
|
|
279
279
|
"block": "execution",
|
|
280
280
|
"subject": _subject(row, "stepwiseExecution"),
|
|
281
281
|
"sourceSection": section,
|
|
@@ -292,15 +292,13 @@ def _extract_step_items(
|
|
|
292
292
|
def _extract_prep_items(
|
|
293
293
|
planning: Mapping[str, Any], items: list[dict[str, Any]]
|
|
294
294
|
) -> None:
|
|
295
|
-
if not planning.get("stages"):
|
|
296
|
-
return
|
|
297
295
|
# 계약 분기는 탐지기가 안다(`design_surfaces._planned_file_structure`).
|
|
298
296
|
# 여기서 레거시 모양을 흉내 내 넘기던 동안 그 지식은 이 호출부에만 있었고,
|
|
299
297
|
# 같은 탐지기를 부르는 나머지 세 곳은 선택 방향 계획에서 실패했다.
|
|
300
298
|
try:
|
|
301
|
-
triggers =
|
|
302
|
-
except
|
|
303
|
-
raise PlanItemContractError(
|
|
299
|
+
triggers = detect_design_surfaces_in_unvalidated_plan(planning)
|
|
300
|
+
except DesignSurfaceError as exc:
|
|
301
|
+
raise PlanItemContractError(str(exc)) from exc
|
|
304
302
|
for trigger in triggers:
|
|
305
303
|
item_id = expected_prep_plan_item_id(trigger.stage, trigger.kind)
|
|
306
304
|
_add_item(
|
|
@@ -308,7 +306,7 @@ def _extract_prep_items(
|
|
|
308
306
|
{
|
|
309
307
|
"id": item_id,
|
|
310
308
|
"elementId": f"prep:{trigger.stage}:{_element_key(trigger.kind)}",
|
|
311
|
-
"stageScope":
|
|
309
|
+
"stageScope": stage_scope(None, trigger.stage),
|
|
312
310
|
"block": "execution",
|
|
313
311
|
"subject": f"Stage {trigger.stage} {trigger.kind} design preparation",
|
|
314
312
|
"sourceSection": "5.5.10",
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
from typing import Protocol
|
|
5
|
+
|
|
6
|
+
from ..paths import RunRef
|
|
7
|
+
from ..verification_input_ref import VerificationInputReference
|
|
8
|
+
from ..verification_input_types import VerificationInputs
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class VerificationInputStore(Protocol):
|
|
12
|
+
def freeze(
|
|
13
|
+
self, project: Path, source: Path, ref: RunRef,
|
|
14
|
+
*, approved_plan: Path | None,
|
|
15
|
+
) -> VerificationInputReference: ...
|
|
16
|
+
|
|
17
|
+
def read(self, path: Path, digest: str) -> VerificationInputs: ...
|
|
@@ -19,14 +19,13 @@ timeout 시킨 적이 있다(`clarification_items.carry` 참고).
|
|
|
19
19
|
"""
|
|
20
20
|
from __future__ import annotations
|
|
21
21
|
|
|
22
|
-
import re
|
|
23
22
|
from pathlib import Path
|
|
24
23
|
from typing import Any, Mapping
|
|
25
24
|
|
|
26
25
|
from .clarification_items import carried_clarification_rows
|
|
27
26
|
from .final_report_paths import final_report_data_path
|
|
28
|
-
from .json_boundary import JsonBoundaryError, load_owned_object
|
|
29
27
|
from .paths import RunRef, infer_project_root, project_rel
|
|
28
|
+
from .prior_run_summary import load_prior_object, one_line
|
|
30
29
|
|
|
31
30
|
|
|
32
31
|
PLANNING_TASK_TYPE = "implementation-planning"
|
|
@@ -34,7 +33,6 @@ PLANNING_TASK_TYPE = "implementation-planning"
|
|
|
34
33
|
# 의 어휘를 그대로 쓴다 — 새 어휘를 만들면 같은 finding 이 run 마다 다르게 읽힌다.
|
|
35
34
|
UNSETTLED_CLASSIFICATIONS = ("contested", "worker-unique")
|
|
36
35
|
_SUMMARY_LIMIT = 200
|
|
37
|
-
_WHITESPACE_RE = re.compile(r"\s+")
|
|
38
36
|
|
|
39
37
|
|
|
40
38
|
def build_prior_planning_summary(task_root: Path) -> str:
|
|
@@ -138,20 +136,11 @@ def _load_object(path: Path) -> Mapping[str, Any]:
|
|
|
138
136
|
이 블록은 전부 최선 노력이다. 직전 run 의 산출물이 깨졌다고 새 run 의 준비를
|
|
139
137
|
막으면, 다시 도는 이유였던 그 실패가 재실행 자체를 못 하게 만든다.
|
|
140
138
|
"""
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
# 맥락일 뿐이라 없는 상태가 정상 분기고, 소비처는 해당 하위 블록을
|
|
146
|
-
# 생략한다.
|
|
147
|
-
return {}
|
|
148
|
-
return data if isinstance(data, Mapping) else {}
|
|
139
|
+
# A missing file is the normal case here (a run that ended before writing
|
|
140
|
+
# it), so the reason is not shown.
|
|
141
|
+
data, _reason = load_prior_object(path, artifact="prior planning artifact")
|
|
142
|
+
return data
|
|
149
143
|
|
|
150
144
|
|
|
151
145
|
def _one_line(value: object) -> str:
|
|
152
|
-
|
|
153
|
-
return ""
|
|
154
|
-
collapsed = _WHITESPACE_RE.sub(" ", value).strip()
|
|
155
|
-
if len(collapsed) <= _SUMMARY_LIMIT:
|
|
156
|
-
return collapsed
|
|
157
|
-
return collapsed[: _SUMMARY_LIMIT - 1].rstrip() + "…"
|
|
146
|
+
return one_line(value, _SUMMARY_LIMIT)
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""Shared pieces of the packet blocks that summarise an earlier run's artifacts."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import re
|
|
5
|
+
from collections.abc import Mapping
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from .json_boundary import JsonBoundaryError, load_owned_object
|
|
10
|
+
|
|
11
|
+
_WHITESPACE_RE = re.compile(r"\s+")
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def one_line(value: object, limit: int) -> str:
|
|
15
|
+
"""``value`` as one line of at most ``limit`` characters; ``""`` if not a string."""
|
|
16
|
+
if not isinstance(value, str):
|
|
17
|
+
return ""
|
|
18
|
+
collapsed = _WHITESPACE_RE.sub(" ", value).strip()
|
|
19
|
+
if len(collapsed) <= limit:
|
|
20
|
+
return collapsed
|
|
21
|
+
return collapsed[: limit - 1].rstrip() + "…"
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def load_prior_object(
|
|
25
|
+
path: Path, *, artifact: str,
|
|
26
|
+
) -> tuple[Mapping[str, Any], str | None]:
|
|
27
|
+
"""The owned object at ``path``, or an empty mapping and why it could not be read.
|
|
28
|
+
|
|
29
|
+
A packet block is context for a new run, so a broken earlier artifact must not
|
|
30
|
+
stop that run's prepare; the caller decides whether to show the reason.
|
|
31
|
+
"""
|
|
32
|
+
try:
|
|
33
|
+
return load_owned_object(path, artifact=artifact), None
|
|
34
|
+
except JsonBoundaryError as exc:
|
|
35
|
+
return {}, exc.reason
|
|
@@ -18,7 +18,8 @@ from __future__ import annotations
|
|
|
18
18
|
|
|
19
19
|
import re
|
|
20
20
|
import shlex
|
|
21
|
-
from
|
|
21
|
+
from pathlib import PurePosixPath
|
|
22
|
+
from typing import Iterable, Mapping
|
|
22
23
|
|
|
23
24
|
# 카테고리 화이트리스트. 알 수 없는 카테고리는 오타 가능성이 높으므로 거부.
|
|
24
25
|
# `db-test` 는 DB/IO/SQL 변경의 실제 DB(또는 충실한 복제) 실행 테스트 전용 카테고리 —
|
|
@@ -26,6 +27,11 @@ from typing import Iterable
|
|
|
26
27
|
# `test` 와 분리한다. implementation verifier / final-verification 의 DB 실제실행 게이트가
|
|
27
28
|
# diff 가 DB 를 건드릴 때 이 카테고리(또는 plan validation 의 db 스텝)를 요구한다.
|
|
28
29
|
ALLOWED_CATEGORIES: tuple[str, ...] = ("lint", "format", "typecheck", "test", "db-test")
|
|
30
|
+
QA_COMMAND_EXECUTING_TASK_TYPES = ("implementation", "final-verification")
|
|
31
|
+
QA_RELATIVE_PATH_DESCRIPTION = (
|
|
32
|
+
"non-blank relative POSIX path with at least one component after normalization, "
|
|
33
|
+
"without traversal or backslashes"
|
|
34
|
+
)
|
|
29
35
|
|
|
30
36
|
# Mutation 을 유발하거나 lockfile 을 갱신하는 토큰. 각 토큰은 `cmd` 문자열을
|
|
31
37
|
# 공백으로 단순 분해한 결과 또는 부분 일치 패턴(prefix/suffix sensitive) 로 검출한다.
|
|
@@ -185,6 +191,7 @@ def validate_qa_commands(qa: object) -> list[str]:
|
|
|
185
191
|
여기서는 raise 하지 않고 메시지를 모아서 호출자가 일괄 보고할 수 있게 한다.
|
|
186
192
|
"""
|
|
187
193
|
errors: list[str] = []
|
|
194
|
+
seen_ids: set[str] = set()
|
|
188
195
|
if qa is None:
|
|
189
196
|
return errors # 옵션 필드 — 미선언은 합법.
|
|
190
197
|
if not isinstance(qa, dict):
|
|
@@ -209,6 +216,10 @@ def validate_qa_commands(qa: object) -> list[str]:
|
|
|
209
216
|
continue
|
|
210
217
|
label = entry.get("label")
|
|
211
218
|
cmd = entry.get("cmd")
|
|
219
|
+
errors.extend(
|
|
220
|
+
f"qaCommands.{category}[{idx}]: {error}"
|
|
221
|
+
for error in qa_metadata_errors(entry, seen_ids)
|
|
222
|
+
)
|
|
212
223
|
if not isinstance(label, str) or not label.strip():
|
|
213
224
|
errors.append(
|
|
214
225
|
f"qaCommands.{category}[{idx}].label must be a non-empty string"
|
|
@@ -228,6 +239,60 @@ def validate_qa_commands(qa: object) -> list[str]:
|
|
|
228
239
|
return errors
|
|
229
240
|
|
|
230
241
|
|
|
242
|
+
def qa_metadata_errors(entry: Mapping[str, object], seen_ids: set[str]) -> list[str]:
|
|
243
|
+
errors: list[str] = []
|
|
244
|
+
identifier = entry.get("id")
|
|
245
|
+
if identifier is not None:
|
|
246
|
+
if not isinstance(identifier, str) or not re.fullmatch(
|
|
247
|
+
r"[A-Za-z0-9][A-Za-z0-9._-]*", identifier
|
|
248
|
+
):
|
|
249
|
+
errors.append("qaCommands id must be a safe non-empty identifier")
|
|
250
|
+
elif identifier in seen_ids:
|
|
251
|
+
errors.append(f"duplicate qaCommands id: {identifier}")
|
|
252
|
+
else:
|
|
253
|
+
seen_ids.add(identifier)
|
|
254
|
+
if "procedurePath" in entry:
|
|
255
|
+
if not identifier:
|
|
256
|
+
errors.append("procedurePath requires an id")
|
|
257
|
+
if not qa_relative_path_valid(entry["procedurePath"]):
|
|
258
|
+
errors.append(f"procedurePath must be a {QA_RELATIVE_PATH_DESCRIPTION}")
|
|
259
|
+
for key in ("sourcePaths", "resourceKeys"):
|
|
260
|
+
if key not in entry:
|
|
261
|
+
continue
|
|
262
|
+
values = entry[key]
|
|
263
|
+
if not isinstance(values, list) or any(
|
|
264
|
+
not isinstance(value, str) or not value.strip() for value in values
|
|
265
|
+
):
|
|
266
|
+
errors.append(f"{key} must be an array of non-empty strings")
|
|
267
|
+
continue
|
|
268
|
+
if len(values) != len(set(values)):
|
|
269
|
+
errors.append(f"{key} must not contain duplicates")
|
|
270
|
+
if key == "sourcePaths" and any(
|
|
271
|
+
not qa_relative_path_valid(value) for value in values
|
|
272
|
+
):
|
|
273
|
+
errors.append(
|
|
274
|
+
"each sourcePaths item must be a " + QA_RELATIVE_PATH_DESCRIPTION
|
|
275
|
+
)
|
|
276
|
+
if key == "resourceKeys" and any(
|
|
277
|
+
"://" in value or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9:._/-]*", value)
|
|
278
|
+
for value in values
|
|
279
|
+
):
|
|
280
|
+
errors.append("resourceKeys must be non-secret resource identifiers")
|
|
281
|
+
digest = entry.get("sourceBaselineDigest")
|
|
282
|
+
if digest is not None and (
|
|
283
|
+
not isinstance(digest, str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", digest)
|
|
284
|
+
):
|
|
285
|
+
errors.append("sourceBaselineDigest must be a sha256 digest")
|
|
286
|
+
return errors
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
def qa_relative_path_valid(value: object) -> bool:
|
|
290
|
+
if not isinstance(value, str) or not value.strip() or "\\" in value:
|
|
291
|
+
return False
|
|
292
|
+
path = PurePosixPath(value)
|
|
293
|
+
return bool(path.parts) and not path.is_absolute() and ".." not in path.parts
|
|
294
|
+
|
|
295
|
+
|
|
231
296
|
def format_errors(errors: Iterable[str]) -> str:
|
|
232
297
|
"""`PrepareError` 등에 그대로 박을 수 있는 멀티라인 문자열."""
|
|
233
298
|
lines = list(errors)
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"""Typed command inputs and fixed text projections for `okstra qa`."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import argparse
|
|
5
|
+
import sys
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
|
|
8
|
+
from .fixed_text import line
|
|
9
|
+
from .qa_procedures import inspect_commands, register_command
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def main(argv: list[str] | None = None) -> int:
|
|
13
|
+
parser = argparse.ArgumentParser(prog="okstra qa")
|
|
14
|
+
parser.add_argument("operation", choices=("register", "show", "check"))
|
|
15
|
+
parser.add_argument("--project-root", type=Path, required=True)
|
|
16
|
+
parser.add_argument("--source-root", type=Path)
|
|
17
|
+
parser.add_argument("--id")
|
|
18
|
+
parser.add_argument("--category", choices=("test", "db-test"))
|
|
19
|
+
parser.add_argument("--label")
|
|
20
|
+
parser.add_argument("--cmd")
|
|
21
|
+
parser.add_argument("--procedure-input", type=Path)
|
|
22
|
+
parser.add_argument("--source-path", action="append", default=[])
|
|
23
|
+
parser.add_argument("--resource-key", action="append", default=[])
|
|
24
|
+
parser.add_argument("--expected-entry-digest")
|
|
25
|
+
args = parser.parse_args(argv)
|
|
26
|
+
source = args.source_root or args.project_root
|
|
27
|
+
try:
|
|
28
|
+
if args.operation == "register":
|
|
29
|
+
required = ("id", "category", "label", "cmd", "procedure_input")
|
|
30
|
+
if any(getattr(args, key) is None for key in required):
|
|
31
|
+
parser.error(
|
|
32
|
+
"register requires --id, --category, --label, --cmd "
|
|
33
|
+
"and --procedure-input"
|
|
34
|
+
)
|
|
35
|
+
entry = {"id": args.id, "label": args.label, "cmd": args.cmd}
|
|
36
|
+
if args.source_path:
|
|
37
|
+
entry["sourcePaths"] = args.source_path
|
|
38
|
+
if args.resource_key:
|
|
39
|
+
entry["resourceKeys"] = args.resource_key
|
|
40
|
+
digest = register_command(
|
|
41
|
+
args.project_root, source, args.category, entry,
|
|
42
|
+
args.procedure_input, expected_digest=args.expected_entry_digest,
|
|
43
|
+
)
|
|
44
|
+
print(line("Registered entry digest", digest), end="")
|
|
45
|
+
return 0
|
|
46
|
+
rows = inspect_commands(args.project_root, source)
|
|
47
|
+
print(line("Source root", str(source.resolve())), end="")
|
|
48
|
+
selection = "explicit" if args.source_root else "original project"
|
|
49
|
+
print(line("Source selection", selection), end="")
|
|
50
|
+
for row in rows:
|
|
51
|
+
print("".join(line(key, row.get(field)) for key, field in (
|
|
52
|
+
("Category", "category"), ("ID", "id"), ("Label", "label"),
|
|
53
|
+
("Command", "cmd"), ("Procedure", "procedurePath"),
|
|
54
|
+
("Entry digest", "entryDigest"), ("Source status", "sourceStatus"),
|
|
55
|
+
("Execution evidence", "evidenceStatus"))), end="")
|
|
56
|
+
errors = [row["error"] for row in rows if "error" in row]
|
|
57
|
+
if errors:
|
|
58
|
+
raise ValueError("; ".join(errors))
|
|
59
|
+
stale = any(row["sourceStatus"] == "changed" for row in rows)
|
|
60
|
+
return int(args.operation == "check" and stale)
|
|
61
|
+
except (OSError, ValueError) as exc:
|
|
62
|
+
print(f"qa: {exc}", file=sys.stderr)
|
|
63
|
+
return 2
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
if __name__ == "__main__":
|
|
67
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
"""Project verification procedure paths, fingerprints, and atomic registration."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import hashlib
|
|
5
|
+
import json
|
|
6
|
+
import os
|
|
7
|
+
import tempfile
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Any, Literal, Mapping, TypedDict
|
|
10
|
+
|
|
11
|
+
from okstra_project import project_json_path
|
|
12
|
+
from okstra_project.dirs import OKSTRA_DIR_NAME, json_lock_path, registry_lock
|
|
13
|
+
|
|
14
|
+
from .analysis_packet import _heading_lines
|
|
15
|
+
from .json_boundary import load_owned_object, write_owned_object_atomic
|
|
16
|
+
from .qa_commands import (
|
|
17
|
+
QA_RELATIVE_PATH_DESCRIPTION, qa_relative_path_valid, validate_qa_commands,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
PROCEDURE_SECTIONS = (
|
|
21
|
+
"Execution", "Environment", "User actions", "Success observations", "Cleanup",
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class QaInspectionRow(TypedDict, total=False):
|
|
26
|
+
category: str
|
|
27
|
+
index: int
|
|
28
|
+
id: str
|
|
29
|
+
label: str
|
|
30
|
+
cmd: str
|
|
31
|
+
procedurePath: str
|
|
32
|
+
entryDigest: str
|
|
33
|
+
procedureDigest: str
|
|
34
|
+
sourceStatus: Literal[
|
|
35
|
+
"not-declared", "not-queried", "no-baseline", "unchanged", "changed",
|
|
36
|
+
]
|
|
37
|
+
evidenceStatus: Literal["not-queried"]
|
|
38
|
+
error: str
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def content_digest(value: bytes) -> str:
|
|
42
|
+
return "sha256:" + hashlib.sha256(value).hexdigest()
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def canonical_json_digest(value: Mapping[str, Any]) -> str:
|
|
46
|
+
encoded = json.dumps(dict(value), sort_keys=True, separators=(",", ":"))
|
|
47
|
+
return content_digest(encoded.encode())
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def safe_qa_path(root: Path, relative: str) -> Path:
|
|
51
|
+
if not qa_relative_path_valid(relative):
|
|
52
|
+
raise ValueError(
|
|
53
|
+
f"QA path must be a {QA_RELATIVE_PATH_DESCRIPTION}: {relative}"
|
|
54
|
+
)
|
|
55
|
+
path = root.resolve()
|
|
56
|
+
for part in Path(relative).parts:
|
|
57
|
+
path = path / part
|
|
58
|
+
if path.is_symlink():
|
|
59
|
+
raise ValueError(f"QA path must not contain a symlink: {relative}")
|
|
60
|
+
return path
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def existing_qa_file(root: Path, relative: str) -> Path:
|
|
64
|
+
path = safe_qa_path(root, relative)
|
|
65
|
+
if not path.is_file():
|
|
66
|
+
raise ValueError(f"QA input must be an existing regular file: {relative}")
|
|
67
|
+
return path
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def procedure_root(project: Path, source: Path, relative: str) -> Path:
|
|
71
|
+
return project if Path(relative).parts[:1] == (OKSTRA_DIR_NAME,) else source
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def validate_procedure_sections(raw: bytes) -> None:
|
|
75
|
+
headings = {text[3:].rstrip("#").strip()
|
|
76
|
+
for _, text in _heading_lines(raw.decode("utf-8").splitlines())
|
|
77
|
+
if text.startswith("## ")}
|
|
78
|
+
missing = set(PROCEDURE_SECTIONS) - headings
|
|
79
|
+
if missing:
|
|
80
|
+
raise ValueError("procedure sections missing: " + ", ".join(sorted(missing)))
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def read_validated_procedure(path: Path) -> bytes:
|
|
84
|
+
raw = path.read_bytes()
|
|
85
|
+
validate_procedure_sections(raw)
|
|
86
|
+
return raw
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def source_digest(source: Path, relatives: list[str]) -> str:
|
|
90
|
+
return canonical_json_digest({
|
|
91
|
+
relative: content_digest(existing_qa_file(source, relative).read_bytes())
|
|
92
|
+
for relative in sorted(relatives)
|
|
93
|
+
})
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def load_qa_config(project: Path) -> dict[str, Any]:
|
|
97
|
+
config = load_owned_object(project_json_path(project), artifact="project config")
|
|
98
|
+
errors = validate_qa_commands(config.get("qaCommands"))
|
|
99
|
+
if errors:
|
|
100
|
+
raise ValueError("; ".join(errors))
|
|
101
|
+
return config
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def inspect_commands(project: Path, source: Path) -> list[QaInspectionRow]:
|
|
105
|
+
config = load_qa_config(project)
|
|
106
|
+
rows: list[QaInspectionRow] = []
|
|
107
|
+
for category, entries in (config.get("qaCommands") or {}).items():
|
|
108
|
+
for index, entry in enumerate(entries):
|
|
109
|
+
row: QaInspectionRow = {
|
|
110
|
+
**entry, "category": category, "index": index,
|
|
111
|
+
"entryDigest": canonical_json_digest(entry),
|
|
112
|
+
"sourceStatus": (
|
|
113
|
+
"not-queried" if entry.get("sourcePaths") else "not-declared"
|
|
114
|
+
),
|
|
115
|
+
"evidenceStatus": "not-queried",
|
|
116
|
+
}
|
|
117
|
+
try:
|
|
118
|
+
relative = entry.get("procedurePath")
|
|
119
|
+
if relative:
|
|
120
|
+
root = procedure_root(project, source, relative)
|
|
121
|
+
raw = read_validated_procedure(existing_qa_file(root, relative))
|
|
122
|
+
row["procedureDigest"] = content_digest(raw)
|
|
123
|
+
if entry.get("sourcePaths"):
|
|
124
|
+
observed = source_digest(source, entry["sourcePaths"])
|
|
125
|
+
baseline = entry.get("sourceBaselineDigest")
|
|
126
|
+
row["sourceStatus"] = "no-baseline" if not baseline else (
|
|
127
|
+
"unchanged" if observed == baseline else "changed"
|
|
128
|
+
)
|
|
129
|
+
except (OSError, ValueError) as exc:
|
|
130
|
+
row["error"] = str(exc)
|
|
131
|
+
rows.append(row)
|
|
132
|
+
return rows
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def _store_procedure(project: Path, relative: str, raw: bytes) -> None:
|
|
136
|
+
target = safe_qa_path(project, relative)
|
|
137
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
138
|
+
descriptor, name = tempfile.mkstemp(prefix=".procedure-", dir=target.parent)
|
|
139
|
+
temporary = Path(name)
|
|
140
|
+
try:
|
|
141
|
+
with os.fdopen(descriptor, "wb") as handle:
|
|
142
|
+
handle.write(raw)
|
|
143
|
+
handle.flush()
|
|
144
|
+
os.fsync(handle.fileno())
|
|
145
|
+
try:
|
|
146
|
+
os.link(temporary, target)
|
|
147
|
+
except FileExistsError:
|
|
148
|
+
if existing_qa_file(project, relative).read_bytes() != raw:
|
|
149
|
+
raise ValueError("procedure digest path contains different bytes")
|
|
150
|
+
finally:
|
|
151
|
+
temporary.unlink(missing_ok=True)
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def read_registration_input(
|
|
155
|
+
project: Path, source: Path, category: str, entry: Mapping[str, Any],
|
|
156
|
+
procedure: Path,
|
|
157
|
+
) -> tuple[dict[str, Any], bytes, bool]:
|
|
158
|
+
candidate = dict(entry)
|
|
159
|
+
errors = validate_qa_commands({category: [candidate]})
|
|
160
|
+
if errors or not candidate.get("id"):
|
|
161
|
+
raise ValueError("; ".join(errors) or "registration requires an id")
|
|
162
|
+
absolute = procedure.absolute()
|
|
163
|
+
if ".." in absolute.parts:
|
|
164
|
+
raise ValueError("procedure input must not contain traversal")
|
|
165
|
+
relative = None
|
|
166
|
+
roots = (project.absolute(), project.resolve(), source.absolute(), source.resolve())
|
|
167
|
+
for root in sorted(roots, key=lambda value: len(value.parts), reverse=True):
|
|
168
|
+
if absolute.is_relative_to(root):
|
|
169
|
+
absolute = existing_qa_file(root, absolute.relative_to(root).as_posix())
|
|
170
|
+
break
|
|
171
|
+
selected_roots = (project.resolve(), source.resolve())
|
|
172
|
+
for root in sorted(
|
|
173
|
+
selected_roots, key=lambda value: len(value.parts), reverse=True,
|
|
174
|
+
):
|
|
175
|
+
if absolute.is_relative_to(root):
|
|
176
|
+
relative = absolute.relative_to(root).as_posix()
|
|
177
|
+
selected = procedure_root(project, source, relative)
|
|
178
|
+
path = existing_qa_file(selected, relative)
|
|
179
|
+
break
|
|
180
|
+
else:
|
|
181
|
+
external_relative = absolute.relative_to(absolute.anchor).as_posix()
|
|
182
|
+
path = existing_qa_file(Path(absolute.anchor), external_relative)
|
|
183
|
+
raw = read_validated_procedure(path)
|
|
184
|
+
external = relative is None
|
|
185
|
+
if external:
|
|
186
|
+
digest = content_digest(raw).split(":", 1)[1]
|
|
187
|
+
relative = (
|
|
188
|
+
f"{OKSTRA_DIR_NAME}/verification/procedures/{candidate['id']}/{digest}.md"
|
|
189
|
+
)
|
|
190
|
+
candidate["procedurePath"] = relative
|
|
191
|
+
if candidate.get("sourcePaths"):
|
|
192
|
+
candidate["sourceBaselineDigest"] = source_digest(
|
|
193
|
+
source, candidate["sourcePaths"]
|
|
194
|
+
)
|
|
195
|
+
return candidate, raw, external
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
def register_command(
|
|
199
|
+
project: Path, source: Path, category: str, entry: Mapping[str, Any],
|
|
200
|
+
procedure: Path, *, expected_digest: str | None = None,
|
|
201
|
+
) -> str:
|
|
202
|
+
candidate, raw, external = read_registration_input(
|
|
203
|
+
project, source, category, entry, procedure
|
|
204
|
+
)
|
|
205
|
+
with registry_lock(json_lock_path(project_json_path(project))):
|
|
206
|
+
config = load_qa_config(project)
|
|
207
|
+
qa = config.get("qaCommands") or {}
|
|
208
|
+
config["qaCommands"] = qa
|
|
209
|
+
found = [(key, index, row) for key, rows in qa.items()
|
|
210
|
+
for index, row in enumerate(rows) if row.get("id") == candidate["id"]]
|
|
211
|
+
if found:
|
|
212
|
+
old_category, index, old = found[0]
|
|
213
|
+
if expected_digest != canonical_json_digest(old):
|
|
214
|
+
raise ValueError(
|
|
215
|
+
"existing QA entry digest mismatch; refresh before updating"
|
|
216
|
+
)
|
|
217
|
+
if category != old_category:
|
|
218
|
+
raise ValueError("registration cannot move an id to another category")
|
|
219
|
+
candidate = {**old, **candidate}
|
|
220
|
+
qa[category][index] = candidate
|
|
221
|
+
else:
|
|
222
|
+
if expected_digest is not None:
|
|
223
|
+
raise ValueError(
|
|
224
|
+
"expected QA entry digest supplied but id does not exist"
|
|
225
|
+
)
|
|
226
|
+
qa.setdefault(category, []).append(candidate)
|
|
227
|
+
errors = validate_qa_commands(qa)
|
|
228
|
+
if errors:
|
|
229
|
+
raise ValueError("; ".join(errors))
|
|
230
|
+
if external:
|
|
231
|
+
_store_procedure(project, candidate["procedurePath"], raw)
|
|
232
|
+
write_owned_object_atomic(
|
|
233
|
+
project_json_path(project), config, artifact="project config"
|
|
234
|
+
)
|
|
235
|
+
return canonical_json_digest(candidate)
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from ..adapters.verification_inputs import JsonVerificationInputStore
|
|
4
|
+
from ..ports.verification_inputs import VerificationInputStore
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
def default_verification_input_store() -> VerificationInputStore:
|
|
8
|
+
return JsonVerificationInputStore()
|
|
@@ -48,6 +48,9 @@ from .ports.worker_dispatch import WorkerDispatchRequest
|
|
|
48
48
|
from .registry.host_registry import default_host_registry
|
|
49
49
|
from .registry.provider_registry import default_provider_registry
|
|
50
50
|
from .path_hints import compact_active_run_context, hydrate_run_context
|
|
51
|
+
from .verification_input_ref import (
|
|
52
|
+
VerificationInputReference, artifact_fields, retain_recorded_reference,
|
|
53
|
+
)
|
|
51
54
|
from .paths import task_timeline_file
|
|
52
55
|
from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
|
|
53
56
|
from .mcp_servers import load_declarations as load_mcp_declarations
|
|
@@ -1709,7 +1712,13 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
|
|
|
1709
1712
|
else {}
|
|
1710
1713
|
)
|
|
1711
1714
|
except JsonBoundaryError:
|
|
1715
|
+
if VerificationInputReference.from_context(ctx) is not None:
|
|
1716
|
+
raise
|
|
1712
1717
|
existing_run_manifest = {}
|
|
1718
|
+
manifest_input_ref = retain_recorded_reference(
|
|
1719
|
+
existing_run_manifest if run_manifest_exists else None,
|
|
1720
|
+
VerificationInputReference.from_context(ctx),
|
|
1721
|
+
)
|
|
1713
1722
|
task_manifest_path = Path(ctx.get("TASK_MANIFEST_PATH", ""))
|
|
1714
1723
|
task_manifest = {}
|
|
1715
1724
|
if task_manifest_path.exists():
|
|
@@ -1855,6 +1864,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
|
|
|
1855
1864
|
"verificationTargetPath": ctx.get("VERIFICATION_TARGET_RELATIVE_PATH", ""),
|
|
1856
1865
|
"verificationTargetDigest": ctx.get("VERIFICATION_TARGET_DIGEST", ""),
|
|
1857
1866
|
"workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
|
|
1867
|
+
**artifact_fields(manifest_input_ref),
|
|
1858
1868
|
"reportTemplatePath": ctx.get("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""),
|
|
1859
1869
|
"validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
|
|
1860
1870
|
"leadSessionId": ctx.get("CLAUDE_SESSION_ID", ""),
|