okstra 0.229.0 → 0.230.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.
Files changed (119) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +105 -16
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +11 -18
  12. package/package.json +1 -2
  13. package/runtime/BUILD.json +2 -2
  14. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  15. package/runtime/prompts/launch.template.md +5 -5
  16. package/runtime/prompts/lead/convergence.md +4 -4
  17. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  18. package/runtime/prompts/lead/phase-routing.md +1 -1
  19. package/runtime/prompts/lead/report-writer.md +3 -3
  20. package/runtime/prompts/lead/team-contract.md +3 -3
  21. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  22. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  23. package/runtime/python/okstra_ctl/cmux.py +4 -2
  24. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  25. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  26. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  27. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  28. package/runtime/python/okstra_ctl/conformance.py +30 -0
  29. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  30. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  31. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  32. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  33. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  34. package/runtime/python/okstra_ctl/ids.py +1 -41
  35. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  36. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  37. package/runtime/python/okstra_ctl/locks.py +28 -1
  38. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  39. package/runtime/python/okstra_ctl/paths.py +75 -33
  40. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  41. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  42. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  43. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  44. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  45. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  46. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  47. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  48. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  49. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  50. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  51. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  52. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  53. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  54. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  55. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  56. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  57. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  58. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  59. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  63. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  64. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  66. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  67. package/runtime/python/okstra_ctl/process_group.py +26 -3
  68. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  69. package/runtime/python/okstra_ctl/recap.py +1 -2
  70. package/runtime/python/okstra_ctl/render.py +10 -2
  71. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  72. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  73. package/runtime/python/okstra_ctl/run.py +24 -20
  74. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  75. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  76. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  77. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  78. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  79. package/runtime/python/okstra_ctl/verification_generation.py +22 -12
  80. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  81. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  82. package/runtime/python/okstra_ctl/verification_inputs.py +73 -2
  83. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  84. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  85. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  86. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  87. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  88. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  89. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  90. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  91. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  92. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  93. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  94. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  95. package/runtime/skills/okstra-run/SKILL.md +6 -6
  96. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  97. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  98. package/runtime/validators/validate-run.py +110 -19
  99. package/docs/cli.md +0 -1060
  100. package/docs/container.md +0 -100
  101. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  102. package/docs/performance-improvement-plan-v2.md +0 -369
  103. package/runtime/python/okstra_ctl/container.py +0 -702
  104. package/runtime/python/okstra_ctl/rollup.py +0 -241
  105. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  106. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  107. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  108. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  109. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  110. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  111. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  112. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  113. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  114. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  115. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  116. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  117. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  118. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  119. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -1,7 +1,6 @@
1
1
  """Immutable source and inspection-file seals for verification generations."""
2
2
  from __future__ import annotations
3
3
 
4
- from dataclasses import replace
5
4
  from functools import partial
6
5
  from itertools import pairwise
7
6
  from pathlib import Path, PurePosixPath
@@ -21,7 +20,9 @@ from .qa_commands import (
21
20
  from .qa_procedures import content_digest, existing_qa_file, safe_qa_path
22
21
  from .verification_input_ref import VerificationInputReference
23
22
  from .verification_conformance import capture_generation_conformance
24
- from .verification_inputs import publish_verification_snapshot, read_verification_inputs
23
+ from .verification_inputs import (
24
+ canonical_run_ref, publish_verification_snapshot, read_verification_inputs,
25
+ )
25
26
  from .verification_target import read_verification_head
26
27
 
27
28
 
@@ -51,9 +52,10 @@ class VerificationGenerationRecord(_OptionalGenerationConformance):
51
52
  artifactInputs: dict[str, str]
52
53
 
53
54
 
54
- _MAX_GENERATION_PATH_LENGTH = 4096
55
+ VERIFICATION_GENERATION_PATH_MAX_LENGTH = 4096
55
56
  _DIGEST = {"type": "string", "pattern": f"^{QA_SOURCE_DIGEST_PATTERN.pattern}$"}
56
- _PATH = {"type": "string", "minLength": 1, "maxLength": _MAX_GENERATION_PATH_LENGTH}
57
+ _PATH = {"type": "string", "minLength": 1,
58
+ "maxLength": VERIFICATION_GENERATION_PATH_MAX_LENGTH}
57
59
  _PATHS = {"type": "array", "uniqueItems": True, "items": _PATH}
58
60
  _FILES = {"type": "object", "additionalProperties": _DIGEST}
59
61
  _SOURCE = {
@@ -102,7 +104,7 @@ def _generation_errors(payload: dict[str, Any]) -> list[str]:
102
104
  protected, generated = source["protectedFiles"], source["generatedFiles"]
103
105
  paths = {*source["trackedPaths"], *protected, *generated, *declarations}
104
106
  for relative in paths:
105
- if len(relative) > _MAX_GENERATION_PATH_LENGTH:
107
+ if len(relative) > VERIFICATION_GENERATION_PATH_MAX_LENGTH:
106
108
  return ["generation source path is too long"]
107
109
  path = PurePosixPath(relative)
108
110
  if (not path.parts or path.is_absolute() or ".." in path.parts
@@ -197,14 +199,8 @@ def prepare_verification_generation(
197
199
  ) -> tuple[Path, str]:
198
200
  if ref.task_type not in QA_COMMAND_EXECUTING_TASK_TYPES:
199
201
  raise ValueError("verification generations require a QA-executing phase")
200
- reference_root = ref.project_root or project
202
+ ref = canonical_run_ref(project, ref)
201
203
  project = project.resolve()
202
- if reference_root.resolve() != project:
203
- raise ValueError("verification generation project root mismatch")
204
- relative_task = ref.task_root.absolute().relative_to(reference_root.absolute())
205
- ref = replace(
206
- ref, task_root_override=safe_qa_path(project, relative_task.as_posix()),
207
- )
208
204
  input_path = ref.verification_inputs.relative_to(project).as_posix()
209
205
  if reference.relative_path != input_path:
210
206
  raise ValueError("generation input reference belongs to a different run")
@@ -226,6 +222,20 @@ def _generation_identity(payload: Mapping[str, Any]) -> dict[str, Any]:
226
222
  return {**payload, "source": {**payload["source"], "generatedFiles": {}}}
227
223
 
228
224
 
225
+ def sealed_source_snapshot(
226
+ record: VerificationGenerationRecord,
227
+ ) -> VerificationSourceSnapshot:
228
+ source = record["source"]
229
+ return VerificationSourceSnapshot(
230
+ root=Path(record["sourceRoot"]),
231
+ tracked_paths=frozenset(source["trackedPaths"]),
232
+ generated_roots=frozenset(source["generatedRoots"]),
233
+ input_paths=frozenset(source["inputPaths"]),
234
+ protected_files=source["protectedFiles"],
235
+ generated_files=source["generatedFiles"],
236
+ )
237
+
238
+
229
239
  def read_verification_generation(
230
240
  path: Path, expected_digest: str,
231
241
  ) -> VerificationGenerationRecord:
@@ -25,6 +25,15 @@ class VerificationInputReference:
25
25
  ) -> VerificationInputReference | None:
26
26
  return cls._read(payload, _ARTIFACT_PATH, _ARTIFACT_DIGEST)
27
27
 
28
+ @classmethod
29
+ def required_from_artifact_fields(
30
+ cls, payload: Mapping[str, object],
31
+ ) -> VerificationInputReference:
32
+ reference = cls.from_artifact_fields(payload)
33
+ if reference is None:
34
+ raise ValueError("run manifest has no verification input reference")
35
+ return reference
36
+
28
37
  @classmethod
29
38
  def from_context(
30
39
  cls, context: Mapping[str, object],
@@ -41,6 +41,8 @@ class FrozenVerificationPlan(TypedDict):
41
41
  class _OptionalVerificationInputs(TypedDict, total=False):
42
42
  approvedPlan: FrozenVerificationPlan
43
43
  qaSourceObservations: dict[str, list[FrozenQaSourceObservation]]
44
+ conformanceBaseline: dict[str, str]
45
+ conformanceBaselineError: str
44
46
 
45
47
 
46
48
  class VerificationInputs(_OptionalVerificationInputs):
@@ -1,6 +1,7 @@
1
1
  """Preparation must allow inspection scripts that implementation creates later."""
2
2
  from __future__ import annotations
3
3
 
4
+ from dataclasses import replace
4
5
  from functools import partial
5
6
  from pathlib import Path
6
7
  from typing import Any, Callable, Mapping, cast
@@ -10,7 +11,8 @@ from okstra_project.dirs import OKSTRA_DIR_NAME, json_lock_path, registry_lock
10
11
  from .json_boundary import load_owned_object_snapshot, write_owned_object_atomic
11
12
  from .paths import RunRef
12
13
  from .qa_commands import (
13
- QA_COMMAND_EXECUTING_TASK_TYPES, QA_SOURCE_DIGEST_PATTERN, validate_qa_commands,
14
+ QA_COMMAND_EXECUTING_TASK_TYPES, QA_SOURCE_DIGEST_PATTERN, qa_relative_path_valid,
15
+ validate_qa_commands,
14
16
  )
15
17
  from .qa_procedures import (
16
18
  canonical_json_digest, content_digest, existing_qa_file, load_qa_config,
@@ -22,6 +24,7 @@ from .verification_input_types import (
22
24
  INPUT_KIND, INPUT_SCHEMA_VERSION, PLAN_INPUT_SCHEMA_VERSION,
23
25
  FrozenProcedure, VerificationInputs,
24
26
  )
27
+ from .verification_conformance import capture_conformance_baseline
25
28
  from .verification_plan import (
26
29
  VERIFICATION_PLAN_SCHEMA, capture_verification_plan, verification_plan_errors,
27
30
  )
@@ -45,6 +48,10 @@ INPUT_SCHEMA = {
45
48
  "procedures": {"type": "object"},
46
49
  "approvedPlan": VERIFICATION_PLAN_SCHEMA,
47
50
  "qaSourceObservations": {"type": "object"},
51
+ "conformanceBaseline": {
52
+ "type": "object", "additionalProperties": {"type": "string"},
53
+ },
54
+ "conformanceBaselineError": {"type": "string", "minLength": 1},
48
55
  },
49
56
  }
50
57
 
@@ -135,9 +142,28 @@ def _verification_input_errors(payload: dict[str, Any]) -> list[str]:
135
142
  errors.extend(_verification_source_errors(
136
143
  commands, payload["qaSourceObservations"],
137
144
  ))
145
+ if "conformanceBaseline" in payload or "conformanceBaselineError" in payload:
146
+ errors.extend(_conformance_baseline_errors(payload))
138
147
  return errors
139
148
 
140
149
 
150
+ def _conformance_baseline_errors(payload: Mapping[str, Any]) -> list[str]:
151
+ plan = payload.get("approvedPlan")
152
+ if plan is None:
153
+ return ["conformance baseline requires approvedPlan"]
154
+ if "conformanceBaselineError" in payload:
155
+ if "conformanceBaseline" in payload:
156
+ return ["conformance baseline and its capture error are exclusive"]
157
+ return []
158
+ baseline = payload["conformanceBaseline"]
159
+ declared = {str(row["stage"]) for row in plan["conformance"]}
160
+ if any(stage not in declared for stage in baseline):
161
+ return ["conformance baseline has an undeclared stage"]
162
+ if any(not qa_relative_path_valid(path) for path in baseline.values()):
163
+ return ["conformance baseline requires safe relative POSIX paths"]
164
+ return []
165
+
166
+
141
167
  def capture_verification_inputs(
142
168
  project: Path, source: Path, *, approved_plan: Path | None = None,
143
169
  ) -> VerificationInputs:
@@ -153,7 +179,7 @@ def capture_verification_inputs(
153
179
  root = procedure_root(project, source, relative)
154
180
  try:
155
181
  raw = read_validated_procedure(existing_qa_file(root, relative))
156
- except (OSError, ValueError) as exc:
182
+ except ValueError as exc:
157
183
  raise ValueError(f"verification procedure {relative}: {exc}") from exc
158
184
  procedures[relative] = {
159
185
  "body": raw.decode("utf-8"), "digest": content_digest(raw),
@@ -216,12 +242,57 @@ def publish_verification_snapshot(
216
242
  return path, content_digest(stored.raw_bytes)
217
243
 
218
244
 
245
+ def conformance_baseline_required(
246
+ task_type: str, inputs: Mapping[str, Any],
247
+ ) -> bool:
248
+ return task_type == "implementation" and "approvedPlan" in inputs
249
+
250
+
251
+ def frozen_conformance_baseline(
252
+ inputs: VerificationInputs, task_type: str,
253
+ ) -> dict[int, str]:
254
+ if not conformance_baseline_required(task_type, inputs):
255
+ return {}
256
+ if "conformanceBaseline" not in inputs:
257
+ cause = inputs.get(
258
+ "conformanceBaselineError", "no capture error was recorded",
259
+ )
260
+ raise ValueError(f"verification inputs carry no conformance baseline: {cause}")
261
+ return {
262
+ int(stage): script
263
+ for stage, script in inputs["conformanceBaseline"].items()
264
+ }
265
+
266
+
267
+ def canonical_run_ref(project: Path, ref: RunRef) -> RunRef:
268
+ reference_root = ref.project_root or project
269
+ if reference_root.resolve() != project.resolve():
270
+ raise ValueError("verification run project root mismatch")
271
+ relative_task = ref.task_root.absolute().relative_to(reference_root.absolute())
272
+ return replace(
273
+ ref,
274
+ task_root_override=safe_qa_path(project.resolve(), relative_task.as_posix()),
275
+ )
276
+
277
+
219
278
  def prepare_verification_inputs(
220
279
  project: Path, source: Path, ref: RunRef, *, approved_plan: Path | None = None,
221
280
  ) -> tuple[Path, str]:
222
281
  if ref.task_type not in QA_COMMAND_EXECUTING_TASK_TYPES:
223
282
  raise ValueError("verification inputs require a QA-executing phase")
224
283
  payload = capture_verification_inputs(project, source, approved_plan=approved_plan)
284
+ if conformance_baseline_required(ref.task_type, payload):
285
+ # The executor may rename or delete an earlier stage's script; only the
286
+ # manifest as it stood before implementation can still name the old path.
287
+ task_root = canonical_run_ref(project, ref).task_root
288
+ try:
289
+ payload["conformanceBaseline"] = capture_conformance_baseline(
290
+ project.resolve(), task_root, payload["approvedPlan"],
291
+ )
292
+ except ValueError as exc:
293
+ # Runs without the evidence contract keep preparing over a malformed
294
+ # manifest; the recorded cause lets a marked seal refuse it by name.
295
+ payload["conformanceBaselineError"] = str(exc)
225
296
  return publish_verification_snapshot(
226
297
  project, ref.verification_inputs, capture=partial(dict, payload),
227
298
  artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
@@ -0,0 +1,139 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from pathlib import Path, PurePosixPath
5
+ from typing import Any, Iterable, Mapping
6
+
7
+ from okstra_project.dirs import OKSTRA_DIR_NAME
8
+
9
+ from .qa_commands import (
10
+ QA_SOURCE_DIGEST_PATTERN, QA_VERIFIER_AUDIENCE_BY_TASK_TYPE, qa_relative_path_valid,
11
+ )
12
+ from .qa_procedures import safe_qa_path
13
+ from .verification_generation import (
14
+ VERIFICATION_GENERATION_PATH_MAX_LENGTH, VerificationGenerationRecord,
15
+ read_verification_generation,
16
+ )
17
+ from .verification_input_ref import VerificationInputReference
18
+ from .verification_inputs import read_verification_inputs
19
+
20
+ VERIFICATION_GENERATION_HEADER_PREFIXES = (
21
+ "**Verification generation path:**", "**Verification generation digest:**",
22
+ )
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class VerificationGenerationReference:
27
+ path: str
28
+ digest: str
29
+
30
+ def __post_init__(self) -> None:
31
+ if (not isinstance(self.path, str)
32
+ or len(self.path) > VERIFICATION_GENERATION_PATH_MAX_LENGTH
33
+ or _has_c0_control_characters(self.path)
34
+ or self.path.splitlines() != [self.path]
35
+ or not qa_relative_path_valid(self.path)):
36
+ raise ValueError("verification generation path is invalid")
37
+ relative = PurePosixPath(self.path)
38
+ if (relative.parts[0] != OKSTRA_DIR_NAME
39
+ or relative.as_posix() != self.path):
40
+ raise ValueError(
41
+ "verification generation requires a canonical artifact path"
42
+ )
43
+ if (not isinstance(self.digest, str)
44
+ or not QA_SOURCE_DIGEST_PATTERN.fullmatch(self.digest)):
45
+ raise ValueError("verification generation digest is invalid")
46
+
47
+ @classmethod
48
+ def from_payload(cls, value: object) -> VerificationGenerationReference:
49
+ if not isinstance(value, dict) or set(value) != {"path", "digest"}:
50
+ raise ValueError("verification generation requires path and digest")
51
+ return cls(value["path"], value["digest"])
52
+
53
+ def to_payload(self) -> dict[str, str]:
54
+ return {"path": self.path, "digest": self.digest}
55
+
56
+
57
+ def _has_c0_control_characters(value: str) -> bool:
58
+ # A control character could forge an extra header line in the prompt prefix.
59
+ return any(ord(char) < 32 for char in value)
60
+
61
+
62
+ def read_invocation_generation(
63
+ project: Path, manifest_path: Path | None, manifest: Mapping[str, Any],
64
+ reference: VerificationGenerationReference | None, audience: str,
65
+ ) -> VerificationGenerationRecord | None:
66
+ if not _generation_required(manifest, reference, audience):
67
+ return None
68
+ if reference is None or manifest_path is None:
69
+ raise ValueError("verifier invocation requires a verification generation")
70
+ return _read_bound_generation(project, manifest_path, manifest, reference)
71
+
72
+
73
+ def verification_generation_required(
74
+ manifest: Mapping[str, Any], audience: str,
75
+ ) -> bool:
76
+ return _generation_required(manifest, None, audience)
77
+
78
+
79
+ def _generation_required(
80
+ manifest: Mapping[str, Any],
81
+ reference: VerificationGenerationReference | None, audience: str,
82
+ ) -> bool:
83
+ if "verificationEvidenceVersion" not in manifest:
84
+ if reference is not None:
85
+ raise ValueError("verification generation requires evidence contract 1.0")
86
+ return False
87
+ if manifest["verificationEvidenceVersion"] != "1.0":
88
+ raise ValueError("unsupported verification evidence version")
89
+ task_type = manifest.get("taskType")
90
+ if (not isinstance(task_type, str)
91
+ or task_type not in QA_VERIFIER_AUDIENCE_BY_TASK_TYPE):
92
+ raise ValueError("verification evidence requires a QA-executing run")
93
+ if audience != QA_VERIFIER_AUDIENCE_BY_TASK_TYPE[task_type]:
94
+ if reference is not None:
95
+ raise ValueError("verification generation requires a verifier invocation")
96
+ return False
97
+ return True
98
+
99
+
100
+ def _read_bound_generation(
101
+ project: Path, manifest_path: Path, manifest: Mapping[str, Any],
102
+ reference: VerificationGenerationReference,
103
+ ) -> VerificationGenerationRecord:
104
+ task_type = manifest["taskType"]
105
+ project = project.resolve()
106
+ path = safe_qa_path(project, reference.path)
107
+ record = read_verification_generation(path, reference.digest)
108
+ relative_manifest = manifest_path.resolve().relative_to(project).as_posix()
109
+ if (record["runManifestPath"] != relative_manifest
110
+ or record["taskType"] != task_type):
111
+ raise ValueError("verification generation belongs to a different run")
112
+ expected = VerificationInputReference.required_from_artifact_fields(manifest)
113
+ if VerificationInputReference.from_artifact_fields(record) != expected:
114
+ raise ValueError("verification generation input reference differs from run")
115
+ inputs = read_verification_inputs(
116
+ safe_qa_path(project, expected.relative_path), expected.digest,
117
+ )
118
+ if record["sourceRoot"] != inputs["sourceRoot"]:
119
+ raise ValueError("verification generation source differs from frozen inputs")
120
+ return record
121
+
122
+
123
+ def verification_generation_headers(
124
+ reference: VerificationGenerationReference,
125
+ ) -> tuple[str, str]:
126
+ path_prefix, digest_prefix = VERIFICATION_GENERATION_HEADER_PREFIXES
127
+ return (
128
+ f"{path_prefix} {reference.path}",
129
+ f"{digest_prefix} {reference.digest}",
130
+ )
131
+
132
+
133
+ def select_verification_generation_header_lines(
134
+ lines: Iterable[str],
135
+ ) -> tuple[str, ...]:
136
+ return tuple(
137
+ line for line in lines
138
+ if line.startswith(VERIFICATION_GENERATION_HEADER_PREFIXES)
139
+ )
@@ -77,10 +77,17 @@ def read_verification_target(project_root: Path, relative: str) -> dict | None:
77
77
  return parsed
78
78
 
79
79
 
80
+ def read_worktree_head(worktree: Path) -> str:
81
+ return subprocess.check_output(
82
+ ["git", "-C", str(worktree), "rev-parse", "HEAD"], text=True,
83
+ ).strip()
84
+
85
+
80
86
  def read_verification_head(worktree: Path, expected_head: str) -> str:
81
- git = ["git", "-C", str(worktree), "rev-parse"]
82
- head = subprocess.check_output([*git, "HEAD"], text=True).strip()
83
- actual_root = subprocess.check_output([*git, "--show-toplevel"], text=True).strip()
87
+ head = read_worktree_head(worktree)
88
+ actual_root = subprocess.check_output(
89
+ ["git", "-C", str(worktree), "rev-parse", "--show-toplevel"], text=True,
90
+ ).strip()
84
91
  if head != expected_head or Path(actual_root).resolve() != worktree:
85
92
  raise ValueError(
86
93
  f"verification target mismatch: expected HEAD {expected_head}, "
@@ -24,6 +24,7 @@ from okstra_ctl.phases.implementation_planning.wizard import (
24
24
 
25
25
  from typing import Optional
26
26
 
27
+ from okstra_ctl.phases.catalog import INPUT_DOCUMENT_TASK_TYPES
27
28
  from .ids import (
28
29
  BRIEF_CARRY_ABORT,
29
30
  BRIEF_CARRY_SWITCH_ENTRY,
@@ -348,7 +349,7 @@ STEPS: list[Step] = [
348
349
  applies=lambda s: (S_TASK_TYPE in s.answered
349
350
  and bool(s.task_type)
350
351
  and s.task_type not in _BRIEF_ENTRY_TASK_TYPES
351
- and s.task_type not in ("release-handoff", "discussion")
352
+ and s.task_type not in INPUT_DOCUMENT_TASK_TYPES
352
353
  and not s.brief_path
353
354
  and not s.brief_path_pending_text),
354
355
  build=_build_brief_carry, submit=_submit_brief_carry,
@@ -11,6 +11,7 @@ from okstra_ctl.wizard_stage_intent import (
11
11
  resolve_wizard_stage_intent,
12
12
  )
13
13
 
14
+ from okstra_ctl.phases.catalog import INPUT_DOCUMENT_TASK_TYPES
14
15
  from .state import (
15
16
  WizardError,
16
17
  WizardState,
@@ -99,7 +100,7 @@ def render_args(state: WizardState) -> dict[str, Any]:
99
100
  "task-id": state.task_id,
100
101
  "task-type": state.task_type,
101
102
  "task-brief": (
102
- "" if state.task_type in ("release-handoff", "discussion")
103
+ "" if state.task_type in INPUT_DOCUMENT_TASK_TYPES
103
104
  else state.brief_path
104
105
  ),
105
106
  "analysis-target": state.analysis_target,
@@ -29,7 +29,9 @@ from okstra_ctl.wizard_stage_intent import WHOLE_TASK_STAGE
29
29
  from okstra_ctl import worktree_registry
30
30
  from okstra_ctl.worktree import is_git_work_tree, main_worktree_path
31
31
  from okstra_ctl.paths import RunRef, task_runs_dir
32
+ from okstra_ctl.phases.catalog import INPUT_DOCUMENT_TASK_TYPES
32
33
  from okstra_ctl.run_context import latest_run_inputs
34
+ from okstra_ctl.generated_input import names_generated_input_document
33
35
  from okstra_project.state import (
34
36
  StateError,
35
37
  list_project_tasks,
@@ -200,7 +202,7 @@ def _resolve_reuse_worktree(state: WizardState) -> bool:
200
202
 
201
203
  def _brief_resolved(state: WizardState) -> bool:
202
204
  """brief 입력이 끝났는가. release-handoff·discussion 은 brief 를 받지 않아 항상 True."""
203
- return bool(state.brief_path) or state.task_type in ("release-handoff", "discussion")
205
+ return bool(state.brief_path) or state.task_type in INPUT_DOCUMENT_TASK_TYPES
204
206
 
205
207
 
206
208
  def _parse_stage_objects(state: WizardState) -> list:
@@ -251,13 +253,22 @@ def _reserved_stage_numbers(state: WizardState) -> set:
251
253
 
252
254
 
253
255
  def _existing_task_brief(project_root: Path, task_key: str) -> str:
254
- """Read taskBriefPath from manifest for an existing task. Empty if none."""
256
+ """Read taskBriefPath from manifest for an existing task.
257
+
258
+ Empty if none, or if it points at an input document a release-handoff or
259
+ discussion run generated.
260
+ """
255
261
  root = find_task_root(project_root, task_key)
256
262
  if root is None:
257
263
  return ""
258
264
  manifest = read_task_manifest(root) or {}
259
265
  val = manifest.get("taskBriefPath") or ""
260
- return val if isinstance(val, str) else ""
266
+ if not isinstance(val, str):
267
+ return ""
268
+ # Manifests written before render kept the task brief can still name one.
269
+ if names_generated_input_document(Path(project_root), task_key, val):
270
+ return ""
271
+ return val
261
272
 
262
273
 
263
274
  def _recently_used_brief_times(state: WizardState) -> dict[str, float]:
@@ -29,6 +29,7 @@ from okstra_project.state import (
29
29
  find_task_root,
30
30
  )
31
31
 
32
+ from okstra_ctl.phases.catalog import INPUT_DOCUMENT_TASK_TYPES
32
33
  from .ids import (
33
34
  BRIEF_CARRY_SWITCH_ENTRY,
34
35
  BASE_REF_FREE_INPUT_TOKEN,
@@ -656,7 +657,7 @@ def _carry_in_existing_brief(state: WizardState) -> str:
656
657
  """downstream task-type 이 등록된 brief 를 자동 carry-in 한다. 주입한 경로(또는 '')."""
657
658
  if state.task_type in _BRIEF_ENTRY_TASK_TYPES:
658
659
  return ""
659
- if state.task_type in ("release-handoff", "discussion"):
660
+ if state.task_type in INPUT_DOCUMENT_TASK_TYPES:
660
661
  return "" # prepare 가 brief 자리의 input 문서를 직접 생성한다
661
662
  if state.brief_path or not state.existing_brief_path:
662
663
  return ""
@@ -470,7 +470,7 @@ def _drain_deadline(
470
470
 
471
471
  Without this the loop ends only at EOF on every stream, and a worker that
472
472
  leaves a background process behind — a dev server, a file watcher, the
473
- watcher the container-build skill starts on purpose — leaves that process
473
+ watcher started on purpose — leaves that process
474
474
  holding the write end of the pipe open for as long as it lives. The shell
475
475
  wrappers returned as soon as `wait <pid>` did, so blocking on a grandchild is
476
476
  a regression rather than a policy, and the exit code the caller gets stays
@@ -3,7 +3,6 @@ from __future__ import annotations
3
3
 
4
4
  import argparse
5
5
  import contextlib
6
- import os
7
6
  import subprocess
8
7
  import sys
9
8
  from pathlib import Path
@@ -11,6 +10,11 @@ from pathlib import Path
11
10
  from okstra_project.dirs import okstra_home
12
11
 
13
12
  from .locks import worktree_exec_lock
13
+ from .registry.verification_inputs_store import default_verification_input_store
14
+ from .verification_evidence import (
15
+ EvidenceRefused, resolve_evidence_check, run_evidence_check, shell_argv,
16
+ shell_exit_code,
17
+ )
14
18
 
15
19
  _CLI_EPILOG = r"""Every verifier of a stage runs in the same worktree at the same time, and each
16
20
  re-runs the plan's Tier 1 commands itself. A command that starts a server on a
@@ -28,24 +32,60 @@ The lock file is <okstra home>/.locks/worktree-exec/<hash of the worktree
28
32
  realpath>.lock, outside the worktree and the project's .okstra tree. When it
29
33
  cannot be created or locked, the command still runs, unlocked, after a warning
30
34
  on stderr.
35
+
36
+ Evidence mode runs one frozen check for one open verifier attempt instead:
37
+
38
+ okstra worktree-lock --project-root <root> --invocation-metadata <meta.json> \
39
+ --check qa:<qaCommands id>
40
+ okstra worktree-lock --project-root <root> --invocation-metadata <meta.json> \
41
+ --check conformance:<stageKey>
42
+
43
+ The command, the worktree and any resourceKeys come from the verification
44
+ generation the invocation is bound to, never from flags. A conformance check
45
+ runs the runCommand of that stage's entry in the conformance manifest the
46
+ generation sealed, only for a stage the generation lists in conformanceStages
47
+ and only while the manifest bytes still match the seal. In an implementation
48
+ run only the stage QA owner may run it; in final verification every verifier
49
+ runs it. It takes the worktree
50
+ lock and then each resource lock in sorted order, re-checks the attempt and the
51
+ sealed target under them, saves stdout and stderr byte for byte while passing
52
+ them through, and publishes one record under the run's verification directory.
53
+ The exit code is the command's only when the record is complete and no signal
54
+ arrived. A SIGTERM, SIGINT or SIGHUP received while the check waits or runs
55
+ exits 128+N of the first one, whatever the record says. Any other outcome (lock
56
+ unavailable, attempt cancelled, target changed, output not saved, incomplete
57
+ drain, evidence error) exits 70 and names the record on stderr. A refused
58
+ invocation or check exits 2 and runs nothing.
31
59
  """
32
60
 
33
61
 
34
- def _shell() -> str:
35
- return os.environ.get("SHELL", "") or "/bin/sh"
62
+ def _announce_wait(lockfile: Path) -> None:
63
+ _notify(f"another command holds {lockfile}; waiting")
36
64
 
37
65
 
38
- def _announce_wait(lockfile: Path) -> None:
39
- sys.stderr.write(
40
- f"okstra worktree-lock: another command holds {lockfile}; waiting\n"
66
+ def _run(command: str, worktree: Path) -> int:
67
+ return shell_exit_code(
68
+ subprocess.run(shell_argv(command), cwd=worktree, check=False).returncode
41
69
  )
70
+
71
+
72
+ def _notify(message: str) -> None:
73
+ sys.stderr.write(f"okstra worktree-lock: {message}\n")
42
74
  sys.stderr.flush()
43
75
 
44
76
 
45
- def _run(command: str, worktree: Path) -> int:
46
- code = subprocess.run([_shell(), "-c", command], cwd=worktree, check=False).returncode
47
- # 시그널로 죽은 자식은 음수를 준다. 셸이 보고하는 128+N 으로 맞춘다.
48
- return 128 - code if code < 0 else code
77
+ def _run_evidence(project: Path, metadata: Path, check_ref: str) -> int:
78
+ store = default_verification_input_store()
79
+ try:
80
+ check = resolve_evidence_check(project, metadata, check_ref, store=store)
81
+ except EvidenceRefused as exc:
82
+ _notify(f"evidence refused: {exc}")
83
+ return 2
84
+ sys.stdout.flush()
85
+ return run_evidence_check(
86
+ check, metadata, store=store, home=okstra_home(), on_wait=_announce_wait,
87
+ notify=_notify,
88
+ )
49
89
 
50
90
 
51
91
  def main(argv: list[str] | None = None) -> int:
@@ -56,17 +96,33 @@ def main(argv: list[str] | None = None) -> int:
56
96
  formatter_class=argparse.RawDescriptionHelpFormatter,
57
97
  )
58
98
  parser.add_argument(
59
- "--worktree", type=Path, required=True,
99
+ "--worktree", type=Path,
60
100
  help="worktree the command runs in; also the lock key (resolved to its realpath)",
61
101
  )
62
102
  parser.add_argument(
63
- "--command", required=True,
103
+ "--command",
64
104
  help="the declared command, run verbatim through the shell",
65
105
  )
106
+ parser.add_argument("--project-root", type=Path, help="evidence mode: project root")
107
+ parser.add_argument(
108
+ "--invocation-metadata", type=Path,
109
+ help="evidence mode: the verifier invocation's .meta.json",
110
+ )
111
+ parser.add_argument(
112
+ "--check", help="evidence mode: qa:<qaCommands id> or conformance:<stageKey>",
113
+ )
66
114
  args = parser.parse_args(argv)
115
+ evidence = (args.project_root, args.invocation_metadata, args.check)
116
+ if any(value is not None for value in evidence):
117
+ if None in evidence or args.worktree is not None or args.command is not None:
118
+ parser.error("evidence mode takes exactly --project-root, "
119
+ "--invocation-metadata and --check")
120
+ return _run_evidence(*evidence)
121
+ if args.worktree is None or args.command is None:
122
+ parser.error("--worktree and --command are required")
67
123
  worktree = args.worktree.resolve()
68
124
  if not worktree.is_dir():
69
- sys.stderr.write(f"okstra worktree-lock: not a directory: {worktree}\n")
125
+ _notify(f"not a directory: {worktree}")
70
126
  return 2
71
127
  with contextlib.ExitStack() as stack:
72
128
  try:
@@ -76,10 +132,7 @@ def main(argv: list[str] | None = None) -> int:
76
132
  except OSError as exc:
77
133
  # 잠그지 못해도 검증자의 재실행 자체를 막지 않는다. 동시 실행의 위험은
78
134
  # 락 도입 전과 같고, 그 사실을 stderr 에 남긴다.
79
- sys.stderr.write(
80
- f"okstra worktree-lock: warning: cannot take the lock ({exc}); running unlocked\n"
81
- )
82
- sys.stderr.flush()
135
+ _notify(f"warning: cannot take the lock ({exc}); running unlocked")
83
136
  return _run(args.command, worktree)
84
137
 
85
138
 
@@ -290,6 +290,10 @@ def get_implementation_base(
290
290
  ) -> Optional[str]:
291
291
  """Return the fixed implementation base commit, or None when unset /
292
292
  task-key missing."""
293
+ # Validation gates read this and must leave no file behind; taking the lock
294
+ # creates `registry.lock`.
295
+ if not _registry_path().is_file():
296
+ return None
293
297
  key = task_key(project_id, task_group, task_id)
294
298
  with _registry_lock():
295
299
  data = _load()