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
@@ -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
+ )
@@ -17,7 +17,9 @@ from pathlib import Path
17
17
 
18
18
  from .consumers import read_consumers
19
19
  from .json_boundary import JsonBoundaryError, load_owned_object
20
+ from .paths import RunRef
20
21
  from .phases.implementation.validation import lead_fixed_verifiers
22
+ from .report_inputs import uses_execution_evidence
21
23
 
22
24
  _REPORT_RE = re.compile(r"final-report-implementation-(\d+)\.data\.json$")
23
25
  _SEQ_RE = re.compile(r"-(\d+)\.data\.json$")
@@ -113,7 +115,7 @@ def derive_stage_fix_carry(
113
115
  if not isinstance(impl, dict):
114
116
  return None
115
117
  # 통과한 리드 수정이 답한 FAIL 은 그 run 안에서 해소됐다 — 다시 fix run 으로 넘기지 않는다.
116
- fixed = lead_fixed_verifiers(impl)
118
+ fixed = lead_fixed_verifiers(impl, evidence_contract=_evidence_contract(report))
117
119
  failed = [
118
120
  row for row in impl.get("verifierResults") or []
119
121
  if isinstance(row, dict) and row.get("verdict") == "FAIL"
@@ -231,6 +233,24 @@ def _routing_line(value: object) -> str:
231
233
  return target or rationale
232
234
 
233
235
 
236
+ def _evidence_contract(report: Path) -> bool:
237
+ """Whether the report's run is under the verification evidence contract. An
238
+ unsupported contract version counts as one, so its lead fixes resolve
239
+ nothing."""
240
+ try:
241
+ manifest = load_owned_object(
242
+ RunRef.from_report_path(report).manifest, artifact="run manifest",
243
+ )
244
+ except (OSError, JsonBoundaryError, ValueError):
245
+ # expected-miss: a report from before run manifests sat beside it is
246
+ # from before the contract existed.
247
+ return False
248
+ try:
249
+ return uses_execution_evidence(manifest)
250
+ except ValueError:
251
+ return True
252
+
253
+
234
254
  def _latest_report(stage_run_dir: Path) -> Path | None:
235
255
  reports_dir = stage_run_dir / "reports"
236
256
  if not reports_dir.is_dir():
@@ -18,6 +18,7 @@ from pathlib import Path
18
18
  from typing import Any
19
19
 
20
20
  from .worktree import _git
21
+ from .worktree.git_ops import WITHOUT_HOOKS
21
22
 
22
23
 
23
24
  class IntegrateError(Exception):
@@ -45,13 +46,14 @@ class StageMergeBranch:
45
46
  class MergeBranchConflict(IntegrateError):
46
47
  """선행 stage 들끼리 내용이 충돌해 공통 바닥을 만들 수 없다."""
47
48
 
48
- def __init__(self, stage: int, branch: str, paths: list[str]):
49
+ def __init__(self, stage: int, branch: str, paths: list[str],
50
+ recovery: str):
49
51
  self.stage = stage
50
52
  self.branch = branch
51
53
  self.paths = paths
52
54
  super().__init__(
53
55
  f"merge conflict while merging stage {stage} ({branch}): "
54
- f"{', '.join(paths)}")
56
+ f"{', '.join(paths)}. {recovery}")
55
57
 
56
58
 
57
59
  def ensure_stage_merge_branch(
@@ -78,8 +80,7 @@ def ensure_stage_merge_branch(
78
80
  재진입이 안 되므로 여기서 다시 잡으면 이미 락을 쥔 implementation 경로가
79
81
  교착한다 — `_resolve_and_integrate_whole_task_unlocked` 와 같은 분리다.
80
82
  """
81
- from .worktree import (compute_branch_name, compute_worktree_path,
82
- is_ancestor, remove_worktree_force, stage_group_id)
83
+ from .worktree import compute_branch_name, stage_group_id
83
84
 
84
85
  if not heads:
85
86
  raise IntegrateError("ensure_stage_merge_branch requires at least one stage")
@@ -88,42 +89,82 @@ def ensure_stage_merge_branch(
88
89
  task_id_segment=task_id,
89
90
  group_id=stage_group_id(stages))
90
91
  root = Path(project_root)
92
+ if not anchor_base:
93
+ raise IntegrateError(
94
+ f"cannot create or reuse {branch}: the implementation base commit "
95
+ "is not recorded in the worktree registry — run at least one "
96
+ "implementation stage first")
91
97
  if _branch_exists(root, branch):
92
- tip = _rev_parse(root, branch)
93
- missing = [n for n in stages if not is_ancestor(root, heads[n], tip)]
98
+ missing = _heads_missing_from(root, branch, heads, anchor_base)
94
99
  if not missing:
95
- return StageMergeBranch(branch=branch, commit=tip, created=False,
96
- stages=stages, merge_commits=[])
100
+ return StageMergeBranch(branch=branch, commit=_rev_parse(root, branch),
101
+ created=False, stages=stages,
102
+ merge_commits=[])
97
103
  if not advance_existing:
98
104
  raise IntegrateError(
99
- f"merge-base branch {branch} exists but stage(s) {missing} "
100
- "are not merged into it — delete the branch and retry so "
101
- "okstra can rebuild it")
105
+ f"merge-base branch {branch} exists but stage(s) "
106
+ f"{sorted(missing)} are not merged into it — delete the "
107
+ "branch and retry so okstra can rebuild it")
102
108
  # 기존 브랜치를 그대로 체크아웃해 빠진 commit 만 얹는다.
103
- creating, start = False, branch
104
- to_merge = {n: heads[n] for n in missing}
109
+ creating, start, to_merge = False, branch, missing
105
110
  else:
106
- if not anchor_base:
107
- raise IntegrateError(
108
- f"cannot create {branch}: the implementation base commit is not "
109
- "recorded in the worktree registry — run at least one "
110
- "implementation stage first")
111
- creating, start = True, anchor_base
112
- to_merge = dict(heads)
111
+ creating, start, to_merge = True, anchor_base, dict(heads)
112
+ return _build_merge_branch(
113
+ root, branch=branch, stages=stages, creating=creating, start=start,
114
+ anchor_base=anchor_base, to_merge=to_merge, project_id=project_id,
115
+ task_group=task_group, task_id=task_id, work_category=work_category)
116
+
117
+
118
+ def _heads_missing_from(root: Path, branch: str, heads: dict[int, str],
119
+ anchor_base: str) -> dict[int, str]:
120
+ """Validate an existing merge-base branch and return the heads it lacks."""
121
+ from .worktree import is_ancestor
122
+
123
+ tip = _rev_parse(root, branch)
124
+ if not is_ancestor(root, anchor_base, tip):
125
+ raise IntegrateError(
126
+ f"merge-base branch {branch} does not contain the anchor "
127
+ f"{anchor_base} — it was not built from the implementation "
128
+ "base; delete the branch and retry so okstra can rebuild it")
129
+ # Merge commits are okstra's own merges or a person's conflict resolution;
130
+ # any other commit came from outside the anchor and the predecessors.
131
+ foreign = _git(root, "rev-list", "--no-merges", tip, f"^{anchor_base}",
132
+ *(f"^{head}" for head in heads.values())).stdout.split()
133
+ if foreign:
134
+ raise IntegrateError(
135
+ f"merge-base branch {branch} carries {len(foreign)} commit(s) that "
136
+ f"are in neither the anchor nor a predecessor stage, such as "
137
+ f"{foreign[0]} — delete the branch and retry so okstra can "
138
+ "rebuild it")
139
+ return {n: heads[n] for n in sorted(heads)
140
+ if not is_ancestor(root, heads[n], tip)}
141
+
142
+
143
+ def _build_merge_branch(
144
+ root: Path, *, branch: str, stages: list[int], creating: bool, start: str,
145
+ anchor_base: str, to_merge: dict[int, str], project_id: str,
146
+ task_group: str, task_id: str, work_category: str,
147
+ ) -> StageMergeBranch:
148
+ """Merge `to_merge` onto `start` in a scratch worktree that is removed
149
+ afterwards; a branch this call created is deleted again on failure."""
150
+ from .worktree import (compute_worktree_path, remove_worktree_force,
151
+ stage_group_id)
113
152
 
114
153
  wt_path = compute_worktree_path(
115
154
  project_id=project_id, task_group_segment=task_group,
116
155
  task_id_segment=task_id, group_id=stage_group_id(stages))
117
156
  wt_path.parent.mkdir(parents=True, exist_ok=True)
118
- add = _git(root, "worktree", "add",
157
+ add = _git(root, *WITHOUT_HOOKS, "worktree", "add",
119
158
  *(["-b", branch] if creating else []), str(wt_path), start)
120
159
  if add.returncode != 0:
121
160
  raise IntegrateError(
122
161
  f"git worktree add for {branch} failed: "
123
162
  f"{(add.stderr or add.stdout).strip()}")
124
163
  try:
125
- merge_commits = _merge_heads_into(wt_path, to_merge, work_category,
126
- task_id)
164
+ merge_commits = _merge_heads_into(
165
+ wt_path, to_merge, work_category, task_id,
166
+ recovery=_conflict_recovery(branch, creating, start, anchor_base,
167
+ to_merge))
127
168
  commit = _rev_parse(wt_path, "HEAD")
128
169
  except Exception:
129
170
  remove_worktree_force(root, wt_path)
@@ -135,8 +176,32 @@ def ensure_stage_merge_branch(
135
176
  stages=stages, merge_commits=merge_commits)
136
177
 
137
178
 
179
+ def _conflict_recovery(branch: str, creating: bool, start: str, anchor: str,
180
+ heads: dict[int, str]) -> str:
181
+ """The manual build of `branch` that a retry accepts: the same start, merge
182
+ order and disabled hooks okstra uses, with the conflict resolved by a
183
+ person, whose resolving commit still runs the repository's hooks."""
184
+ no_hooks = " ".join(WITHOUT_HOOKS)
185
+ if creating:
186
+ intro = f"To recover, build {branch} by hand from the anchor"
187
+ checkout = f"git {no_hooks} worktree add -b {branch} <dir> {start}"
188
+ else:
189
+ intro = (f"{branch} was left at its previous tip. To recover, finish it "
190
+ "by hand")
191
+ checkout = f"git {no_hooks} worktree add <dir> {branch}"
192
+ merges = "; ".join(
193
+ f"`git -C <dir> {no_hooks} merge --no-ff --no-edit {heads[n]}` "
194
+ f"(stage {n})" for n in sorted(heads))
195
+ return (
196
+ f"{intro}: `{checkout}`, then {merges}, in that order. Resolve each "
197
+ "conflict, run the project's checks and commit the merge, then "
198
+ "`git worktree remove <dir>` and retry the same command. okstra reuses "
199
+ f"{branch} only when it contains the anchor {anchor} and every "
200
+ "predecessor commit, and no other non-merge commit")
201
+
202
+
138
203
  def _merge_heads_into(wt_path, heads: dict[int, str], work_category: str,
139
- task_id: str) -> list[str]:
204
+ task_id: str, *, recovery: str) -> list[str]:
140
205
  """stage 번호 순서로 done commit 을 `--no-ff` 머지한다. 이미 담긴 commit 은
141
206
  git 이 `Already up to date` 로 지나가므로 빈 머지 커밋이 생기지 않는다."""
142
207
  from .worktree import MergeError, compute_branch_name, merge_branch
@@ -154,7 +219,7 @@ def _merge_heads_into(wt_path, heads: dict[int, str], work_category: str,
154
219
  ) from exc
155
220
  if conflicts is not None:
156
221
  raise MergeBranchConflict(stage=n, branch=stage_branch,
157
- paths=conflicts)
222
+ paths=conflicts, recovery=recovery)
158
223
  merge_commits.append(_rev_parse(wt_path, "HEAD"))
159
224
  return merge_commits
160
225
 
@@ -0,0 +1,291 @@
1
+ """Byte-exact capture of one verification command's output and process group."""
2
+ from __future__ import annotations
3
+
4
+ import hashlib
5
+ import os
6
+ import select
7
+ import selectors
8
+ import signal
9
+ import stat
10
+ import subprocess
11
+ import time
12
+ from dataclasses import dataclass
13
+ from pathlib import Path
14
+ from typing import Callable, Sequence
15
+
16
+ from .process_group import kill_group, live_group_members
17
+
18
+ DRAIN_AFTER_EXIT_SECONDS = 2.0
19
+ CLEANUP_GRACE_SECONDS = 5.0
20
+ _SELECT_SECONDS = 0.1
21
+ _READ_SIZE = 65536
22
+ # A forwarding destination that falls this far behind is not reading; its
23
+ # copy is dropped so the saved evidence and the deadlines keep going.
24
+ _FORWARD_BACKLOG_BYTES = 4 * 1024 * 1024
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class StreamCapture:
29
+ """`bytes` and `digest` describe what the pipe delivered; the file at
30
+ `path` holds exactly those bytes only when `save_error` is None."""
31
+
32
+ path: Path
33
+ bytes: int
34
+ digest: str
35
+ save_error: str | None
36
+ forward_error: str | None
37
+
38
+
39
+ @dataclass(frozen=True)
40
+ class CommandCapture:
41
+ returncode: int
42
+ drain_complete: bool
43
+ cleanup: str
44
+ interrupted: bool
45
+ stdout: StreamCapture
46
+ stderr: StreamCapture
47
+
48
+
49
+ class _Stream:
50
+ def __init__(self, path: Path, forward_fd: int) -> None:
51
+ self.path = path
52
+ self.hash = hashlib.sha256()
53
+ self.size = 0
54
+ self.save_error: str | None = None
55
+ self.forward_error: str | None = None
56
+ self.pending = bytearray()
57
+ self.save_fd: int | None = None
58
+ self.forward_fd: int | None = None
59
+ try:
60
+ self.save_fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
61
+ except OSError as exc:
62
+ self.save_error = str(exc)
63
+ mode = 0
64
+ try:
65
+ # A private descriptor, so two streams forwarded to one pipe still
66
+ # register separately and closing it never closes the caller's.
67
+ self.forward_fd = os.dup(forward_fd)
68
+ mode = os.fstat(self.forward_fd).st_mode
69
+ except OSError as exc:
70
+ self.drop_forward(str(exc))
71
+ # A write larger than PIPE_BUF to a writable pipe can still block.
72
+ self.forward_chunk = None if stat.S_ISREG(mode) else select.PIPE_BUF
73
+
74
+ def feed(self, chunk: bytes) -> None:
75
+ self.hash.update(chunk)
76
+ self.size += len(chunk)
77
+ if self.save_fd is not None:
78
+ try:
79
+ _write_all(self.save_fd, chunk)
80
+ except OSError as exc:
81
+ # Draining continues so the child never blocks on a full pipe;
82
+ # save_error marks the saved file as short.
83
+ self.save_error = str(exc)
84
+ os.close(self.save_fd)
85
+ self.save_fd = None
86
+ if self.forward_fd is None:
87
+ return
88
+ self.pending += chunk
89
+ if self.forward_chunk is None:
90
+ self.forward()
91
+ elif len(self.pending) > _FORWARD_BACKLOG_BYTES:
92
+ self.drop_forward("the forwarding destination stopped reading")
93
+
94
+ def forward(self) -> None:
95
+ """Write what the destination accepts now; called when it is writable."""
96
+ assert self.forward_fd is not None
97
+ try:
98
+ if self.forward_chunk is None:
99
+ _write_all(self.forward_fd, self.pending)
100
+ self.pending.clear()
101
+ else:
102
+ written = os.write(self.forward_fd, self.pending[:self.forward_chunk])
103
+ del self.pending[:written]
104
+ except OSError as exc:
105
+ self.drop_forward(str(exc))
106
+
107
+ def drop_forward(self, reason: str) -> None:
108
+ self.forward_error = self.forward_error or reason
109
+ self.pending.clear()
110
+ if self.forward_fd is not None:
111
+ os.close(self.forward_fd)
112
+ self.forward_fd = None
113
+
114
+ def close(self) -> None:
115
+ for fd in (self.save_fd, self.forward_fd):
116
+ if fd is not None:
117
+ os.close(fd)
118
+ self.save_fd = self.forward_fd = None
119
+
120
+ def result(self) -> StreamCapture:
121
+ return StreamCapture(
122
+ self.path, self.size, "sha256:" + self.hash.hexdigest(),
123
+ self.save_error, self.forward_error,
124
+ )
125
+
126
+
127
+ @dataclass
128
+ class _Stop:
129
+ sent_at: float | None = None
130
+ killed: bool = False
131
+ drained: bool = False
132
+
133
+
134
+ def _write_all(fd: int, chunk: bytes | bytearray) -> None:
135
+ view = memoryview(chunk)
136
+ while view:
137
+ view = view[os.write(fd, view):]
138
+
139
+
140
+ def run_captured(
141
+ argv: Sequence[str], cwd: Path, *, stdout_path: Path, stderr_path: Path,
142
+ stop_requested: Callable[[], bool], forward: tuple[int, int] = (1, 2),
143
+ drain_seconds: float = DRAIN_AFTER_EXIT_SECONDS,
144
+ grace_seconds: float = CLEANUP_GRACE_SECONDS,
145
+ ) -> CommandCapture:
146
+ """Run argv in its own process group, save and forward both streams.
147
+
148
+ Reads and forwarding writes share one select loop, so neither a full pipe
149
+ nor a destination that stops reading stalls the other stream, the
150
+ interruption or the drain deadline. That deadline is set once when the
151
+ main process exits; grandchild output never extends it.
152
+ """
153
+ streams = (_Stream(stdout_path, forward[0]), _Stream(stderr_path, forward[1]))
154
+ try:
155
+ process = subprocess.Popen(
156
+ list(argv), cwd=cwd, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
157
+ stderr=subprocess.PIPE, start_new_session=True,
158
+ )
159
+ except BaseException:
160
+ for stream in streams:
161
+ stream.close()
162
+ raise
163
+ stop = _Stop()
164
+ try:
165
+ _drain(process, streams, stop, stop_requested, drain_seconds, grace_seconds)
166
+ finally:
167
+ returncode, cleanup = _end_group(process, stop, grace_seconds)
168
+ for stream in streams:
169
+ stream.close()
170
+ return CommandCapture(
171
+ returncode, stop.drained, cleanup, stop.sent_at is not None,
172
+ streams[0].result(), streams[1].result(),
173
+ )
174
+
175
+
176
+ def _drain(
177
+ process: subprocess.Popen[bytes], streams: tuple[_Stream, _Stream],
178
+ stop: _Stop, stop_requested: Callable[[], bool], drain_seconds: float,
179
+ grace_seconds: float,
180
+ ) -> None:
181
+ assert process.stdout is not None and process.stderr is not None
182
+ with selectors.DefaultSelector() as selector:
183
+ for pipe, stream in zip((process.stdout, process.stderr), streams):
184
+ selector.register(pipe, selectors.EVENT_READ, stream)
185
+ deadline: float | None = None
186
+ while (_reading(selector) or any(s.pending for s in streams)
187
+ or not _exited(process)):
188
+ _escalate(process, stop, stop_requested, grace_seconds)
189
+ _watch_forwarding(selector, streams)
190
+ _pump_once(selector)
191
+ if deadline is None and _exited(process):
192
+ deadline = time.monotonic() + drain_seconds
193
+ if deadline is not None and time.monotonic() >= deadline:
194
+ break
195
+ stop.drained = not _reading(selector)
196
+ for stream in streams:
197
+ if stream.pending:
198
+ stream.drop_forward("the forwarded copy was cut at the drain deadline")
199
+
200
+
201
+ def _reading(selector: selectors.BaseSelector) -> bool:
202
+ return any(key.events & selectors.EVENT_READ
203
+ for key in selector.get_map().values())
204
+
205
+
206
+ def _escalate(
207
+ process: subprocess.Popen[bytes], stop: _Stop,
208
+ stop_requested: Callable[[], bool], grace_seconds: float,
209
+ ) -> None:
210
+ if stop.sent_at is None and stop_requested():
211
+ stop.sent_at = time.monotonic()
212
+ kill_group(process.pid, signal.SIGTERM)
213
+ if (stop.sent_at is not None and not stop.killed
214
+ and time.monotonic() - stop.sent_at >= grace_seconds):
215
+ stop.killed = True
216
+ kill_group(process.pid)
217
+
218
+
219
+ def _watch_forwarding(
220
+ selector: selectors.BaseSelector, streams: tuple[_Stream, _Stream],
221
+ ) -> None:
222
+ """Watch a destination for writability only while it has pending bytes.
223
+
224
+ A destination dropped since the last pass has a closed descriptor, so its
225
+ registration is removed before the next select.
226
+ """
227
+ for key in list(selector.get_map().values()):
228
+ if key.events & selectors.EVENT_WRITE and (
229
+ key.data.forward_fd != key.fd or not key.data.pending):
230
+ selector.unregister(key.fileobj)
231
+ registered = selector.get_map()
232
+ for stream in streams:
233
+ fd = stream.forward_fd
234
+ if stream.pending and fd is not None and fd not in registered:
235
+ selector.register(fd, selectors.EVENT_WRITE, stream)
236
+
237
+
238
+ def _pump_once(selector: selectors.BaseSelector) -> None:
239
+ if not selector.get_map():
240
+ time.sleep(_SELECT_SECONDS)
241
+ return
242
+ for key, events in selector.select(timeout=_SELECT_SECONDS):
243
+ stream: _Stream = key.data
244
+ if events & selectors.EVENT_WRITE:
245
+ if stream.forward_fd == key.fd:
246
+ stream.forward()
247
+ continue
248
+ chunk = os.read(key.fd, _READ_SIZE)
249
+ if chunk:
250
+ stream.feed(chunk)
251
+ else:
252
+ selector.unregister(key.fileobj)
253
+
254
+
255
+ def _end_group(
256
+ process: subprocess.Popen[bytes], stop: _Stop, grace_seconds: float,
257
+ ) -> tuple[int, str]:
258
+ """Kill the group, reap the main process, and confirm the group gone.
259
+
260
+ The main process stays unreaped until the kill, so its pid, which is the
261
+ group id, cannot be reused by an unrelated group first. An interrupted
262
+ group keeps the rest of its grace even when its leader exited early.
263
+ """
264
+ if stop.sent_at is not None and not stop.killed:
265
+ _await_no_live_member(process.pid, stop.sent_at + grace_seconds)
266
+ kill_group(process.pid)
267
+ returncode = process.wait()
268
+ for pipe in (process.stdout, process.stderr):
269
+ if pipe is not None:
270
+ pipe.close()
271
+ gone = _await_no_live_member(process.pid, time.monotonic() + grace_seconds)
272
+ return returncode, "confirmed" if gone else "unconfirmed"
273
+
274
+
275
+ def _exited(process: subprocess.Popen[bytes]) -> bool:
276
+ """Whether the main process exited, observed without reaping it."""
277
+ try:
278
+ return os.waitid(
279
+ os.P_PID, process.pid, os.WEXITED | os.WNOHANG | os.WNOWAIT,
280
+ ) is not None
281
+ except ChildProcessError:
282
+ return process.poll() is not None
283
+
284
+
285
+ def _await_no_live_member(pgid: int, limit: float) -> bool:
286
+ while True:
287
+ if live_group_members(pgid) == 0:
288
+ return True
289
+ if time.monotonic() >= limit:
290
+ return False
291
+ time.sleep(_SELECT_SECONDS)