okstra 0.229.0 → 0.231.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 (150) 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 +168 -18
  9. package/docs/architecture.md +15 -14
  10. package/docs/coding-rules.md +15 -0
  11. package/docs/contributor-change-matrix.md +5 -5
  12. package/docs/project-structure-overview.md +13 -19
  13. package/package.json +2 -3
  14. package/runtime/BUILD.json +2 -2
  15. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  16. package/runtime/prompts/coding-preflight/clean-code.md +8 -0
  17. package/runtime/prompts/coding-preflight/overview.md +1 -0
  18. package/runtime/prompts/launch.template.md +7 -5
  19. package/runtime/prompts/lead/convergence.md +4 -4
  20. package/runtime/prompts/lead/okstra-lead-contract.md +19 -18
  21. package/runtime/prompts/lead/phase-routing.md +1 -1
  22. package/runtime/prompts/lead/report-writer.md +3 -3
  23. package/runtime/prompts/lead/team-contract.md +3 -3
  24. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
  25. package/runtime/python/okstra_ctl/agent/invocation.py +190 -9
  26. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  27. package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
  28. package/runtime/python/okstra_ctl/cmux.py +4 -2
  29. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  30. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  31. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  32. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  33. package/runtime/python/okstra_ctl/conformance.py +30 -0
  34. package/runtime/python/okstra_ctl/conformance_evidence.py +316 -0
  35. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  36. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  37. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  38. package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
  39. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  40. package/runtime/python/okstra_ctl/ids.py +1 -41
  41. package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
  42. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  43. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  44. package/runtime/python/okstra_ctl/locks.py +28 -1
  45. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  46. package/runtime/python/okstra_ctl/paths.py +90 -33
  47. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  48. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  50. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  51. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  53. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +5 -4
  55. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
  57. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +5 -4
  58. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
  59. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +6 -2
  60. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +4 -2
  61. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +23 -7
  63. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
  65. package/runtime/python/okstra_ctl/phases/implementation/spec.md +6 -4
  66. package/runtime/python/okstra_ctl/phases/implementation/validation.py +152 -30
  67. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  68. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
  69. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -12
  70. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  71. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  72. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  73. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  74. package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
  75. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  76. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  77. package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
  78. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
  79. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  80. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  81. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  82. package/runtime/python/okstra_ctl/plan_items.py +28 -0
  83. package/runtime/python/okstra_ctl/process_group.py +26 -3
  84. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  85. package/runtime/python/okstra_ctl/recap.py +1 -2
  86. package/runtime/python/okstra_ctl/render.py +25 -2
  87. package/runtime/python/okstra_ctl/report_assembly.py +102 -1
  88. package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
  89. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  90. package/runtime/python/okstra_ctl/report_inputs.py +28 -0
  91. package/runtime/python/okstra_ctl/report_narrative.py +12 -3
  92. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  93. package/runtime/python/okstra_ctl/run.py +40 -20
  94. package/runtime/python/okstra_ctl/stage_close.py +52 -6
  95. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  96. package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
  97. package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
  98. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  99. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  100. package/runtime/python/okstra_ctl/verification_dispatch.py +136 -0
  101. package/runtime/python/okstra_ctl/verification_evidence.py +671 -0
  102. package/runtime/python/okstra_ctl/verification_generation.py +34 -16
  103. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  104. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  105. package/runtime/python/okstra_ctl/verification_inputs.py +83 -2
  106. package/runtime/python/okstra_ctl/verification_invocation.py +140 -0
  107. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  108. package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
  109. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  110. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  111. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  112. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  113. package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
  114. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  115. package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
  116. package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
  117. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  118. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  119. package/runtime/schemas/final-report-v3.0.schema.json +184 -1
  120. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  121. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  122. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  123. package/runtime/skills/okstra-run/SKILL.md +11 -7
  124. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  125. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  126. package/runtime/templates/reports/html/i18n/en.json +7 -0
  127. package/runtime/templates/reports/html/i18n/ko.json +7 -0
  128. package/runtime/validators/validate-run.py +130 -20
  129. package/runtime/validators/validate-workflow.sh +1 -1
  130. package/docs/cli.md +0 -1060
  131. package/docs/container.md +0 -100
  132. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  133. package/docs/performance-improvement-plan-v2.md +0 -369
  134. package/runtime/python/okstra_ctl/container.py +0 -702
  135. package/runtime/python/okstra_ctl/rollup.py +0 -241
  136. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  137. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  138. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  139. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  140. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  141. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  142. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  143. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  144. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  145. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  146. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  147. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  148. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  149. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  150. 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,11 +20,17 @@ 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
 
28
- class FrozenVerificationSource(TypedDict):
29
+ class _OptionalFrozenVerificationSource(TypedDict, total=False):
30
+ ignoredRoots: list[str]
31
+
32
+
33
+ class FrozenVerificationSource(_OptionalFrozenVerificationSource):
29
34
  trackedPaths: list[str]
30
35
  generatedRoots: list[str]
31
36
  inputPaths: list[str]
@@ -51,9 +56,10 @@ class VerificationGenerationRecord(_OptionalGenerationConformance):
51
56
  artifactInputs: dict[str, str]
52
57
 
53
58
 
54
- _MAX_GENERATION_PATH_LENGTH = 4096
59
+ VERIFICATION_GENERATION_PATH_MAX_LENGTH = 4096
55
60
  _DIGEST = {"type": "string", "pattern": f"^{QA_SOURCE_DIGEST_PATTERN.pattern}$"}
56
- _PATH = {"type": "string", "minLength": 1, "maxLength": _MAX_GENERATION_PATH_LENGTH}
61
+ _PATH = {"type": "string", "minLength": 1,
62
+ "maxLength": VERIFICATION_GENERATION_PATH_MAX_LENGTH}
57
63
  _PATHS = {"type": "array", "uniqueItems": True, "items": _PATH}
58
64
  _FILES = {"type": "object", "additionalProperties": _DIGEST}
59
65
  _SOURCE = {
@@ -62,7 +68,7 @@ _SOURCE = {
62
68
  "protectedFiles", "generatedFiles"],
63
69
  "properties": {
64
70
  "trackedPaths": _PATHS, "generatedRoots": _PATHS, "inputPaths": _PATHS,
65
- "protectedFiles": _FILES, "generatedFiles": _FILES,
71
+ "protectedFiles": _FILES, "generatedFiles": _FILES, "ignoredRoots": _PATHS,
66
72
  },
67
73
  }
68
74
  _SCHEMA = {
@@ -100,9 +106,10 @@ def _generation_errors(payload: dict[str, Any]) -> list[str]:
100
106
  if PurePosixPath(payload[field]).parts[0] != OKSTRA_DIR_NAME:
101
107
  return ["generation references must remain in project artifacts"]
102
108
  protected, generated = source["protectedFiles"], source["generatedFiles"]
103
- paths = {*source["trackedPaths"], *protected, *generated, *declarations}
109
+ ignored = source.get("ignoredRoots", [])
110
+ paths = {*source["trackedPaths"], *protected, *generated, *declarations, *ignored}
104
111
  for relative in paths:
105
- if len(relative) > _MAX_GENERATION_PATH_LENGTH:
112
+ if len(relative) > VERIFICATION_GENERATION_PATH_MAX_LENGTH:
106
113
  return ["generation source path is too long"]
107
114
  path = PurePosixPath(relative)
108
115
  if (not path.parts or path.is_absolute() or ".." in path.parts
@@ -110,7 +117,7 @@ def _generation_errors(payload: dict[str, Any]) -> list[str]:
110
117
  return ["generation source paths must be canonical and relative"]
111
118
  if not set(source["inputPaths"]).issubset(protected):
112
119
  return ["generation declared inputs must remain protected"]
113
- roots = frozenset(source["generatedRoots"])
120
+ roots = frozenset(source["generatedRoots"]) | frozenset(ignored)
114
121
  required = frozenset(source["trackedPaths"]) | frozenset(source["inputPaths"])
115
122
  if any(is_generated_verification_path(path, roots, required) for path in protected):
116
123
  return ["generation protected path conflicts with classification"]
@@ -182,6 +189,8 @@ def _capture_generation(
182
189
  "inputPaths": sorted(snapshot.input_paths),
183
190
  "protectedFiles": dict(snapshot.protected_files),
184
191
  "generatedFiles": dict(snapshot.generated_files),
192
+ **({"ignoredRoots": sorted(snapshot.ignored_roots)}
193
+ if snapshot.ignored_roots else {}),
185
194
  },
186
195
  "artifactInputs": artifacts,
187
196
  **({"conformanceStages": list(conformance.stages)}
@@ -197,14 +206,8 @@ def prepare_verification_generation(
197
206
  ) -> tuple[Path, str]:
198
207
  if ref.task_type not in QA_COMMAND_EXECUTING_TASK_TYPES:
199
208
  raise ValueError("verification generations require a QA-executing phase")
200
- reference_root = ref.project_root or project
209
+ ref = canonical_run_ref(project, ref)
201
210
  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
211
  input_path = ref.verification_inputs.relative_to(project).as_posix()
209
212
  if reference.relative_path != input_path:
210
213
  raise ValueError("generation input reference belongs to a different run")
@@ -226,6 +229,21 @@ def _generation_identity(payload: Mapping[str, Any]) -> dict[str, Any]:
226
229
  return {**payload, "source": {**payload["source"], "generatedFiles": {}}}
227
230
 
228
231
 
232
+ def sealed_source_snapshot(
233
+ record: VerificationGenerationRecord,
234
+ ) -> VerificationSourceSnapshot:
235
+ source = record["source"]
236
+ return VerificationSourceSnapshot(
237
+ root=Path(record["sourceRoot"]),
238
+ tracked_paths=frozenset(source["trackedPaths"]),
239
+ generated_roots=frozenset(source["generatedRoots"]),
240
+ input_paths=frozenset(source["inputPaths"]),
241
+ protected_files=source["protectedFiles"],
242
+ generated_files=source["generatedFiles"],
243
+ ignored_roots=frozenset(source.get("ignoredRoots", ())),
244
+ )
245
+
246
+
229
247
  def read_verification_generation(
230
248
  path: Path, expected_digest: str,
231
249
  ) -> 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,67 @@ 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 evidence_contract_applies(inputs: Mapping[str, Any]) -> bool:
252
+ """Whether a new run with these frozen inputs can satisfy the verification
253
+ evidence contract: a generation seals conformance stages only from an
254
+ approved plan with a captured baseline, and an evidence check selects a
255
+ qaCommands entry by its id (`verification_evidence.resolve_evidence_check`)."""
256
+ return ("approvedPlan" in inputs and "conformanceBaselineError" not in inputs
257
+ and all(entry.get("id") is not None
258
+ for entries in inputs["qaCommands"].values() for entry in entries))
259
+
260
+
261
+ def frozen_conformance_baseline(
262
+ inputs: VerificationInputs, task_type: str,
263
+ ) -> dict[int, str]:
264
+ if not conformance_baseline_required(task_type, inputs):
265
+ return {}
266
+ if "conformanceBaseline" not in inputs:
267
+ cause = inputs.get(
268
+ "conformanceBaselineError", "no capture error was recorded",
269
+ )
270
+ raise ValueError(f"verification inputs carry no conformance baseline: {cause}")
271
+ return {
272
+ int(stage): script
273
+ for stage, script in inputs["conformanceBaseline"].items()
274
+ }
275
+
276
+
277
+ def canonical_run_ref(project: Path, ref: RunRef) -> RunRef:
278
+ reference_root = ref.project_root or project
279
+ if reference_root.resolve() != project.resolve():
280
+ raise ValueError("verification run project root mismatch")
281
+ relative_task = ref.task_root.absolute().relative_to(reference_root.absolute())
282
+ return replace(
283
+ ref,
284
+ task_root_override=safe_qa_path(project.resolve(), relative_task.as_posix()),
285
+ )
286
+
287
+
219
288
  def prepare_verification_inputs(
220
289
  project: Path, source: Path, ref: RunRef, *, approved_plan: Path | None = None,
221
290
  ) -> tuple[Path, str]:
222
291
  if ref.task_type not in QA_COMMAND_EXECUTING_TASK_TYPES:
223
292
  raise ValueError("verification inputs require a QA-executing phase")
224
293
  payload = capture_verification_inputs(project, source, approved_plan=approved_plan)
294
+ if conformance_baseline_required(ref.task_type, payload):
295
+ # The executor may rename or delete an earlier stage's script; only the
296
+ # manifest as it stood before implementation can still name the old path.
297
+ task_root = canonical_run_ref(project, ref).task_root
298
+ try:
299
+ payload["conformanceBaseline"] = capture_conformance_baseline(
300
+ project.resolve(), task_root, payload["approvedPlan"],
301
+ )
302
+ except ValueError as exc:
303
+ # Runs without the evidence contract keep preparing over a malformed
304
+ # manifest; the recorded cause lets a marked seal refuse it by name.
305
+ payload["conformanceBaselineError"] = str(exc)
225
306
  return publish_verification_snapshot(
226
307
  project, ref.verification_inputs, capture=partial(dict, payload),
227
308
  artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
@@ -0,0 +1,140 @@
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_EVIDENCE_VERSION = "1.0"
21
+ VERIFICATION_GENERATION_HEADER_PREFIXES = (
22
+ "**Verification generation path:**", "**Verification generation digest:**",
23
+ )
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class VerificationGenerationReference:
28
+ path: str
29
+ digest: str
30
+
31
+ def __post_init__(self) -> None:
32
+ if (not isinstance(self.path, str)
33
+ or len(self.path) > VERIFICATION_GENERATION_PATH_MAX_LENGTH
34
+ or _has_c0_control_characters(self.path)
35
+ or self.path.splitlines() != [self.path]
36
+ or not qa_relative_path_valid(self.path)):
37
+ raise ValueError("verification generation path is invalid")
38
+ relative = PurePosixPath(self.path)
39
+ if (relative.parts[0] != OKSTRA_DIR_NAME
40
+ or relative.as_posix() != self.path):
41
+ raise ValueError(
42
+ "verification generation requires a canonical artifact path"
43
+ )
44
+ if (not isinstance(self.digest, str)
45
+ or not QA_SOURCE_DIGEST_PATTERN.fullmatch(self.digest)):
46
+ raise ValueError("verification generation digest is invalid")
47
+
48
+ @classmethod
49
+ def from_payload(cls, value: object) -> VerificationGenerationReference:
50
+ if not isinstance(value, dict) or set(value) != {"path", "digest"}:
51
+ raise ValueError("verification generation requires path and digest")
52
+ return cls(value["path"], value["digest"])
53
+
54
+ def to_payload(self) -> dict[str, str]:
55
+ return {"path": self.path, "digest": self.digest}
56
+
57
+
58
+ def _has_c0_control_characters(value: str) -> bool:
59
+ # A control character could forge an extra header line in the prompt prefix.
60
+ return any(ord(char) < 32 for char in value)
61
+
62
+
63
+ def read_invocation_generation(
64
+ project: Path, manifest_path: Path | None, manifest: Mapping[str, Any],
65
+ reference: VerificationGenerationReference | None, audience: str,
66
+ ) -> VerificationGenerationRecord | None:
67
+ if not _generation_required(manifest, reference, audience):
68
+ return None
69
+ if reference is None or manifest_path is None:
70
+ raise ValueError("verifier invocation requires a verification generation")
71
+ return _read_bound_generation(project, manifest_path, manifest, reference)
72
+
73
+
74
+ def verification_generation_required(
75
+ manifest: Mapping[str, Any], audience: str,
76
+ ) -> bool:
77
+ return _generation_required(manifest, None, audience)
78
+
79
+
80
+ def _generation_required(
81
+ manifest: Mapping[str, Any],
82
+ reference: VerificationGenerationReference | None, audience: str,
83
+ ) -> bool:
84
+ if "verificationEvidenceVersion" not in manifest:
85
+ if reference is not None:
86
+ raise ValueError("verification generation requires evidence contract 1.0")
87
+ return False
88
+ if manifest["verificationEvidenceVersion"] != VERIFICATION_EVIDENCE_VERSION:
89
+ raise ValueError("unsupported verification evidence version")
90
+ task_type = manifest.get("taskType")
91
+ if (not isinstance(task_type, str)
92
+ or task_type not in QA_VERIFIER_AUDIENCE_BY_TASK_TYPE):
93
+ raise ValueError("verification evidence requires a QA-executing run")
94
+ if audience != QA_VERIFIER_AUDIENCE_BY_TASK_TYPE[task_type]:
95
+ if reference is not None:
96
+ raise ValueError("verification generation requires a verifier invocation")
97
+ return False
98
+ return True
99
+
100
+
101
+ def _read_bound_generation(
102
+ project: Path, manifest_path: Path, manifest: Mapping[str, Any],
103
+ reference: VerificationGenerationReference,
104
+ ) -> VerificationGenerationRecord:
105
+ task_type = manifest["taskType"]
106
+ project = project.resolve()
107
+ path = safe_qa_path(project, reference.path)
108
+ record = read_verification_generation(path, reference.digest)
109
+ relative_manifest = manifest_path.resolve().relative_to(project).as_posix()
110
+ if (record["runManifestPath"] != relative_manifest
111
+ or record["taskType"] != task_type):
112
+ raise ValueError("verification generation belongs to a different run")
113
+ expected = VerificationInputReference.required_from_artifact_fields(manifest)
114
+ if VerificationInputReference.from_artifact_fields(record) != expected:
115
+ raise ValueError("verification generation input reference differs from run")
116
+ inputs = read_verification_inputs(
117
+ safe_qa_path(project, expected.relative_path), expected.digest,
118
+ )
119
+ if record["sourceRoot"] != inputs["sourceRoot"]:
120
+ raise ValueError("verification generation source differs from frozen inputs")
121
+ return record
122
+
123
+
124
+ def verification_generation_headers(
125
+ reference: VerificationGenerationReference,
126
+ ) -> tuple[str, str]:
127
+ path_prefix, digest_prefix = VERIFICATION_GENERATION_HEADER_PREFIXES
128
+ return (
129
+ f"{path_prefix} {reference.path}",
130
+ f"{digest_prefix} {reference.digest}",
131
+ )
132
+
133
+
134
+ def select_verification_generation_header_lines(
135
+ lines: Iterable[str],
136
+ ) -> tuple[str, ...]:
137
+ return tuple(
138
+ line for line in lines
139
+ if line.startswith(VERIFICATION_GENERATION_HEADER_PREFIXES)
140
+ )
@@ -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}, "
@@ -13,6 +13,10 @@ from okstra_ctl.domain.wizard.interaction import (
13
13
  WizardAnswerError,
14
14
  normalize_planned_answer,
15
15
  )
16
+ from okstra_ctl.phases.implementation_planning.wizard import (
17
+ _DIRECTION_SEPARATOR,
18
+ _settle_selected_direction,
19
+ )
16
20
  from okstra_ctl.registry.host_registry import default_host_registry
17
21
  from okstra_ctl.run import PrepareError
18
22
 
@@ -22,11 +26,13 @@ from .ids import (
22
26
  PROMPT_GROUPS,
23
27
  REQUESTABLE_TASK_TYPES,
24
28
  S_ABORTED,
29
+ S_APPROVE_PLAN_CONFIRM,
25
30
  S_CONFIRM,
26
31
  S_DESIGN_PREP_CONFIRM,
27
32
  S_DESIGN_PREP_OVERRIDES,
28
33
  S_DONE,
29
34
  S_REPORT_LANGUAGE,
35
+ S_SELECTED_DIRECTION_PICK,
30
36
  _ABORT_OPTION,
31
37
  _STEP_TO_GROUP,
32
38
  )
@@ -40,6 +46,7 @@ from .picker_navigation import (
40
46
  )
41
47
  from .roles import _step_role, _submit_role_prompt, next_role_prompt
42
48
  from .steps_analysis import _advance_design_prep_item
49
+ from .steps_plan import _settle_approved_plan
43
50
  from .registry import STEPS, STEP_BY_ID, _ROLE_SELECTION_BOUNDARY
44
51
  from .worker_settings import (
45
52
  next_worker_settings_prompt,
@@ -285,6 +292,22 @@ def _sim_advance(state: WizardState, prompt: Prompt) -> None:
285
292
  if q.step not in state.answered:
286
293
  state.answered.append(q.step)
287
294
  return
295
+ if prompt.step == S_APPROVE_PLAN_CONFIRM:
296
+ # The real submit writes `approved: true` into the plan's data.json
297
+ # and re-renders the report. The deepcopy in `_remaining_screens`
298
+ # does not cover files, so counting screens would approve the plan.
299
+ _settle_approved_plan(state, state.approve_plan_candidate)
300
+ if prompt.step not in state.answered:
301
+ state.answered.append(prompt.step)
302
+ return
303
+ if prompt.step == S_SELECTED_DIRECTION_PICK:
304
+ # The real submit records the picked direction in the report's
305
+ # user-response sidecar; counting screens must not answer for the user.
306
+ path, _, _ = _sim_answer(prompt).partition(_DIRECTION_SEPARATOR)
307
+ _settle_selected_direction(state, path)
308
+ if prompt.step not in state.answered:
309
+ state.answered.append(prompt.step)
310
+ return
288
311
  if prompt.step == S_DESIGN_PREP_CONFIRM:
289
312
  _advance_design_prep_item(state)
290
313
  if prompt.step not in state.answered:
@@ -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 ""
@@ -403,11 +403,15 @@ def _submit_approve_plan_confirm(state: WizardState, value: str) -> Optional[str
403
403
  path=resolved, option=state.html_approval_option)
404
404
  except PrepareError as exc:
405
405
  raise WizardError(str(exc)) from exc
406
- state.approved_plan_path = str(resolved)
406
+ _settle_approved_plan(state, str(resolved))
407
+ return echo
408
+
409
+
410
+ def _settle_approved_plan(state: WizardState, path_str: str) -> None:
411
+ state.approved_plan_path = path_str
407
412
  state.approve_plan_candidate = ""
408
413
  state.html_approval_sidecar = ""
409
414
  state.html_approval_option = ""
410
- return echo
411
415
 
412
416
 
413
417
  def _build_stage_pick(state: WizardState) -> Prompt:
@@ -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
@@ -7,9 +7,16 @@ okstra 의 규칙을 하나도 모른다 — 브랜치가 존재하는지, HEAD
7
7
  """
8
8
  from __future__ import annotations
9
9
 
10
+ import os
10
11
  import subprocess
11
12
  from pathlib import Path
12
13
 
14
+ # Prefix for git commands that create commits or checkouts nobody asked the
15
+ # repository's hooks about: okstra's merge commits, rebases and scratch
16
+ # worktrees. A hooks path such as husky's `.husky` expects files a fresh
17
+ # worktree does not have, and `--no-verify` still runs `prepare-commit-msg`.
18
+ WITHOUT_HOOKS = ("-c", f"core.hooksPath={os.devnull}")
19
+
13
20
 
14
21
  def _git(cwd: Path, *args: str) -> subprocess.CompletedProcess:
15
22
  return subprocess.run(
@@ -145,7 +152,7 @@ def merge_branch(cwd, branch: str, *, no_ff: bool) -> list[str] | None:
145
152
  충돌감지·abort 시퀀스의 단일 지점."""
146
153
  args = ["merge", "--no-ff", "--no-edit", branch] if no_ff \
147
154
  else ["merge", "--no-edit", branch]
148
- res = _git(Path(cwd), *args)
155
+ res = _git(Path(cwd), *WITHOUT_HOOKS, *args)
149
156
  if res.returncode == 0:
150
157
  return None
151
158
  conflicts = _git(Path(cwd), "diff", "--name-only",