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.
Files changed (76) hide show
  1. package/README.md +1 -1
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/docs/architecture/storage-model.md +77 -0
  5. package/docs/cli.md +15 -3
  6. package/docs/project-structure-overview.md +12 -2
  7. package/package.json +1 -1
  8. package/runtime/BUILD.json +2 -2
  9. package/runtime/prompts/coding-preflight/clean-code.md +24 -18
  10. package/runtime/prompts/coding-preflight/overview.md +6 -6
  11. package/runtime/prompts/duties/code-reviewer.json +1 -0
  12. package/runtime/prompts/lead/convergence.md +5 -19
  13. package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
  14. package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
  15. package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
  16. package/runtime/python/okstra_ctl/adapters/worker_defaults.py +2 -2
  17. package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
  18. package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
  19. package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
  20. package/runtime/python/okstra_ctl/brief_sources.py +162 -44
  21. package/runtime/python/okstra_ctl/code_review_coverage.py +11 -1
  22. package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
  23. package/runtime/python/okstra_ctl/code_review_target.py +46 -10
  24. package/runtime/python/okstra_ctl/conformance.py +9 -3
  25. package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
  26. package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
  27. package/runtime/python/okstra_ctl/fixed_text.py +31 -9
  28. package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
  29. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
  30. package/runtime/python/okstra_ctl/json_registry.py +3 -18
  31. package/runtime/python/okstra_ctl/manager_split.py +201 -84
  32. package/runtime/python/okstra_ctl/model_io/references.py +31 -1
  33. package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
  34. package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
  35. package/runtime/python/okstra_ctl/path_hints.py +13 -1
  36. package/runtime/python/okstra_ctl/paths.py +4 -0
  37. package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
  38. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
  39. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
  40. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
  41. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +3 -1
  42. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +3 -1
  43. package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
  44. package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
  45. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  46. package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
  47. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  48. package/runtime/python/okstra_ctl/plan_items.py +9 -11
  49. package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
  50. package/runtime/python/okstra_ctl/prior_planning.py +6 -17
  51. package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
  52. package/runtime/python/okstra_ctl/qa_commands.py +66 -1
  53. package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
  54. package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
  55. package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
  56. package/runtime/python/okstra_ctl/render.py +10 -0
  57. package/runtime/python/okstra_ctl/report_assembly.py +12 -12
  58. package/runtime/python/okstra_ctl/run.py +108 -5
  59. package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
  60. package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
  61. package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
  62. package/runtime/python/okstra_ctl/verification_plan.py +116 -0
  63. package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
  64. package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
  65. package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
  66. package/runtime/python/okstra_project/dirs.py +22 -0
  67. package/runtime/python/okstra_project/resolver.py +10 -0
  68. package/runtime/schemas/final-report-v3.0.schema.json +5 -1
  69. package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
  70. package/runtime/skills/okstra-code-review/SKILL.md +39 -45
  71. package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
  72. package/runtime/skills/okstra-code-review/references/review-calibration.md +31 -8
  73. package/runtime/skills/okstra-manager/SKILL.md +2 -2
  74. package/runtime/skills/okstra-setup/SKILL.md +2 -0
  75. package/runtime/skills/okstra-setup/references/project-config.md +2 -0
  76. package/runtime/validators/validate-brief.py +21 -5
@@ -27,7 +27,10 @@ from .report_synthesis_packet import (
27
27
  )
28
28
  from .conformance import strip_stage_declaration_label
29
29
  from .coverage_census import census_warning_rows, read_census_state
30
- from .design_surfaces import DesignSurfaceError, detect_design_surfaces
30
+ from .design_surfaces import (
31
+ DesignSurfaceError,
32
+ detect_design_surfaces_in_unvalidated_plan,
33
+ )
31
34
  from .design_prep import (
32
35
  DesignPrepError,
33
36
  canonicalize_request_paths,
@@ -251,7 +254,7 @@ def _carried_clarification_row(source: Mapping[str, Any]) -> dict[str, Any]:
251
254
  key: source[key]
252
255
  for key in (
253
256
  "id", "ticketId", "kind", "statement", "expectedForm", "blocks",
254
- "origin", "userConfirmation", "userInput", "options",
257
+ "origin", "userConfirmation", "userInput", "options", "candidateRef",
255
258
  )
256
259
  if key in source
257
260
  }
@@ -440,7 +443,7 @@ def _clarification_row(
440
443
  key: source[key]
441
444
  for key in (
442
445
  "id", "ticketId", "kind", "statement", "expectedForm", "blocks",
443
- "origin", "userConfirmation", "options",
446
+ "origin", "userConfirmation", "options", "candidateRef",
444
447
  )
445
448
  if key in source
446
449
  }
@@ -697,18 +700,15 @@ def validate_plan_draft(
697
700
 
698
701
 
699
702
  def _design_surface_errors(draft: Mapping[str, Any]) -> list[str]:
700
- """`plan-items prepare` 가 돌릴 설계 표면 탐지기를 초안 단계에서 미리 돌린다.
703
+ """Run the design-surface detector that `plan-items prepare` runs, on the draft.
701
704
 
702
- 탐지 실패는 서사를 고쳐야 풀리는데, 교정 원장 대조가 이를 몰라 ok 를 낸 뒤
703
- prepare 에서야 드러났다.
705
+ Only a narrative edit resolves a detection failure, so it must surface in the
706
+ draft check, where the writer can still correct it in the same run.
704
707
  """
705
- planning = draft.get("implementationPlanning")
706
- if not isinstance(planning, Mapping) or not planning.get("stages"):
707
- return []
708
708
  try:
709
- detect_design_surfaces(planning)
710
- except (DesignSurfaceError, TypeError, AttributeError) as exc:
711
- return [f"implementationPlanning: design-surface detection failed: {exc}"]
709
+ detect_design_surfaces_in_unvalidated_plan(draft.get("implementationPlanning"))
710
+ except DesignSurfaceError as exc:
711
+ return [f"implementationPlanning: {exc}"]
712
712
  return []
713
713
 
714
714
 
@@ -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 format_errors as _format_qa_errors, validate_qa_commands
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
@@ -1648,9 +1660,6 @@ def _validate_analysis_prepare_inputs(project_root: Path, inp: PrepareInputs) ->
1648
1660
 
1649
1661
 
1650
1662
 
1651
- QA_COMMAND_EXECUTING_TASK_TYPES = ("implementation", "final-verification")
1652
-
1653
-
1654
1663
  def validate_project_qa_commands(task_type: str, project_root: Path) -> None:
1655
1664
  """`qaCommands` 를 실행하는 phase 진입에서 변경성 토큰 선언을 막는다.
1656
1665
 
@@ -3386,6 +3395,99 @@ def _write_run_inputs_once(
3386
3395
  )
3387
3396
 
3388
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
+
3389
3491
  def _persist_pre_dispatch_run_manifest(ctx: dict) -> None:
3390
3492
  """Publish and re-read the complete invocation authority before prompts."""
3391
3493
  render_run_manifest(ctx["RUN_MANIFEST_PATH"], ctx)
@@ -4414,7 +4516,6 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
4414
4516
  project_root, assignment_plan, inp.brief_path,
4415
4517
  ),
4416
4518
  })
4417
- refresh_run_context_snapshot(ctx)
4418
4519
  if lead_runtime == "codex":
4419
4520
  ctx["CLAUDE_RESUME_COMMAND_PATH"] = ""
4420
4521
  ctx["CLAUDE_RESUME_COMMAND_RELATIVE_PATH"] = ""
@@ -4444,6 +4545,8 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
4444
4545
  _write_bundle_artifacts(
4445
4546
  inp, ctx, project_root, lead_runtime, claude_session_id,
4446
4547
  )
4548
+ _prepare_verification_input_reference(ctx, default_verification_input_store())
4549
+ refresh_run_context_snapshot(ctx)
4447
4550
  _prepare_agent_contract(inp, ctx, workspace_root, models)
4448
4551
 
4449
4552
  # ---- write instruction-set scaffolding ----
@@ -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)
@@ -72,14 +72,20 @@ def analysis_input_lines(
72
72
  # The packet already carries the brief extract, the reference
73
73
  # expectations, the profile prelude and the directive; the task brief,
74
74
  # analysis material, profile and reference files repeat them in full.
75
- # Measured 2026-10-30 (dev-11562): those four files were 1,929 lines
76
- # beside a 4,865-line packet. The clarification file stays: the
77
- # packet keeps only its extract, and a lazy-delivery prompt has no
78
- # inlined authority block.
75
+ # The clarification file stays: the packet keeps only its extract, and
76
+ # a lazy-delivery prompt has no inlined authority block.
79
77
  return existing_input_lines((
80
- ("Primary analysis packet", instruction_path(manifest, active_context, "analysisPacketPath")),
78
+ (
79
+ "Primary analysis packet",
80
+ instruction_path(manifest, active_context, "analysisPacketPath"),
81
+ ),
81
82
  ("Approved plan stage extract", stage_extract_path),
82
- ("Clarification response", instruction_path(manifest, active_context, "clarificationResponsePath")),
83
+ (
84
+ "Clarification response",
85
+ instruction_path(
86
+ manifest, active_context, "clarificationResponsePath"
87
+ ),
88
+ ),
83
89
  ))
84
90
  if plan.packet_only:
85
91
  packet_path = instruction_path(manifest, active_context, "analysisPacketPath")
@@ -25,7 +25,10 @@ from .worker_prompt_policy import (
25
25
  resolve_prompt_plan_for_manifest,
26
26
  verification_dispatch_round,
27
27
  )
28
- from .worker_prompt_headers import EVIDENCE_LEDGER_HEADER
28
+ from .worker_prompt_headers import (
29
+ EVIDENCE_LEDGER_HEADER,
30
+ VERIFICATION_INPUT_HEADER_PREFIXES,
31
+ )
29
32
 
30
33
 
31
34
  MAX_FINAL_VERIFICATION_DIRECTIVE_LINES = 40
@@ -76,6 +79,7 @@ _NON_BODY_PREFIXES = (
76
79
  "**Verification head ref:**",
77
80
  "**Verification target path:**",
78
81
  "**Verification target digest:**",
82
+ *VERIFICATION_INPUT_HEADER_PREFIXES,
79
83
  PROMPT_DELIVERY_MODE_HEADER,
80
84
  )
81
85
  _REQUIRED_TARGET_PREFIXES = (