okstra 0.226.0 → 0.228.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 +2 -1
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/wizard.mjs +12 -15
- package/dist/commands/execute/wizard.mjs.map +1 -1
- package/docs/architecture/storage-model.md +77 -0
- package/docs/cli.md +43 -7
- package/docs/project-structure-overview.md +13 -3
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/code-review.json +1 -1
- 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 +2 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
- package/runtime/prompts/wizard/prompts.ko.json +44 -0
- package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
- 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 +81 -19
- package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
- package/runtime/python/okstra_ctl/code_review_target.py +115 -55
- package/runtime/python/okstra_ctl/conformance.py +9 -3
- package/runtime/python/okstra_ctl/correction_cli.py +6 -5
- package/runtime/python/okstra_ctl/correction_round.py +1 -1
- package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
- package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
- package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
- 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-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +4 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +5 -3
- 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/authoring.py +22 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- 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/ports/worker_defaults.py +25 -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/registry/worker_defaults_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 +123 -6
- package/runtime/python/okstra_ctl/stage_done.py +5 -4
- 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/wizard/cli.py +16 -4
- package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
- package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
- package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
- package/runtime/python/okstra_ctl/wizard/render.py +2 -2
- package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
- package/runtime/python/okstra_ctl/wizard/state.py +55 -14
- package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
- package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
- package/runtime/python/okstra_ctl/worker_defaults.py +135 -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_ctl/write_policy.py +33 -18
- 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 +59 -63
- package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
- package/runtime/skills/okstra-code-review/references/review-calibration.md +32 -9
- package/runtime/skills/okstra-manager/SKILL.md +2 -2
- package/runtime/skills/okstra-run/SKILL.md +21 -1
- 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
|
@@ -95,7 +95,18 @@ from .implementation_direction import (
|
|
|
95
95
|
validate_task_artifact_path,
|
|
96
96
|
write_selected_direction_snapshot,
|
|
97
97
|
)
|
|
98
|
-
from .qa_commands import
|
|
98
|
+
from .qa_commands import (
|
|
99
|
+
QA_COMMAND_EXECUTING_TASK_TYPES,
|
|
100
|
+
format_errors as _format_qa_errors,
|
|
101
|
+
validate_qa_commands,
|
|
102
|
+
)
|
|
103
|
+
from .paths import RunRef
|
|
104
|
+
from .qa_procedures import safe_qa_path
|
|
105
|
+
from .verification_input_ref import (
|
|
106
|
+
VerificationInputReference, retain_recorded_reference,
|
|
107
|
+
)
|
|
108
|
+
from .ports.verification_inputs import VerificationInputStore
|
|
109
|
+
from .registry.verification_inputs_store import default_verification_input_store
|
|
99
110
|
from .material import (
|
|
100
111
|
build_analysis_material,
|
|
101
112
|
direct_work_context,
|
|
@@ -107,6 +118,7 @@ from .final_report_schema import load_schema_version
|
|
|
107
118
|
from .final_report_paths import (
|
|
108
119
|
final_report_data_path as _final_report_data_path,
|
|
109
120
|
final_report_markdown_path as _final_report_markdown_path,
|
|
121
|
+
is_report_record_path,
|
|
110
122
|
require_approved_plan_record as _require_approved_plan_record_path,
|
|
111
123
|
)
|
|
112
124
|
from .lead_events import LeadEvent, append_lead_event
|
|
@@ -164,6 +176,10 @@ from .models import (
|
|
|
164
176
|
from .schema_excerpt import build_schema_excerpt
|
|
165
177
|
from .registry.host_registry import default_host_registry
|
|
166
178
|
from .registry.provider_registry import default_provider_registry
|
|
179
|
+
from .model_pool import ModelPool
|
|
180
|
+
from .worker_defaults import apply_worker_defaults
|
|
181
|
+
from .domain.worker_defaults import role_uses_worker_defaults
|
|
182
|
+
from .registry.worker_defaults_store import default_worker_defaults_store
|
|
167
183
|
from .role_requirements import RoleProfile, RoleProfileError, load_role_profile
|
|
168
184
|
from .agent.invocation import (
|
|
169
185
|
AgentInstruction,
|
|
@@ -1644,9 +1660,6 @@ def _validate_analysis_prepare_inputs(project_root: Path, inp: PrepareInputs) ->
|
|
|
1644
1660
|
|
|
1645
1661
|
|
|
1646
1662
|
|
|
1647
|
-
QA_COMMAND_EXECUTING_TASK_TYPES = ("implementation", "final-verification")
|
|
1648
|
-
|
|
1649
|
-
|
|
1650
1663
|
def validate_project_qa_commands(task_type: str, project_root: Path) -> None:
|
|
1651
1664
|
"""`qaCommands` 를 실행하는 phase 진입에서 변경성 토큰 선언을 막는다.
|
|
1652
1665
|
|
|
@@ -1838,7 +1851,17 @@ def _normalize_prepare_model_selection(
|
|
|
1838
1851
|
"antigravity": inp.antigravity_model,
|
|
1839
1852
|
},
|
|
1840
1853
|
)
|
|
1841
|
-
|
|
1854
|
+
if any(
|
|
1855
|
+
role_uses_worker_defaults(row.role, row.dynamic, frozenset())
|
|
1856
|
+
for row in profile.roles
|
|
1857
|
+
):
|
|
1858
|
+
selection = apply_worker_defaults(
|
|
1859
|
+
selection,
|
|
1860
|
+
profile,
|
|
1861
|
+
default_worker_defaults_store().load_scopes(Path(inp.project_root)),
|
|
1862
|
+
ModelPool.from_registry(default_provider_registry()),
|
|
1863
|
+
)
|
|
1864
|
+
except (ModelSelectionInputError, RoleProfileError, ValueError) as exc:
|
|
1842
1865
|
raise PrepareError(str(exc)) from exc
|
|
1843
1866
|
return selection, profile
|
|
1844
1867
|
|
|
@@ -3372,6 +3395,99 @@ def _write_run_inputs_once(
|
|
|
3372
3395
|
)
|
|
3373
3396
|
|
|
3374
3397
|
|
|
3398
|
+
def _load_recorded_run_manifest_strict(
|
|
3399
|
+
project_root: Path, manifest_path: str,
|
|
3400
|
+
) -> dict[str, object] | None:
|
|
3401
|
+
relative = Path(manifest_path).relative_to(project_root).as_posix()
|
|
3402
|
+
manifest = safe_qa_path(project_root, relative)
|
|
3403
|
+
if not manifest.exists():
|
|
3404
|
+
return None
|
|
3405
|
+
return load_owned_object(manifest, artifact="run manifest")
|
|
3406
|
+
|
|
3407
|
+
|
|
3408
|
+
def _verification_input_source(
|
|
3409
|
+
ctx: dict, reference: VerificationInputReference | None,
|
|
3410
|
+
) -> Path | None:
|
|
3411
|
+
source_key = ("EXECUTOR_WORKTREE_PATH" if ctx["TASK_TYPE"] == "implementation"
|
|
3412
|
+
else "VERIFICATION_WORKTREE_PATH")
|
|
3413
|
+
source_path = ctx.get(source_key, "")
|
|
3414
|
+
if not source_path and reference is None:
|
|
3415
|
+
return None
|
|
3416
|
+
if not source_path or not Path(source_path).is_dir():
|
|
3417
|
+
raise ValueError("verification source worktree is unavailable")
|
|
3418
|
+
return Path(source_path).resolve()
|
|
3419
|
+
|
|
3420
|
+
|
|
3421
|
+
def _validate_recorded_verification_inputs(
|
|
3422
|
+
project_root: Path, source: Path, run_ref: RunRef,
|
|
3423
|
+
reference: VerificationInputReference, store: VerificationInputStore,
|
|
3424
|
+
approved_plan: Path | None,
|
|
3425
|
+
) -> None:
|
|
3426
|
+
expected_relative = run_ref.verification_inputs.relative_to(project_root).as_posix()
|
|
3427
|
+
if reference.relative_path != expected_relative:
|
|
3428
|
+
raise ValueError(
|
|
3429
|
+
f"verification input reference path {reference.relative_path!r} "
|
|
3430
|
+
f"does not match this run's {expected_relative!r}"
|
|
3431
|
+
)
|
|
3432
|
+
path = safe_qa_path(project_root, expected_relative)
|
|
3433
|
+
stored = store.read(path, reference.digest)
|
|
3434
|
+
if stored["sourceRoot"] != str(source):
|
|
3435
|
+
raise ValueError(
|
|
3436
|
+
"verification input source root does not match the selected worktree"
|
|
3437
|
+
)
|
|
3438
|
+
frozen_plan = stored.get("approvedPlan")
|
|
3439
|
+
if frozen_plan is not None:
|
|
3440
|
+
if approved_plan is None:
|
|
3441
|
+
raise ValueError(
|
|
3442
|
+
f"snapshot was frozen with approved plan {frozen_plan['path']!r}; "
|
|
3443
|
+
"no .data.json approved plan is selected"
|
|
3444
|
+
)
|
|
3445
|
+
selected = str(approved_plan.resolve())
|
|
3446
|
+
if frozen_plan["path"] != selected:
|
|
3447
|
+
raise ValueError(
|
|
3448
|
+
f"selected approved plan {selected!r} "
|
|
3449
|
+
f"does not match frozen {frozen_plan['path']!r}"
|
|
3450
|
+
)
|
|
3451
|
+
|
|
3452
|
+
|
|
3453
|
+
def _prepare_verification_input_reference(
|
|
3454
|
+
ctx: dict, store: VerificationInputStore,
|
|
3455
|
+
) -> None:
|
|
3456
|
+
if ctx["TASK_TYPE"] not in QA_COMMAND_EXECUTING_TASK_TYPES:
|
|
3457
|
+
return
|
|
3458
|
+
try:
|
|
3459
|
+
project_root = Path(ctx["PROJECT_ROOT"]).resolve()
|
|
3460
|
+
run_ref = RunRef.from_run_dir(
|
|
3461
|
+
Path(ctx["RUN_DIR"]), seq=int(ctx["RUN_MANIFESTS_SEQ"]),
|
|
3462
|
+
)
|
|
3463
|
+
recorded = _load_recorded_run_manifest_strict(
|
|
3464
|
+
project_root, ctx["RUN_MANIFEST_PATH"],
|
|
3465
|
+
)
|
|
3466
|
+
reference = retain_recorded_reference(
|
|
3467
|
+
recorded, VerificationInputReference.from_context(ctx),
|
|
3468
|
+
)
|
|
3469
|
+
if recorded is not None and reference is None:
|
|
3470
|
+
return
|
|
3471
|
+
source = _verification_input_source(ctx, reference)
|
|
3472
|
+
if source is None:
|
|
3473
|
+
return
|
|
3474
|
+
plan_path = ctx.get("APPROVED_PLAN_PATH")
|
|
3475
|
+
approved_plan = Path(plan_path) if plan_path else None
|
|
3476
|
+
if approved_plan is not None and not is_report_record_path(approved_plan):
|
|
3477
|
+
approved_plan = None
|
|
3478
|
+
if reference is None:
|
|
3479
|
+
reference = store.freeze(
|
|
3480
|
+
project_root, source, run_ref, approved_plan=approved_plan,
|
|
3481
|
+
)
|
|
3482
|
+
else:
|
|
3483
|
+
_validate_recorded_verification_inputs(
|
|
3484
|
+
project_root, source, run_ref, reference, store, approved_plan,
|
|
3485
|
+
)
|
|
3486
|
+
ctx.update(reference.to_context(project_root))
|
|
3487
|
+
except (OSError, ValueError) as exc:
|
|
3488
|
+
raise PrepareError(f"verification inputs preparation failed: {exc}") from exc
|
|
3489
|
+
|
|
3490
|
+
|
|
3375
3491
|
def _persist_pre_dispatch_run_manifest(ctx: dict) -> None:
|
|
3376
3492
|
"""Publish and re-read the complete invocation authority before prompts."""
|
|
3377
3493
|
render_run_manifest(ctx["RUN_MANIFEST_PATH"], ctx)
|
|
@@ -4400,7 +4516,6 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
|
|
|
4400
4516
|
project_root, assignment_plan, inp.brief_path,
|
|
4401
4517
|
),
|
|
4402
4518
|
})
|
|
4403
|
-
refresh_run_context_snapshot(ctx)
|
|
4404
4519
|
if lead_runtime == "codex":
|
|
4405
4520
|
ctx["CLAUDE_RESUME_COMMAND_PATH"] = ""
|
|
4406
4521
|
ctx["CLAUDE_RESUME_COMMAND_RELATIVE_PATH"] = ""
|
|
@@ -4430,6 +4545,8 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
|
|
|
4430
4545
|
_write_bundle_artifacts(
|
|
4431
4546
|
inp, ctx, project_root, lead_runtime, claude_session_id,
|
|
4432
4547
|
)
|
|
4548
|
+
_prepare_verification_input_reference(ctx, default_verification_input_store())
|
|
4549
|
+
refresh_run_context_snapshot(ctx)
|
|
4433
4550
|
_prepare_agent_contract(inp, ctx, workspace_root, models)
|
|
4434
4551
|
|
|
4435
4552
|
# ---- write instruction-set scaffolding ----
|
|
@@ -24,7 +24,7 @@ from .consumers import (
|
|
|
24
24
|
carry_head_commit,
|
|
25
25
|
read_consumers,
|
|
26
26
|
)
|
|
27
|
-
from .file_size_cap import file_size_violations
|
|
27
|
+
from .file_size_cap import FILE_LINE_LIMIT, file_size_violations
|
|
28
28
|
from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
|
|
29
29
|
from .paths import RunRef
|
|
30
30
|
from .stage_reopen import resolve_planned_stage
|
|
@@ -71,7 +71,7 @@ def _check_file_size(project_root: Path, carry: dict, head: str) -> str:
|
|
|
71
71
|
return f"not checked: git: {exc.stderr.decode(errors='replace').strip()}"
|
|
72
72
|
if violations:
|
|
73
73
|
raise StateError(
|
|
74
|
-
"the stage diff breaks the
|
|
74
|
+
f"the stage diff breaks the {FILE_LINE_LIMIT}-line file-size limit:\n"
|
|
75
75
|
+ "\n".join(v.line() for v in violations)
|
|
76
76
|
+ f"\nRun a correction round (`okstra correction prompt ... --base {head} "
|
|
77
77
|
f"--stage-base {base}`) so the executor splits these files, or end the run FAIL "
|
|
@@ -164,8 +164,9 @@ canonical sidecar `runs/implementation/carry/stage-<N>.json`, then appends the
|
|
|
164
164
|
the carry's head and the completion time. A reopened stage's previous sidecar
|
|
165
165
|
is moved to `carry/superseded/stage-<N>-from-<task-type>-<seq>.json` first.
|
|
166
166
|
Refuses a carry for another stage, a failed carry, a stage already done at
|
|
167
|
-
another head, and a carry whose stageCommitRange diff
|
|
168
|
-
|
|
167
|
+
another head, and a carry whose stageCommitRange diff adds a source or test file
|
|
168
|
+
over the 500-line limit or takes one past it (`okstra correction file-size`); a
|
|
169
|
+
file already over 500 at the stage base may grow. Re-running with the
|
|
169
170
|
same carry writes nothing new.
|
|
170
171
|
|
|
171
172
|
Output: JSON { ok, taskKey, stage, headCommit, carryPath, supersededCarryPath,
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from pathlib import Path, PurePosixPath
|
|
5
|
+
from typing import Mapping
|
|
6
|
+
|
|
7
|
+
from okstra_project.dirs import OKSTRA_DIR_NAME
|
|
8
|
+
|
|
9
|
+
from .qa_commands import qa_relative_path_valid
|
|
10
|
+
|
|
11
|
+
_ARTIFACT_PATH = "verificationInputsPath"
|
|
12
|
+
_ARTIFACT_DIGEST = "verificationInputsDigest"
|
|
13
|
+
_CONTEXT_PATH = "VERIFICATION_INPUTS_RELATIVE_PATH"
|
|
14
|
+
_CONTEXT_DIGEST = "VERIFICATION_INPUTS_DIGEST"
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
@dataclass(frozen=True)
|
|
18
|
+
class VerificationInputReference:
|
|
19
|
+
relative_path: str
|
|
20
|
+
digest: str
|
|
21
|
+
|
|
22
|
+
@classmethod
|
|
23
|
+
def from_artifact_fields(
|
|
24
|
+
cls, payload: Mapping[str, object],
|
|
25
|
+
) -> VerificationInputReference | None:
|
|
26
|
+
return cls._read(payload, _ARTIFACT_PATH, _ARTIFACT_DIGEST)
|
|
27
|
+
|
|
28
|
+
@classmethod
|
|
29
|
+
def from_context(
|
|
30
|
+
cls, context: Mapping[str, object],
|
|
31
|
+
) -> VerificationInputReference | None:
|
|
32
|
+
return cls._read(context, _CONTEXT_PATH, _CONTEXT_DIGEST)
|
|
33
|
+
|
|
34
|
+
@classmethod
|
|
35
|
+
def _read(
|
|
36
|
+
cls, payload: Mapping[str, object], path_key: str, digest_key: str,
|
|
37
|
+
) -> VerificationInputReference | None:
|
|
38
|
+
if path_key not in payload and digest_key not in payload:
|
|
39
|
+
return None
|
|
40
|
+
relative_path = payload.get(path_key)
|
|
41
|
+
digest = payload.get(digest_key)
|
|
42
|
+
if (not isinstance(relative_path, str)
|
|
43
|
+
or not qa_relative_path_valid(relative_path)
|
|
44
|
+
or PurePosixPath(relative_path).parts[0] != OKSTRA_DIR_NAME
|
|
45
|
+
or not isinstance(digest, str) or not digest.strip()):
|
|
46
|
+
raise ValueError(
|
|
47
|
+
"verification input reference requires a project-artifact path "
|
|
48
|
+
"and a non-blank digest"
|
|
49
|
+
)
|
|
50
|
+
return cls(relative_path, digest)
|
|
51
|
+
|
|
52
|
+
def to_artifact_fields(self) -> dict[str, str]:
|
|
53
|
+
return {_ARTIFACT_PATH: self.relative_path, _ARTIFACT_DIGEST: self.digest}
|
|
54
|
+
|
|
55
|
+
def to_context(self, project_root: Path) -> dict[str, str]:
|
|
56
|
+
return {
|
|
57
|
+
_CONTEXT_PATH: self.relative_path,
|
|
58
|
+
_CONTEXT_DIGEST: self.digest,
|
|
59
|
+
"VERIFICATION_INPUTS_PATH": str(project_root / self.relative_path),
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def artifact_fields(ref: VerificationInputReference | None) -> dict[str, str]:
|
|
64
|
+
return ref.to_artifact_fields() if ref is not None else {}
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def artifact_fields_from_context(context: Mapping[str, object]) -> dict[str, str]:
|
|
68
|
+
return artifact_fields(VerificationInputReference.from_context(context))
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def retain_recorded_reference(
|
|
72
|
+
recorded_manifest: Mapping[str, object] | None,
|
|
73
|
+
provided: VerificationInputReference | None,
|
|
74
|
+
) -> VerificationInputReference | None:
|
|
75
|
+
recorded = VerificationInputReference.from_artifact_fields(recorded_manifest or {})
|
|
76
|
+
if recorded_manifest is not None and recorded is None and provided is not None:
|
|
77
|
+
raise ValueError("recorded run manifest has no verification input reference")
|
|
78
|
+
if (recorded is not None and provided is not None and recorded != provided):
|
|
79
|
+
raise ValueError("verification input reference is immutable")
|
|
80
|
+
return recorded or provided
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from typing import Any, Literal, TypedDict
|
|
4
|
+
|
|
5
|
+
INPUT_SCHEMA_VERSION: Literal["1.0"] = "1.0"
|
|
6
|
+
INPUT_KIND: Literal["verification-inputs"] = "verification-inputs"
|
|
7
|
+
PLAN_INPUT_SCHEMA_VERSION: Literal["2.0"] = "2.0"
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class FrozenProcedure(TypedDict):
|
|
11
|
+
body: str
|
|
12
|
+
digest: str
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class FrozenVerificationPlan(TypedDict):
|
|
16
|
+
path: str
|
|
17
|
+
digest: str
|
|
18
|
+
reportSchemaVersion: Literal["2.0", "3.0"]
|
|
19
|
+
validationChecklist: list[dict[str, Any]]
|
|
20
|
+
conformance: list[dict[str, Any]]
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class _OptionalVerificationPlan(TypedDict, total=False):
|
|
24
|
+
approvedPlan: FrozenVerificationPlan
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class VerificationInputs(_OptionalVerificationPlan):
|
|
28
|
+
schemaVersion: Literal["1.0", "2.0"]
|
|
29
|
+
kind: Literal["verification-inputs"]
|
|
30
|
+
sourceRoot: str
|
|
31
|
+
qaCommands: dict[str, list[dict[str, Any]]]
|
|
32
|
+
procedures: dict[str, FrozenProcedure]
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
"""Preparation must allow inspection scripts that implementation creates later."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from typing import Any, Mapping, cast
|
|
6
|
+
|
|
7
|
+
from okstra_project.dirs import OKSTRA_DIR_NAME, json_lock_path, registry_lock
|
|
8
|
+
|
|
9
|
+
from .json_boundary import load_owned_object_snapshot, write_owned_object_atomic
|
|
10
|
+
from .paths import RunRef
|
|
11
|
+
from .qa_commands import QA_COMMAND_EXECUTING_TASK_TYPES, validate_qa_commands
|
|
12
|
+
from .qa_procedures import (
|
|
13
|
+
content_digest, existing_qa_file, load_qa_config, procedure_root,
|
|
14
|
+
read_validated_procedure, safe_qa_path, validate_procedure_sections,
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
from .verification_input_types import (
|
|
18
|
+
INPUT_KIND, INPUT_SCHEMA_VERSION, PLAN_INPUT_SCHEMA_VERSION,
|
|
19
|
+
FrozenProcedure, VerificationInputs,
|
|
20
|
+
)
|
|
21
|
+
from .verification_plan import (
|
|
22
|
+
VERIFICATION_PLAN_SCHEMA, capture_verification_plan, verification_plan_errors,
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
INPUT_ARTIFACT = "verification inputs"
|
|
26
|
+
QA_INPUT_FIELDS = (
|
|
27
|
+
"label", "cmd", "id", "procedurePath", "sourcePaths", "resourceKeys",
|
|
28
|
+
"sourceBaselineDigest",
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
INPUT_SCHEMA = {
|
|
33
|
+
"type": "object",
|
|
34
|
+
"additionalProperties": False,
|
|
35
|
+
"required": ["schemaVersion", "kind", "sourceRoot", "qaCommands", "procedures"],
|
|
36
|
+
"properties": {
|
|
37
|
+
"schemaVersion": {"enum": [INPUT_SCHEMA_VERSION, PLAN_INPUT_SCHEMA_VERSION]},
|
|
38
|
+
"kind": {"const": INPUT_KIND},
|
|
39
|
+
"sourceRoot": {"type": "string", "minLength": 1},
|
|
40
|
+
"qaCommands": {"type": "object"},
|
|
41
|
+
"procedures": {"type": "object"},
|
|
42
|
+
"approvedPlan": VERIFICATION_PLAN_SCHEMA,
|
|
43
|
+
},
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _procedure_paths(commands: Mapping[str, list[dict[str, Any]]]) -> tuple[str, ...]:
|
|
48
|
+
return tuple(dict.fromkeys(
|
|
49
|
+
entry["procedurePath"]
|
|
50
|
+
for entries in commands.values()
|
|
51
|
+
for entry in entries
|
|
52
|
+
if entry.get("procedurePath")
|
|
53
|
+
))
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _verification_input_errors(payload: dict[str, Any]) -> list[str]:
|
|
57
|
+
has_plan = "approvedPlan" in payload
|
|
58
|
+
if payload["schemaVersion"] == PLAN_INPUT_SCHEMA_VERSION and not has_plan:
|
|
59
|
+
return ["verification inputs 2.0 requires approvedPlan"]
|
|
60
|
+
if payload["schemaVersion"] == INPUT_SCHEMA_VERSION and has_plan:
|
|
61
|
+
return ["legacy verification inputs must not contain approvedPlan"]
|
|
62
|
+
if has_plan:
|
|
63
|
+
errors = verification_plan_errors(payload["approvedPlan"])
|
|
64
|
+
if errors:
|
|
65
|
+
return errors
|
|
66
|
+
commands = payload["qaCommands"]
|
|
67
|
+
errors = validate_qa_commands(commands)
|
|
68
|
+
if errors:
|
|
69
|
+
return errors
|
|
70
|
+
if any(set(entry).difference(QA_INPUT_FIELDS)
|
|
71
|
+
for entries in commands.values() for entry in entries):
|
|
72
|
+
errors.append("unsupported QA declaration fields in verification inputs")
|
|
73
|
+
if not Path(payload["sourceRoot"]).is_absolute():
|
|
74
|
+
errors.append("verification source root must be absolute")
|
|
75
|
+
procedures = payload["procedures"]
|
|
76
|
+
if set(_procedure_paths(commands)) != set(procedures):
|
|
77
|
+
errors.append("frozen procedure references must match qaCommands")
|
|
78
|
+
for relative, procedure in procedures.items():
|
|
79
|
+
if (not isinstance(procedure, dict)
|
|
80
|
+
or set(procedure) != {"body", "digest"}
|
|
81
|
+
or not all(isinstance(value, str) for value in procedure.values())):
|
|
82
|
+
errors.append(
|
|
83
|
+
f"invalid frozen procedure {relative}: expected body and digest strings"
|
|
84
|
+
)
|
|
85
|
+
continue
|
|
86
|
+
try:
|
|
87
|
+
raw = procedure["body"].encode("utf-8")
|
|
88
|
+
validate_procedure_sections(raw)
|
|
89
|
+
except ValueError as exc:
|
|
90
|
+
errors.append(f"invalid frozen procedure {relative}: {exc}")
|
|
91
|
+
continue
|
|
92
|
+
if content_digest(raw) != procedure["digest"]:
|
|
93
|
+
errors.append(f"frozen procedure digest mismatch: {relative}")
|
|
94
|
+
return errors
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def capture_verification_inputs(
|
|
98
|
+
project: Path, source: Path, *, approved_plan: Path | None = None,
|
|
99
|
+
) -> VerificationInputs:
|
|
100
|
+
declared = load_qa_config(project).get("qaCommands") or {}
|
|
101
|
+
commands = {
|
|
102
|
+
category: [{key: entry[key] for key in QA_INPUT_FIELDS if key in entry}
|
|
103
|
+
for entry in entries]
|
|
104
|
+
for category, entries in declared.items()
|
|
105
|
+
}
|
|
106
|
+
procedures: dict[str, FrozenProcedure] = {}
|
|
107
|
+
for relative in _procedure_paths(commands):
|
|
108
|
+
root = procedure_root(project, source, relative)
|
|
109
|
+
try:
|
|
110
|
+
raw = read_validated_procedure(existing_qa_file(root, relative))
|
|
111
|
+
except (OSError, ValueError) as exc:
|
|
112
|
+
raise ValueError(f"verification procedure {relative}: {exc}") from exc
|
|
113
|
+
procedures[relative] = {
|
|
114
|
+
"body": raw.decode("utf-8"), "digest": content_digest(raw),
|
|
115
|
+
}
|
|
116
|
+
payload: VerificationInputs = {
|
|
117
|
+
"schemaVersion": INPUT_SCHEMA_VERSION, "kind": INPUT_KIND,
|
|
118
|
+
"sourceRoot": str(source.resolve()), "qaCommands": commands,
|
|
119
|
+
"procedures": procedures,
|
|
120
|
+
}
|
|
121
|
+
if approved_plan is not None:
|
|
122
|
+
payload["schemaVersion"] = PLAN_INPUT_SCHEMA_VERSION
|
|
123
|
+
payload["approvedPlan"] = capture_verification_plan(approved_plan)
|
|
124
|
+
return payload
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def read_verification_inputs(path: Path, expected_digest: str) -> VerificationInputs:
|
|
128
|
+
snapshot = load_owned_object_snapshot(
|
|
129
|
+
path, artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
|
|
130
|
+
validate_cross_fields=_verification_input_errors,
|
|
131
|
+
)
|
|
132
|
+
if content_digest(snapshot.raw_bytes) != expected_digest:
|
|
133
|
+
raise ValueError("verification input digest mismatch")
|
|
134
|
+
return cast(VerificationInputs, snapshot.value)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def prepare_verification_inputs(
|
|
138
|
+
project: Path, source: Path, ref: RunRef, *, approved_plan: Path | None = None,
|
|
139
|
+
) -> tuple[Path, str]:
|
|
140
|
+
if ref.task_type not in QA_COMMAND_EXECUTING_TASK_TYPES:
|
|
141
|
+
raise ValueError("verification inputs require a QA-executing phase")
|
|
142
|
+
destination = ref.verification_inputs.absolute()
|
|
143
|
+
project_root = project.absolute()
|
|
144
|
+
if not destination.is_relative_to(project_root / OKSTRA_DIR_NAME):
|
|
145
|
+
raise ValueError("verification inputs must remain in the project artifact tree")
|
|
146
|
+
artifact_relative = destination.relative_to(project_root)
|
|
147
|
+
path = safe_qa_path(project, artifact_relative.as_posix())
|
|
148
|
+
lock = safe_qa_path(project, json_lock_path(artifact_relative).as_posix())
|
|
149
|
+
payload = capture_verification_inputs(project, source, approved_plan=approved_plan)
|
|
150
|
+
with registry_lock(lock):
|
|
151
|
+
if not path.exists():
|
|
152
|
+
write_owned_object_atomic(
|
|
153
|
+
path, payload, artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
|
|
154
|
+
validate_cross_fields=_verification_input_errors,
|
|
155
|
+
)
|
|
156
|
+
snapshot = load_owned_object_snapshot(
|
|
157
|
+
path, artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
|
|
158
|
+
validate_cross_fields=_verification_input_errors,
|
|
159
|
+
)
|
|
160
|
+
if snapshot.value != payload:
|
|
161
|
+
raise ValueError("verification input snapshot is immutable")
|
|
162
|
+
return path, content_digest(snapshot.raw_bytes)
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
from typing import Any, cast
|
|
5
|
+
|
|
6
|
+
from .conformance import CAPABILITY_WHITELIST, parse_conformance_tests
|
|
7
|
+
from .final_report_paths import is_report_record_path, require_approved_plan_record
|
|
8
|
+
from .final_report_schema import json_schema_number_key, load_schema_version, validate
|
|
9
|
+
from .json_boundary import load_owned_object_snapshot
|
|
10
|
+
from .qa_procedures import content_digest
|
|
11
|
+
from .verification_input_types import FrozenVerificationPlan
|
|
12
|
+
|
|
13
|
+
VERIFICATION_PLAN_SCHEMA = {
|
|
14
|
+
"type": "object", "additionalProperties": False,
|
|
15
|
+
"required": ["path", "digest", "reportSchemaVersion",
|
|
16
|
+
"validationChecklist", "conformance"],
|
|
17
|
+
"properties": {
|
|
18
|
+
"path": {"type": "string", "minLength": 1},
|
|
19
|
+
"digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
|
|
20
|
+
"reportSchemaVersion": {"enum": ["2.0", "3.0"]},
|
|
21
|
+
"validationChecklist": {"type": "array"},
|
|
22
|
+
"conformance": {"type": "array", "items": {
|
|
23
|
+
"type": "object", "additionalProperties": False,
|
|
24
|
+
"required": ["stage"],
|
|
25
|
+
"properties": {
|
|
26
|
+
"stage": {"type": "integer", "minimum": 1},
|
|
27
|
+
"script": {"type": "string", "minLength": 1},
|
|
28
|
+
"requires": {"type": "array", "minItems": 1,
|
|
29
|
+
"uniqueItems": True,
|
|
30
|
+
"items": {"enum": list(CAPABILITY_WHITELIST)}},
|
|
31
|
+
"exemption": {"type": "string", "minLength": 1},
|
|
32
|
+
},
|
|
33
|
+
"oneOf": [
|
|
34
|
+
{"required": ["script", "requires"],
|
|
35
|
+
"not": {"required": ["exemption"]}},
|
|
36
|
+
{"required": ["exemption"],
|
|
37
|
+
"properties": {"script": False, "requires": False}},
|
|
38
|
+
],
|
|
39
|
+
}},
|
|
40
|
+
},
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def verification_plan_errors(plan: dict[str, Any]) -> list[str]:
|
|
45
|
+
errors = validate(plan, VERIFICATION_PLAN_SCHEMA)
|
|
46
|
+
if errors:
|
|
47
|
+
return errors
|
|
48
|
+
if not Path(plan["path"]).is_absolute():
|
|
49
|
+
return ["approved plan path must be absolute"]
|
|
50
|
+
if not is_report_record_path(Path(plan["path"])):
|
|
51
|
+
return ["approved plan path must name a .data.json record"]
|
|
52
|
+
report_schema = load_schema_version(plan["reportSchemaVersion"])
|
|
53
|
+
errors = validate(plan["validationChecklist"], {
|
|
54
|
+
"$defs": report_schema["$defs"], "type": "array",
|
|
55
|
+
"items": {"$ref": "#/$defs/ValidationCheckRow"},
|
|
56
|
+
})
|
|
57
|
+
if errors:
|
|
58
|
+
return errors
|
|
59
|
+
ids = [row["id"] for row in plan["validationChecklist"]]
|
|
60
|
+
stage_keys = [json_schema_number_key(row["stage"]) for row in plan["conformance"]]
|
|
61
|
+
if len(ids) != len(set(ids)):
|
|
62
|
+
errors.append("duplicate validation check identity in approved plan")
|
|
63
|
+
if len(stage_keys) != len(set(stage_keys)):
|
|
64
|
+
errors.append("duplicate conformance stage in approved plan")
|
|
65
|
+
for row in plan["conformance"]:
|
|
66
|
+
if "script" in row:
|
|
67
|
+
parsed = parse_conformance_tests(
|
|
68
|
+
f"{row['script']} (requires=[{','.join(row['requires'])}])"
|
|
69
|
+
)
|
|
70
|
+
if parsed is None or parsed[0] != row["script"]:
|
|
71
|
+
errors.append("invalid frozen conformance script declaration")
|
|
72
|
+
elif not row["exemption"].strip():
|
|
73
|
+
errors.append("frozen conformance exemption must be non-blank")
|
|
74
|
+
return errors
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _conformance_expectations(stages: object) -> list[dict[str, Any]]:
|
|
78
|
+
if not isinstance(stages, list):
|
|
79
|
+
raise ValueError("approved plan stages must be an array")
|
|
80
|
+
rows: list[dict[str, Any]] = []
|
|
81
|
+
for stage in stages:
|
|
82
|
+
if not isinstance(stage, dict):
|
|
83
|
+
raise ValueError("approved plan stage must be an object")
|
|
84
|
+
if "conformanceTests" in stage and "conformanceExemption" in stage:
|
|
85
|
+
raise ValueError(
|
|
86
|
+
"approved plan conformance declares both test and exemption"
|
|
87
|
+
)
|
|
88
|
+
if "conformanceTests" in stage:
|
|
89
|
+
parsed = parse_conformance_tests(stage["conformanceTests"])
|
|
90
|
+
if parsed is None:
|
|
91
|
+
raise ValueError("approved plan has malformed conformanceTests")
|
|
92
|
+
script, requires = parsed
|
|
93
|
+
rows.append({"stage": stage.get("stage"), "script": script,
|
|
94
|
+
"requires": sorted(requires)})
|
|
95
|
+
elif "conformanceExemption" in stage:
|
|
96
|
+
rows.append({"stage": stage.get("stage"),
|
|
97
|
+
"exemption": stage["conformanceExemption"]})
|
|
98
|
+
return rows
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def capture_verification_plan(path: Path) -> FrozenVerificationPlan:
|
|
102
|
+
path = require_approved_plan_record(path).resolve()
|
|
103
|
+
snapshot = load_owned_object_snapshot(path, artifact="approved verification plan")
|
|
104
|
+
planning = snapshot.value.get("implementationPlanning")
|
|
105
|
+
if not isinstance(planning, dict):
|
|
106
|
+
raise ValueError("approved plan has no implementationPlanning object")
|
|
107
|
+
plan = {
|
|
108
|
+
"path": str(path), "digest": content_digest(snapshot.raw_bytes),
|
|
109
|
+
"reportSchemaVersion": snapshot.value.get("schemaVersion"),
|
|
110
|
+
"validationChecklist": planning.get("validationChecklist", []),
|
|
111
|
+
"conformance": _conformance_expectations(planning.get("stages", [])),
|
|
112
|
+
}
|
|
113
|
+
errors = verification_plan_errors(plan)
|
|
114
|
+
if errors:
|
|
115
|
+
raise ValueError(f"approved verification plan: {errors[0]}")
|
|
116
|
+
return cast(FrozenVerificationPlan, plan)
|
|
@@ -41,8 +41,9 @@ def main(argv: list[str]) -> int:
|
|
|
41
41
|
p_init = sub.add_parser("init")
|
|
42
42
|
p_init.add_argument("--state-file", required=True)
|
|
43
43
|
p_init.add_argument("--workspace-root", required=True)
|
|
44
|
-
p_init.add_argument("--project-root",
|
|
45
|
-
p_init.add_argument("--project-id",
|
|
44
|
+
p_init.add_argument("--project-root", default="")
|
|
45
|
+
p_init.add_argument("--project-id", default="")
|
|
46
|
+
p_init.add_argument("--worker-settings", action="store_true")
|
|
46
47
|
p_init.add_argument("--preferred-task-key", default="")
|
|
47
48
|
p_init.add_argument(
|
|
48
49
|
"--task-type",
|
|
@@ -84,6 +85,8 @@ def main(argv: list[str]) -> int:
|
|
|
84
85
|
state_path = Path(args.state_file)
|
|
85
86
|
|
|
86
87
|
if args.cmd == "init":
|
|
88
|
+
if not args.worker_settings and not (args.project_root and args.project_id):
|
|
89
|
+
parser.error("init requires --project-root and --project-id")
|
|
87
90
|
state = init_state(
|
|
88
91
|
workspace_root=args.workspace_root,
|
|
89
92
|
project_root=args.project_root,
|
|
@@ -93,10 +96,19 @@ def main(argv: list[str]) -> int:
|
|
|
93
96
|
host_runtime=args.host_runtime,
|
|
94
97
|
host_entry_mode=args.entry_mode,
|
|
95
98
|
available_functions=args.available_function,
|
|
99
|
+
worker_settings=args.worker_settings,
|
|
96
100
|
)
|
|
97
|
-
save_state_file(state_path, state)
|
|
98
101
|
first = next_prompt(state)
|
|
99
|
-
|
|
102
|
+
save_state_file(state_path, state)
|
|
103
|
+
result = {"ok": True, "next": prompt_payload(state, first)}
|
|
104
|
+
if args.worker_settings:
|
|
105
|
+
result["relayContract"] = (
|
|
106
|
+
default_host_registry()
|
|
107
|
+
.resolve(state.host_runtime)
|
|
108
|
+
.descriptor.relay_contract
|
|
109
|
+
)
|
|
110
|
+
result["runtime"] = state.host_runtime
|
|
111
|
+
print(json.dumps(result,
|
|
100
112
|
ensure_ascii=False, indent=2))
|
|
101
113
|
return 0
|
|
102
114
|
|