okstra 0.228.2 → 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 (124) 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 +179 -13
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +16 -21
  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/bin/okstra-provider-exec.py +53 -4
  16. package/runtime/prompts/duties/code-reviewer.json +5 -2
  17. package/runtime/prompts/launch.template.md +5 -5
  18. package/runtime/prompts/lead/convergence.md +4 -4
  19. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  20. package/runtime/prompts/lead/phase-routing.md +1 -1
  21. package/runtime/prompts/lead/report-writer.md +3 -3
  22. package/runtime/prompts/lead/team-contract.md +3 -3
  23. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  24. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  25. package/runtime/python/okstra_ctl/cmux.py +4 -2
  26. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  27. package/runtime/python/okstra_ctl/code_review_coverage.py +18 -5
  28. package/runtime/python/okstra_ctl/code_review_scope.py +11 -7
  29. package/runtime/python/okstra_ctl/code_review_target.py +79 -25
  30. package/runtime/python/okstra_ctl/conformance.py +61 -0
  31. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  32. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  33. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  34. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  35. package/runtime/python/okstra_ctl/execution_mutation_audit.py +100 -2
  36. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  37. package/runtime/python/okstra_ctl/ids.py +1 -41
  38. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  39. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  40. package/runtime/python/okstra_ctl/locks.py +28 -1
  41. package/runtime/python/okstra_ctl/model_io/renderers.py +17 -1
  42. package/runtime/python/okstra_ctl/paths.py +84 -31
  43. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  44. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  45. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  46. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  47. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  48. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  50. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  51. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  53. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  55. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  57. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  58. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  59. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  62. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  63. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  66. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  67. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  68. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  69. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  70. package/runtime/python/okstra_ctl/process_group.py +26 -3
  71. package/runtime/python/okstra_ctl/qa_commands.py +7 -2
  72. package/runtime/python/okstra_ctl/qa_procedures.py +60 -17
  73. package/runtime/python/okstra_ctl/recap.py +1 -2
  74. package/runtime/python/okstra_ctl/render.py +10 -2
  75. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  76. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  77. package/runtime/python/okstra_ctl/run.py +24 -20
  78. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  79. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  80. package/runtime/python/okstra_ctl/verification_conformance.py +182 -0
  81. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  82. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  83. package/runtime/python/okstra_ctl/verification_generation.py +248 -0
  84. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  85. package/runtime/python/okstra_ctl/verification_input_types.py +23 -2
  86. package/runtime/python/okstra_ctl/verification_inputs.py +161 -23
  87. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  88. package/runtime/python/okstra_ctl/verification_target.py +20 -5
  89. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  90. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  91. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  92. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  93. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  94. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  95. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  96. package/runtime/skills/okstra-code-review/SKILL.md +84 -48
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +10 -4
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +7 -4
  99. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  100. package/runtime/skills/okstra-run/SKILL.md +6 -6
  101. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  102. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  103. package/runtime/validators/validate-run.py +118 -52
  104. package/docs/cli.md +0 -1060
  105. package/docs/container.md +0 -100
  106. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  107. package/docs/performance-improvement-plan-v2.md +0 -369
  108. package/runtime/python/okstra_ctl/container.py +0 -702
  109. package/runtime/python/okstra_ctl/rollup.py +0 -241
  110. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  111. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  112. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  113. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  114. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  115. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  116. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  117. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  118. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  119. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  120. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  121. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  122. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  123. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  124. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -5,8 +5,9 @@ import hashlib
5
5
  import json
6
6
  import os
7
7
  import tempfile
8
+ from functools import cache
8
9
  from pathlib import Path
9
- from typing import Any, Literal, Mapping, TypedDict
10
+ from typing import Any, Callable, Literal, Mapping
10
11
 
11
12
  from okstra_project import project_json_path
12
13
  from okstra_project.dirs import OKSTRA_DIR_NAME, json_lock_path, registry_lock
@@ -16,13 +17,15 @@ from .json_boundary import load_owned_object, write_owned_object_atomic
16
17
  from .qa_commands import (
17
18
  QA_RELATIVE_PATH_DESCRIPTION, qa_relative_path_valid, validate_qa_commands,
18
19
  )
20
+ from .verification_input_types import QaSourceObservation, QaSourceStatus
19
21
 
20
22
  PROCEDURE_SECTIONS = (
21
23
  "Execution", "Environment", "User actions", "Success observations", "Cleanup",
22
24
  )
25
+ QA_SOURCE_PATH_LIMIT = 1024
23
26
 
24
27
 
25
- class QaInspectionRow(TypedDict, total=False):
28
+ class QaInspectionRow(QaSourceObservation, total=False):
26
29
  category: str
27
30
  index: int
28
31
  id: str
@@ -31,11 +34,7 @@ class QaInspectionRow(TypedDict, total=False):
31
34
  procedurePath: str
32
35
  entryDigest: str
33
36
  procedureDigest: str
34
- sourceStatus: Literal[
35
- "not-declared", "not-queried", "no-baseline", "unchanged", "changed",
36
- ]
37
37
  evidenceStatus: Literal["not-queried"]
38
- error: str
39
38
 
40
39
 
41
40
  def content_digest(value: bytes) -> str:
@@ -86,13 +85,62 @@ def read_validated_procedure(path: Path) -> bytes:
86
85
  return raw
87
86
 
88
87
 
89
- def source_digest(source: Path, relatives: list[str]) -> str:
88
+ def new_qa_source_digest_reader() -> Callable[[Path], str]:
89
+ @cache
90
+ def read_digest(path: Path) -> str:
91
+ return content_digest(path.read_bytes())
92
+
93
+ return read_digest
94
+
95
+
96
+ def source_digest(
97
+ source: Path, relatives: list[str], *,
98
+ read_digest: Callable[[Path], str] | None = None,
99
+ ) -> str:
100
+ if len(relatives) > QA_SOURCE_PATH_LIMIT:
101
+ raise ValueError(
102
+ f"related sources must contain at most {QA_SOURCE_PATH_LIMIT} paths"
103
+ )
104
+ reader = read_digest if read_digest is not None else new_qa_source_digest_reader()
90
105
  return canonical_json_digest({
91
- relative: content_digest(existing_qa_file(source, relative).read_bytes())
106
+ relative: reader(existing_qa_file(source, relative))
92
107
  for relative in sorted(relatives)
93
108
  })
94
109
 
95
110
 
111
+ def qa_source_status(
112
+ entry: Mapping[str, Any], observed_digest: str | None,
113
+ ) -> QaSourceStatus:
114
+ if not entry.get("sourcePaths"):
115
+ return "not-declared"
116
+ if observed_digest is None:
117
+ return "not-queried"
118
+ baseline = entry.get("sourceBaselineDigest")
119
+ if not baseline:
120
+ return "no-baseline"
121
+ return "unchanged" if observed_digest == baseline else "changed"
122
+
123
+
124
+ def observe_qa_sources(
125
+ source: Path, entry: Mapping[str, Any], read_digest: Callable[[Path], str],
126
+ ) -> QaSourceObservation:
127
+ observation: QaSourceObservation = {
128
+ "sourceStatus": qa_source_status(entry, None),
129
+ }
130
+ if not entry.get("sourcePaths"):
131
+ return observation
132
+ try:
133
+ observed = source_digest(source, entry["sourcePaths"], read_digest=read_digest)
134
+ except (OSError, ValueError) as exc:
135
+ observation["error"] = str(exc)
136
+ else:
137
+ observation.update(
138
+ sourceStatus=qa_source_status(entry, observed),
139
+ observedSourceDigest=observed,
140
+ )
141
+ return observation
142
+
143
+
96
144
  def load_qa_config(project: Path) -> dict[str, Any]:
97
145
  config = load_owned_object(project_json_path(project), artifact="project config")
98
146
  errors = validate_qa_commands(config.get("qaCommands"))
@@ -103,29 +151,24 @@ def load_qa_config(project: Path) -> dict[str, Any]:
103
151
 
104
152
  def inspect_commands(project: Path, source: Path) -> list[QaInspectionRow]:
105
153
  config = load_qa_config(project)
154
+ read_digest = new_qa_source_digest_reader()
106
155
  rows: list[QaInspectionRow] = []
107
156
  for category, entries in (config.get("qaCommands") or {}).items():
108
157
  for index, entry in enumerate(entries):
109
158
  row: QaInspectionRow = {
110
159
  **entry, "category": category, "index": index,
111
160
  "entryDigest": canonical_json_digest(entry),
112
- "sourceStatus": (
113
- "not-queried" if entry.get("sourcePaths") else "not-declared"
114
- ),
161
+ "sourceStatus": qa_source_status(entry, None),
115
162
  "evidenceStatus": "not-queried",
116
163
  }
164
+ row.pop("observedSourceDigest", None)
117
165
  try:
118
166
  relative = entry.get("procedurePath")
119
167
  if relative:
120
168
  root = procedure_root(project, source, relative)
121
169
  raw = read_validated_procedure(existing_qa_file(root, relative))
122
170
  row["procedureDigest"] = content_digest(raw)
123
- if entry.get("sourcePaths"):
124
- observed = source_digest(source, entry["sourcePaths"])
125
- baseline = entry.get("sourceBaselineDigest")
126
- row["sourceStatus"] = "no-baseline" if not baseline else (
127
- "unchanged" if observed == baseline else "changed"
128
- )
171
+ row.update(observe_qa_sources(source, entry, read_digest))
129
172
  except (OSError, ValueError) as exc:
130
173
  row["error"] = str(exc)
131
174
  rows.append(row)
@@ -212,8 +212,7 @@ def assemble_group_recap(project_root: Path, task_group: str) -> dict:
212
212
  브리프 디렉터리가 목록과 순서를, 카탈로그(task-manifest)가 실제 phase·상태를,
213
213
  그룹 문서의 Task Memory 영역이 결론(headline·decisions·watch out·follow-ups)을
214
214
  준다. 어느 하나만으로는 틀린다 — 카탈로그는 미시작 브리프를 모르고, 메모리는
215
- 2026-09-07 이전에 끝난 task 를 모른다. 숫자 집계(CPU·에러)는 rollup 의 것이라
216
- 여기서 세지 않는다.
215
+ 2026-09-07 이전에 끝난 task 를 모른다.
217
216
  """
218
217
  context_file = group_context.group_context_file(project_root, task_group)
219
218
  text = context_file.read_text(encoding="utf-8") if context_file.is_file() else ""
@@ -17,7 +17,7 @@ session id 등) 를 덧붙여 전달한다.
17
17
 
18
18
  from __future__ import annotations
19
19
 
20
- from .phases.catalog import profile_sidecar
20
+ from .phases.catalog import INPUT_DOCUMENT_TASK_TYPES, profile_sidecar
21
21
 
22
22
  import hashlib
23
23
  import json
@@ -1405,6 +1405,14 @@ def _derive_latest_pointers(existing: dict, ctx: dict, current_report_relative:
1405
1405
  }
1406
1406
 
1407
1407
 
1408
+ def _registered_task_brief(existing: dict, ctx: dict) -> str:
1409
+ # Downstream runs carry the manifest value in as their brief, so an input
1410
+ # document prepare generated must not replace the task's requirement brief.
1411
+ if ctx.get("TASK_TYPE") in INPUT_DOCUMENT_TASK_TYPES:
1412
+ return existing.get("taskBriefPath", "")
1413
+ return ctx.get("BRIEF_RELATIVE_PATH", "")
1414
+
1415
+
1408
1416
  def render_task_manifest(manifest_path: str, ctx: dict) -> None:
1409
1417
  path = Path(manifest_path)
1410
1418
  existing = {}
@@ -1484,7 +1492,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
1484
1492
  "workStatusNote": existing.get("workStatusNote", ""),
1485
1493
  "latestWorkRecordPath": existing.get("latestWorkRecordPath", ""),
1486
1494
  "registrationSource": existing.get("registrationSource", ""),
1487
- "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
1495
+ "taskBriefPath": _registered_task_brief(existing, ctx),
1488
1496
  "recommendedWorkers": reviewers,
1489
1497
  "relatedTasks": related_tasks,
1490
1498
  "currentStatus": ctx.get("CURRENT_TASK_STATUS", ""),
@@ -1325,7 +1325,7 @@ def closeout_command(result: Mapping[str, Any]) -> dict[str, str]:
1325
1325
  }
1326
1326
  pointer = result.get("nextRecommendedPhase")
1327
1327
  if not isinstance(pointer, Mapping):
1328
- return {"command": "/okstra-inspect status", "note": "no pointer recorded"}
1328
+ return {"command": "okstra task-show <task-key>", "note": "no pointer recorded; replace <task-key> with the full task key"}
1329
1329
  status = str(pointer.get("status") or "").strip()
1330
1330
  phase = str(pointer.get("phase") or "").strip()
1331
1331
  rationale = str(pointer.get("rationale") or "").strip()
@@ -1345,14 +1345,14 @@ def closeout_command(result: Mapping[str, Any]) -> dict[str, str]:
1345
1345
  "command": "",
1346
1346
  "note": "the lifecycle ends here — say the task is finished, name any "
1347
1347
  "follow-up tasks this run registered, and do not send the user "
1348
- "to /okstra-inspect",
1348
+ "to a separate status workflow",
1349
1349
  }
1350
1350
  if status in (STATUS_BLOCKED, STATUS_PENDING) and rationale:
1351
1351
  return {
1352
1352
  "command": "",
1353
1353
  "note": "quote the rationale above and issue the command it names",
1354
1354
  }
1355
- return {"command": "/okstra-inspect status", "note": ""}
1355
+ return {"command": "okstra task-show <task-key>", "note": "replace <task-key> with the full task key"}
1356
1356
 
1357
1357
 
1358
1358
  def _next_phase_summary_lines(result: Mapping[str, Any]) -> list[str]:
@@ -15,6 +15,7 @@ from okstra_token_usage.blocks import accounting_workers
15
15
 
16
16
  from .analysis_packet import reference_source_extracts
17
17
  from .correction_round import correction_convergence_states
18
+ from .dispatch_state import UNSUCCESSFUL_WORKER_STATUSES
18
19
  from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
19
20
  from .phases.implementation_option_selection.authoring import (
20
21
  requirement_instructions as selection_requirement_instructions,
@@ -849,6 +850,10 @@ def _source_specs(
849
850
  for worker in workers:
850
851
  if not isinstance(worker, Mapping) or worker.get("workerId") == "report-writer":
851
852
  continue
853
+ # Such a worker settled no result, whatever file it left; a run closed with
854
+ # no verifier result still owes the writer a report.
855
+ if worker.get("status") in UNSUCCESSFUL_WORKER_STATUSES:
856
+ continue
852
857
  path = _string(worker.get("resultPath"))
853
858
  if path:
854
859
  worker_id = _string(worker.get("workerId")) or "unknown"
@@ -47,7 +47,7 @@ from typing import Mapping, Sequence
47
47
 
48
48
  from okstra_project import project_json_path, upsert_project_json
49
49
  from okstra_project.slug import slugify
50
- from .phases.catalog import host_rules
50
+ from .phases.catalog import INPUT_DOCUMENT_TASK_TYPES, host_rules
51
51
  from .phases.implementation_planning.entry import (
52
52
  _resolve_planning_input_path,
53
53
  _validate_planning_entry_inputs,
@@ -97,6 +97,7 @@ from .implementation_direction import (
97
97
  )
98
98
  from .qa_commands import (
99
99
  QA_COMMAND_EXECUTING_TASK_TYPES,
100
+ QA_VERIFIER_AUDIENCE_BY_TASK_TYPE,
100
101
  format_errors as _format_qa_errors,
101
102
  validate_qa_commands,
102
103
  )
@@ -442,9 +443,13 @@ def _validate_approved_plan_conformance(path: Path) -> None:
442
443
  data_path, data = loaded
443
444
  from .implementation_direction import stage_validation_executability_errors
444
445
 
445
- command_errors = stage_validation_executability_errors(
446
- data.get("implementationPlanning") or {}
447
- )
446
+ from .stage_command_commits import stage_command_commit_errors_from_task_state
447
+
448
+ planning = data.get("implementationPlanning") or {}
449
+ command_errors = [
450
+ *stage_validation_executability_errors(planning),
451
+ *stage_command_commit_errors_from_task_state(data_path, data),
452
+ ]
448
453
  if command_errors:
449
454
  raise PrepareError(
450
455
  f"approved plan command preflight failed: {data_path}\n"
@@ -453,10 +458,9 @@ def _validate_approved_plan_conformance(path: Path) -> None:
453
458
  bad = malformed_conformance_stages(data)
454
459
  if not bad:
455
460
  return
456
- planning = data.get("implementationPlanning") if isinstance(data, dict) else None
457
461
  declared_by_stage = {
458
462
  stage.get("stage"): stage.get("conformanceTests")
459
- for stage in (planning or {}).get("stages") or []
463
+ for stage in planning.get("stages") or []
460
464
  if isinstance(stage, dict)
461
465
  }
462
466
  # 한 stage 씩 고치고 다시 막히는 왕복을 피하려면 전부 나열해야 한다 —
@@ -820,7 +824,10 @@ def _published_run_seqs(run_dir: Path, task_type_segment: str) -> dict[str, str]
820
824
  매니페스트의 `runSequencesByCategory` 가 같은 런의 나머지 카테고리 seq 를
821
825
  묶는 유일한 기록이다. 재실행이 카테고리별로 다른 속도로 올라가므로
822
826
  (`paths.next_run_seq` 가 디렉터리마다 따로 스캔한다) 이 대응 없이는 "리포트
823
- 017 의 worker-results 는 몇 번인가" 에 답할 방법이 없다.
827
+ 017 의 worker-results 는 몇 번인가" 에 답할 방법이 없다. The divergence
828
+ above describes runs prepared before `compute_run_paths` gave every
829
+ category one seq; newer runs share one seq across categories, and this
830
+ mapping still resolves the older ones.
824
831
  """
825
832
  reports = run_dir / "reports"
826
833
  manifests = run_dir / "manifests"
@@ -1428,7 +1435,7 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
1428
1435
  f"got {inp.task_type}"
1429
1436
  )
1430
1437
  validate_discussion_start(project_root, inp)
1431
- if inp.task_type in ("release-handoff", "discussion"):
1438
+ if inp.task_type in INPUT_DOCUMENT_TASK_TYPES:
1432
1439
  # brief 는 entry phase 의 입력물 — release-handoff 는 검증 보고서를
1433
1440
  # 인용하는 input 문서를 prepare 가 직접 생성해 brief 자리에 채운다
1434
1441
  # (materialize_handoff_input, 이 검증 직후 실행). discussion 은 시작
@@ -1567,11 +1574,6 @@ def _validate_selected_implementation_plan(
1567
1574
  expected_task_root,
1568
1575
  "selected direction snapshot",
1569
1576
  )
1570
- brief_path = validate_task_artifact_path(
1571
- expected_task_root / "instruction-set" / "task-brief.md",
1572
- expected_task_root,
1573
- "selected direction task brief",
1574
- )
1575
1577
  except DirectionSelectionError as exc:
1576
1578
  raise PrepareError(f"selected-direction plan input is invalid: {exc}") from exc
1577
1579
 
@@ -1582,7 +1584,9 @@ def _validate_selected_implementation_plan(
1582
1584
  "selected-direction plan header.taskKey must match the implementation "
1583
1585
  f"task: expected {expected_task_key!r}, got {actual_task_key!r}"
1584
1586
  )
1585
- failures = validate_selected_direction_plan(data, brief_path, snapshot_path)
1587
+ # instruction-set/task-brief.md holds whatever brief the task's last run used
1588
+ # (a release-handoff run leaves its input there), so read this run's brief.
1589
+ failures = validate_selected_direction_plan(data, Path(inp.brief_path), snapshot_path)
1586
1590
  if failures:
1587
1591
  raise PrepareError(
1588
1592
  "selected-direction plan failed implementation entry validation:\n - "
@@ -3809,10 +3813,10 @@ def _allowed_agent_audiences(
3809
3813
  audiences.add("reverification-worker")
3810
3814
  if any(item.worker_id == "report-writer" for item in models.worker_assignments):
3811
3815
  audiences.add("report-writer")
3812
- if inp.task_type == "implementation":
3813
- audiences.update({"implementation-executor", "implementation-verifier"})
3814
- elif inp.task_type == "final-verification":
3815
- audiences.add("acceptance-verifier")
3816
+ if inp.task_type in QA_VERIFIER_AUDIENCE_BY_TASK_TYPE:
3817
+ audiences.add(QA_VERIFIER_AUDIENCE_BY_TASK_TYPE[inp.task_type])
3818
+ if inp.task_type == "implementation":
3819
+ audiences.add("implementation-executor")
3816
3820
  else:
3817
3821
  # Same map the prompt policy resolves the duty from. Allowing a
3818
3822
  # different audience here than the one the policy will ask for makes
@@ -4210,7 +4214,7 @@ def _prepare_user_authorization(inp: PrepareInputs) -> dict:
4210
4214
  "user authorization scope does not match --preselected-direction; confirm the changed scope"
4211
4215
  )
4212
4216
  for key, path in (
4213
- ("task-brief", "" if inp.task_type in ("release-handoff", "discussion") else inp.brief_path),
4217
+ ("task-brief", "" if inp.task_type in INPUT_DOCUMENT_TASK_TYPES else inp.brief_path),
4214
4218
  ("approved-plan", inp.approved_plan_path),
4215
4219
  ("clarification-response", inp.clarification_response_path),
4216
4220
  ("selected-direction", inp.selected_direction_path),
@@ -4277,7 +4281,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
4277
4281
  task_index_template = assets.task_index_template
4278
4282
  final_report_template = assets.final_report_template
4279
4283
  ctx_stage_map = _validate_prepare_inputs(project_root, inp)
4280
- if inp.task_type not in ("release-handoff", "discussion"):
4284
+ if inp.task_type not in INPUT_DOCUMENT_TASK_TYPES:
4281
4285
  _validate_task_brief_preflight(
4282
4286
  project_root,
4283
4287
  inp.brief_path,
@@ -0,0 +1,143 @@
1
+ """Reject a stage-gating validation command naming a commit the stage's worktree lacks.
2
+
3
+ A stage's worktree holds the implementation anchor plus the work of the stages in its
4
+ `dependsOn` closure, nothing else. A command that compares against another branch's
5
+ head fails there before any edit, so the stage can never pass it.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import re
10
+ from functools import cache
11
+ from pathlib import Path
12
+ from typing import Any, Mapping
13
+
14
+ from .incremental_scope import parse_stage_graph
15
+ from .stage_targets import order_stage_closure
16
+ from .worktree import _resolve_commit_sha, is_ancestor
17
+
18
+ # Any 7-40 character hex word may be an abbreviated commit, digits-only included;
19
+ # git resolution decides which ones name a commit.
20
+ _COMMIT_TOKEN = re.compile(r"(?<![0-9A-Za-z])[0-9a-f]{7,40}(?![0-9A-Za-z])")
21
+
22
+
23
+ def stage_command_commit_errors(
24
+ planning: Mapping[str, Any],
25
+ *,
26
+ repo_dir: Path,
27
+ anchor_base: str,
28
+ done_heads: Mapping[int, str],
29
+ ) -> list[str]:
30
+ stage_map = planning.get("stageMap") or ()
31
+ if not isinstance(stage_map, list) or not all(
32
+ isinstance(row, Mapping) for row in stage_map
33
+ ):
34
+ return ["stageMap must be a list of stage rows to check stage command commits"]
35
+ try:
36
+ graph = parse_stage_graph({"implementationPlanning": planning})
37
+ except (KeyError, TypeError, ValueError) as exc:
38
+ return [f"stageMap cannot be read to check stage command commits: {exc!r}"]
39
+ resolve = cache(lambda ref: _resolve_commit_sha(repo_dir, ref))
40
+ contains = cache(lambda tip, commit: is_ancestor(repo_dir, commit, tip))
41
+ failures: list[str] = []
42
+ for row in planning.get("validationChecklist") or ():
43
+ if not isinstance(row, Mapping):
44
+ continue
45
+ stages = [
46
+ stage for stage in row.get("stageRefs") or ()
47
+ if isinstance(stage, int) and not isinstance(stage, bool)
48
+ and stage not in done_heads
49
+ ]
50
+ if not stages:
51
+ continue
52
+ command = str(row.get("commandOrObservation") or "")
53
+ commits = {
54
+ token: commit
55
+ for token in dict.fromkeys(_COMMIT_TOKEN.findall(command))
56
+ if (commit := resolve(token))
57
+ }
58
+ if not commits:
59
+ continue
60
+ for stage in stages:
61
+ tips = _worktree_tips(stage, graph, anchor_base, done_heads)
62
+ if not tips:
63
+ continue
64
+ unresolved = [tip for tip in tips if not resolve(tip)]
65
+ if unresolved:
66
+ failures.append(
67
+ f"validationChecklist {row.get('id')} gates stage {stage}, whose "
68
+ f"worktree base commit(s) {unresolved} do not resolve in this "
69
+ "repository; reconcile the implementation anchor or the consumers "
70
+ "ledger (`okstra git-reconcile`) before judging the command"
71
+ )
72
+ continue
73
+ missing = [
74
+ token for token, commit in commits.items()
75
+ if not any(contains(tip, commit) for tip in tips)
76
+ ]
77
+ if missing:
78
+ failures.append(
79
+ f"validationChecklist {row.get('id')} gates stage {stage} but "
80
+ f"names commit(s) {missing} that stage {stage}'s worktree does not "
81
+ "contain: it starts from the implementation anchor and its "
82
+ f"dependsOn closure ({', '.join(tip[:12] for tip in tips)}); "
83
+ "compare against a commit in that chain or remove the stage "
84
+ "from stageRefs"
85
+ )
86
+ return failures
87
+
88
+
89
+ def _worktree_tips(
90
+ stage: int,
91
+ graph: list[tuple[int, list[int]]],
92
+ anchor_base: str,
93
+ done_heads: Mapping[int, str],
94
+ ) -> list[str]:
95
+ closure = order_stage_closure(graph, {stage}, set())
96
+ tips = [anchor_base] if anchor_base else []
97
+ tips.extend(done_heads[number] for number in closure if number in done_heads)
98
+ return tips
99
+
100
+
101
+ def stage_command_commit_errors_from_task_state(
102
+ data_path: Path, data: Mapping[str, Any],
103
+ ) -> list[str]:
104
+ """Judge the plan record at ``data_path`` against the task's recorded stage bases.
105
+
106
+ The anchor comes from the worktree registry and the done heads from the consumers
107
+ ledger of the planning run that owns the record. Returns failure lines; a plan
108
+ with no task key yields none, since no recorded base can be looked up for it.
109
+ """
110
+ from okstra_project.state import StateError, parse_task_key
111
+
112
+ from .consumers import read_stage_consumer_state
113
+ from .worktree_registry import get_implementation_base
114
+
115
+ header = data.get("header")
116
+ task_key = header.get("taskKey") if isinstance(header, Mapping) else None
117
+ try:
118
+ project_id, task_group, task_id = parse_task_key(str(task_key or ""))
119
+ except StateError:
120
+ # expected-miss: the report schema checks the header; without a task key there
121
+ # is no recorded anchor or ledger to judge the plan against.
122
+ return []
123
+ reports_dir = data_path.parent
124
+ plan_run_root = reports_dir.parent
125
+ try:
126
+ state = read_stage_consumer_state(plan_run_root)
127
+ except (OSError, UnicodeError) as exc:
128
+ return [
129
+ "stage command commit check could not read the consumers ledger under "
130
+ f"{plan_run_root}: {exc}"
131
+ ]
132
+ done_heads = {
133
+ stage: str(row.get("head_commit") or "")
134
+ for stage, row in state.done_by_stage.items()
135
+ if row.get("head_commit")
136
+ }
137
+ planning = data.get("implementationPlanning")
138
+ return stage_command_commit_errors(
139
+ planning if isinstance(planning, Mapping) else {},
140
+ repo_dir=reports_dir,
141
+ anchor_base=get_implementation_base(project_id, task_group, task_id) or "",
142
+ done_heads=done_heads,
143
+ )