okstra 0.67.0 → 0.69.0

package/runtime/python/okstra_ctl/render.py

@@ -1641,8 +1641,11 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     # - release-handoff (and any other phase that renders with no workers
     #   selected) is single-lead and MUST NOT call `TeamCreate`. Emit a
     #   short notice instead of the BLOCKING gate.
+    # - concurrent implementation runs skip team creation to avoid racing the
+    #   shared `~/.claude/teams/` config.
     # - All other phases keep the full team-creation contract.
     task_type = ctx.get("TASK_TYPE", "")
+    concurrent_stages = str(ctx.get("CONCURRENT_RUN_STAGES", "") or "").strip()
     if task_type == "release-handoff" or not selected:
         team_creation_gate_block = (
             "## Single-Lead Phase (no team creation)\n"
@@ -1655,7 +1658,34 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "report). Do NOT call `TeamCreate` or dispatch any sub-agent\n"
             "from this run — that would be a contract violation."
         )
+    elif task_type == "implementation" and concurrent_stages:
+        team_creation_gate_block = (
+            "## Concurrent-run: no-team background (BLOCKING)\n"
+            "\n"
+            "A concurrent implementation run of the same task-key holds stage(s)\n"
+            f"`{concurrent_stages}` right now. Creating a team would race the shared\n"
+            "`~/.claude/teams/` config and can make another stage's `config.json`\n"
+            "unreadable. This run therefore does NOT create a team.\n"
+            "\n"
+            "Required actions, in order:\n"
+            "\n"
+            "1. Do NOT call `TeamCreate`, and do NOT dispatch any worker with\n"
+            "   `Agent(... team_name: ...)`.\n"
+            "2. Before any dispatch, record in team-state:\n"
+            '   `teamCreate: { attempted: false, status: "skipped",'
+            f' reason: "concurrent-run", concurrentStages: [{concurrent_stages}] }}`.\n'
+            "3. Dispatch every worker with `run_in_background: true` and NO\n"
+            "   `team_name` (the Phase 5 fallback). Worker completion is detected by\n"
+            "   result-file polling, so analysis output is equivalent — only the\n"
+            "   Teams split-pane view is lost."
+        )
     else:
+        team_name = f'okstra-{ctx.get("TASK_KEY", "")}'
+        stage = str(ctx.get("EFFECTIVE_STAGES", "") or "").strip()
+        if task_type == "implementation" and stage:
+            # stage 격리 run 은 stage 별 team — 같은 task 의 다른 stage 가 남긴
+            # team 과 이름이 충돌하지 않는다(worktree branch `-s<N>` 접미사와 동형).
+            team_name = f"{team_name}-s{stage}"
         team_creation_gate_block = (
             "## Team Creation Gate (BLOCKING)\n"
             "\n"
@@ -1671,14 +1701,26 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "\n"
             "1. Invoke the `okstra-team-contract` skill and verify the selected worker\n"
             "   roster against `task-manifest.json`'s `resultContract.requiredWorkerRoles`.\n"
-            f'2. Call `TeamCreate(team_name: "okstra-{ctx.get("TASK_KEY", "")}", description: ...)`.\n'
+            f'2. Call `TeamCreate(team_name: "{team_name}", description: ...)`.\n'
             "3. Record the outcome in team-state under\n"
             '   `teamCreate: { attempted: true, status: "ok" | "error", error?: <msg> }`\n'
-            "   BEFORE any `Agent(...)` worker dispatch.\n"
+            "   AND record the exact name as `teamName` BEFORE any `Agent(...)` worker\n"
+            "   dispatch.\n"
             "4. Only after `teamCreate` is persisted may you dispatch workers — with\n"
             "   `team_name` on success, or with `run_in_background: true` and no\n"
             '   `team_name` ONLY when `teamCreate.status == "error"` was recorded.\n'
             "\n"
+            'If `TeamCreate` fails with "team already exists" (stale leftover from an\n'
+            "earlier attempt): call `TeamList`; if the team is listed in this session,\n"
+            "`TeamDelete` it and retry step 2 once. If it is NOT listed, do NOT remove\n"
+            "`~/.claude/teams/...` / `~/.claude/tasks/...` on your own initiative —\n"
+            "shell deletion of harness-internal state is destructive and `rm -rf` is\n"
+            "commonly denied by user permission rules. Instead ask the user via\n"
+            "AskUserQuestion (recommended option: quarantine), and on approval move\n"
+            f"`~/.claude/teams/{team_name}` and `~/.claude/tasks/{team_name}` into\n"
+            "`~/.okstra/trash/<UTC-timestamp>/` with `mv` (reversible, no delete),\n"
+            "then retry step 2 once.\n"
+            "\n"
             'If the Agent tool rejects a dispatch with `"team must be created first"` /\n'
             '`"team을 먼저 생성하거나 team_name 없이 호출해야 합니다"`, the correct\n'
             "response is to go back to step 2 — NOT to strip `team_name` and retry."

package/runtime/python/okstra_ctl/run.py

@@ -81,7 +81,11 @@ from .workers import (
 )
 from .workflow import compute_workflow_state
 from .locks import worktree_provision_mutex
-from .worktree import provision_task_worktree
+from .worktree import (
+    WorktreeProvision,
+    okstra_clean_gate_excludes,
+    provision_task_worktree,
+)
 
 # Frontmatter approval-flag matcher.
 #
@@ -462,12 +466,41 @@ def _commit_is_ancestor(project_root, ancestor: str, descendant: str) -> bool:
     return r.returncode == 0
 
 
+def _check_multi_dep_merged(project_root, plan_run_root, latest,
+                            pred_commits: dict, candidate_base: str,
+                            stage_n: int) -> None:
+    """모든 선행 done commit 이 candidate 에 (내용 기준으로라도) 머지됐는지
+    검증. patch-equivalent 면 보정 row 를 자동 기록(다음 run 은 ancestor 로
+    바로 통과). 아니면 회복 안내를 담아 PrepareError."""
+    from .git_reconcile import content_merged, _record_reconciled
+    for d, head in pred_commits.items():
+        if _commit_is_ancestor(project_root, head, candidate_base):
+            continue
+        match = content_merged(project_root, head, candidate_base)
+        if match.status in ("ancestor", "patch-equivalent"):
+            if plan_run_root is not None:
+                _record_reconciled(
+                    plan_run_root,
+                    impl_task_key=(latest.get(d) or {}).get("impl_task_key", ""),
+                    stage=d, new_commit=match.matched_commit,
+                    replaced=head, reason="auto-patch-id")
+            continue
+        raise PrepareError(
+            f"multi-dependency stage {stage_n}: predecessor stage {d} "
+            f"({head[:8]}) is not merged into the task worktree "
+            f"({candidate_base[:8]}). Merge stage branches "
+            f"(e.g. the `-s{d}` branches) into the task worktree "
+            "(or into main, then refresh the worktree) and retry."
+        )
+
+
 def _resolve_stage_base_commit(
     stage: dict,
     consumer_done_rows: list,
     anchor_base_commit: str,
     candidate_base: str = "",
     project_root=None,
+    plan_run_root=None,
 ) -> str:
     """Pick the git base commit a stage's isolated worktree branches from.
 
@@ -479,18 +512,15 @@ def _resolve_stage_base_commit(
       candidate 를 반환(사용자가 선행을 머지함). 아니면 PrepareError.
 
     Raises PrepareError on missing predecessor / anchor / unmerged predecessor."""
+    from .consumers import latest_done_by_stage
+    latest = latest_done_by_stage(consumer_done_rows)
     deps = stage.get("depends_on") or []
     if len(deps) >= 2:
         n = stage["stage_number"]
         # 1) 모든 선행의 done head_commit 수집
         pred_commits = {}
         for d in deps:
-            head = next(
-                (r.get("head_commit") for r in consumer_done_rows
-                 if r.get("stage") == d and r.get("status") == "done"
-                 and r.get("head_commit")),
-                None,
-            )
+            head = (latest.get(d) or {}).get("head_commit")
             if not head:
                 raise PrepareError(
                     f"predecessor stage {d} has no done row with head_commit "
@@ -503,16 +533,10 @@ def _resolve_stage_base_commit(
                 f"candidate base missing for multi-dependency stage {n}; "
                 "task-key worktree HEAD could not be resolved"
             )
-        # 3) 모든 선행 done 이 candidate 의 ancestor 인지 (=사용자가 머지함)
-        for d, head in pred_commits.items():
-            if not _commit_is_ancestor(project_root, head, candidate_base):
-                raise PrepareError(
-                    f"multi-dependency stage {n}: predecessor stage {d} "
-                    f"({head[:8]}) is not merged into the task worktree "
-                    f"({candidate_base[:8]}). Merge stage branches "
-                    f"(e.g. the `-s{d}` branches) into the task worktree "
-                    "(or into main, then refresh the worktree) and retry."
-                )
+        # 3) 모든 선행 done 이 candidate 에 (ancestor 또는 patch-equivalent 로)
+        #    머지됐는지 — patch-equivalent 면 보정 row 를 자동 기록한다.
+        _check_multi_dep_merged(project_root, plan_run_root, latest,
+                                pred_commits, candidate_base, n)
         return candidate_base
     if not deps:
         if not anchor_base_commit:
@@ -524,11 +548,9 @@ def _resolve_stage_base_commit(
         return anchor_base_commit
     # 단일 의존
     pred = deps[0]
-    for row in consumer_done_rows:
-        if row.get("stage") == pred and row.get("status") == "done":
-            head = row.get("head_commit") or ""
-            if head:
-                return head
+    head = (latest.get(pred) or {}).get("head_commit") or ""
+    if head:
+        return head
     raise PrepareError(
         f"predecessor stage {pred} has no done row with head_commit in "
         "consumers.jsonl; cannot derive base for stage "
@@ -553,7 +575,8 @@ def _resolve_whole_task_target(
 ) -> "_FVTarget":
     """전체-task 검증 target. 모든 Stage Map stage 가 done + HEAD 에 머지 +
     worktree clean 이어야 한다. 위반 시 PrepareError."""
-    done_by_stage = {r["stage"]: r for r in done_rows}
+    from .consumers import latest_done_by_stage
+    done_by_stage = latest_done_by_stage(done_rows)
     for s in stage_map:
         n = s["stage_number"]
         if n not in done_by_stage:
@@ -587,8 +610,9 @@ def _resolve_single_stage_target(
 ) -> "_FVTarget":
     """단독-stage 검증 target. stage N 만 done + stage worktree 존재 + clean.
     다른 stage 의 done/머지 여부와 무관. 위반 시 PrepareError."""
+    from .consumers import latest_done_by_stage
     n = int(requested_stage)
-    done_by_stage = {r["stage"]: r for r in done_rows}
+    done_by_stage = latest_done_by_stage(done_rows)
     if n not in done_by_stage:
         raise PrepareError(
             f"final-verification(single-stage): stage {n} not done — "
@@ -1131,6 +1155,46 @@ def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> N
     manifest_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n")
 
 
+def _clear_stale_stage_waiver(inp: "PrepareInputs", project_root: Path, stage: int) -> None:
+    """A fresh `implementation` run of stage N must not inherit a waiver left on
+    its conformance entry by an earlier run (e.g. an all-gate run that pre-waived
+    future stages, or an abandoned attempt). A stale waiver makes the verifier
+    skip Tier 3 conformance and silently mask this stage, so clear it — UNLESS
+    the user re-waived this exact stage for this run via `--qa-waiver` (already
+    applied upstream in `_apply_qa_waiver_if_requested`)."""
+    from .conformance import clear_qa_waiver, parse_qa_waiver_arg
+    from .paths import task_dir
+    manifest_path = (
+        task_dir(project_root, inp.task_group, inp.task_id)
+        / "qa" / "conformance-manifest.json"
+    )
+    if not manifest_path.is_file():
+        return
+    manifest = json.loads(manifest_path.read_text())
+    entries = manifest.get("entries") if isinstance(manifest, dict) else None
+    if not isinstance(entries, list):
+        return
+    # The manifest stageKey is `<task-id>-stage-<N>` authored by planning; match
+    # on the `-stage-<N>` suffix so we do not assume the task-id's exact form.
+    suffix = f"-stage-{stage}"
+    stage_key = next(
+        (e["stageKey"] for e in entries
+         if isinstance(e, dict) and isinstance(e.get("stageKey"), str)
+         and e["stageKey"].endswith(suffix)),
+        None,
+    )
+    if stage_key is None:
+        return
+    if inp.qa_waiver:
+        parsed = parse_qa_waiver_arg(inp.qa_waiver)
+        if parsed is not None and parsed[0] == stage_key:
+            return  # user intentionally waived this stage for this run
+    if clear_qa_waiver(manifest, stage_key):
+        manifest_path.write_text(
+            json.dumps(manifest, indent=2, ensure_ascii=False) + "\n"
+        )
+
+
 def _register_and_check_project(project_root: Path, inp: PrepareInputs) -> None:
     """project.json self-registration + (implementation 한정) qaCommands gate 검증."""
     from okstra_project import ResolverError
@@ -1290,6 +1354,7 @@ class StageSelection:
     worktree_status: str
     worktree_note: str
     started_head_commit: str
+    concurrent_stages: list = field(default_factory=list)
 
 
 def _select_and_provision_implementation_stage(
@@ -1315,6 +1380,7 @@ def _select_and_provision_implementation_stage(
     # carry sidecars are the SSOT for stage completion; recover any `done` rows
     # the lead failed to append before the dependency gate reads them.
     backfill_done_from_carry(plan_run_root)
+    _auto_reconcile_best_effort(inp, plan_run_root)
     consumed = read_consumers(plan_run_root)
     done_stages = {r["stage"] for r in consumed if r.get("status") == "done"}
     started_stages = {r["stage"] for r in consumed if r.get("status") == "started"}
@@ -1327,6 +1393,7 @@ def _select_and_provision_implementation_stage(
         started_stages=started_stages, reserved_stages=reserved_stages,
     )
     selected = batch[0]
+    concurrent_stages = sorted(reserved_stages - {selected})
 
     # spec §2.1 degradation: 주변 흐름이 non-git / nested-worktree 로 skipped 면
     # stage 격리도 동일하게 degrade — worktree 없이 project HEAD 만 기록.
@@ -1340,6 +1407,7 @@ def _select_and_provision_implementation_stage(
             worktree_status=executor_worktree_status,
             worktree_note="",
             started_head_commit=head,
+            concurrent_stages=concurrent_stages,
         )
 
     # anchor base commit 1회 고정 (task-key worktree HEAD 기준)
@@ -1360,6 +1428,7 @@ def _select_and_provision_implementation_stage(
     stage_base = _resolve_stage_base_commit(
         selected_stage, consumer_done_rows, anchor_base_commit=anchor,
         candidate_base=head_sha, project_root=Path(inp.project_root),
+        plan_run_root=plan_run_root,
     )
     try:
         prov = _worktree.provision_stage_worktree(
@@ -1372,7 +1441,12 @@ def _select_and_provision_implementation_stage(
             base_commit=stage_base,
         )
     except RuntimeError as exc:
-        raise PrepareError(f"stage worktree provisioning failed: {exc}") from exc
+        from .git_reconcile import guidance
+        hint = guidance(plan_run_root=plan_run_root, project_id=inp.project_id,
+                        task_group=inp.task_group, task_id=inp.task_id,
+                        work_category=inp.work_category)
+        raise PrepareError(
+            f"stage worktree provisioning failed: {exc}\n{hint}") from exc
 
     return StageSelection(
         stage=selected,
@@ -1382,6 +1456,7 @@ def _select_and_provision_implementation_stage(
         worktree_status=prov.status,
         worktree_note=prov.note,
         started_head_commit=prov.base_ref,
+        concurrent_stages=concurrent_stages,
     )
 
 
@@ -1400,6 +1475,7 @@ def _apply_implementation_stage(
     ctx["effective_stages"] = [sel.stage]
     csv = str(sel.stage)
     ctx["EFFECTIVE_STAGES"] = csv
+    ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in sel.concurrent_stages)
     ctx["STAGE_BATCH_DIRECTIVE"] = (
         f"- **Stage for this implementation run:** `{csv}`. "
         "Execute exactly this Stage Map stage — this is the authoritative scope. "
@@ -1436,6 +1512,20 @@ def _git_out(cwd, *args) -> str:
     return r.stdout.strip() if r.returncode == 0 else ""
 
 
+def _auto_reconcile_best_effort(inp: "PrepareInputs", plan_run_root: Path) -> None:
+    try:
+        from .git_reconcile import auto_reconcile
+        for it in auto_reconcile(
+                project_root=Path(inp.project_root), plan_run_root=plan_run_root,
+                project_id=inp.project_id, task_group=inp.task_group,
+                task_id=inp.task_id, work_category=inp.work_category):
+            print(f"git-reconcile: stage {it.stage} done commit "
+                  f"{it.recorded[:8]} -> {it.suggested_commit[:8]} "
+                  "(patch-equivalent)", file=sys.stdout)
+    except Exception as exc:  # 화해는 부가 기능 — 실패 시 기존 gate 가 판정
+        print(f"git-reconcile skipped: {exc}", file=sys.stderr)
+
+
 def _is_ancestor(cwd, commit, head) -> bool:
     if not commit or not head:
         return False
@@ -1447,10 +1537,22 @@ def _is_ancestor(cwd, commit, head) -> bool:
 
 
 def _is_dirty_excluding_okstra(cwd) -> bool:
-    out = _git_out(cwd, "status", "--short", "--", ".", ":(exclude).okstra")
+    excludes = [f":(exclude){p}" for p in okstra_clean_gate_excludes(Path(cwd))]
+    out = _git_out(cwd, "status", "--short", "--", ".", *excludes)
     return bool(out.strip())
 
 
+def _single_stage_final_verification_worktree(inp: "PrepareInputs") -> WorktreeProvision:
+    """Placeholder until the selected stage registry row is resolved."""
+    return WorktreeProvision(
+        status="deferred-final-verification",
+        note=(
+            "final-verification single-stage uses the selected implementation "
+            "stage worktree from the registry"
+        ),
+    )
+
+
 def _reserve_final_verification_target(
     inp: "PrepareInputs", ctx: dict, ctx_stage_map: list,
 ) -> None:
@@ -1464,6 +1566,7 @@ def _reserve_final_verification_target(
     # carry sidecars are the SSOT for stage completion — recover missing `done`
     # rows before the whole-task gate checks every stage.
     backfill_done_from_carry(plan_run_root)
+    _auto_reconcile_best_effort(inp, plan_run_root)
     done_rows = [r for r in read_consumers(plan_run_root)
                  if r.get("status") == "done"]
 
@@ -1472,6 +1575,7 @@ def _reserve_final_verification_target(
         row = _reg.get_stage_row(inp.project_id, inp.task_group, inp.task_id, n)
         wt_path = (row or {}).get("worktree_path", "")
         stage_base = (row or {}).get("base_ref", "")
+        stage_branch = (row or {}).get("branch", "")
         head = _git_out(wt_path, "rev-parse", "HEAD") if wt_path else ""
         target = _resolve_single_stage_target(
             requested_stage=inp.stage, done_rows=done_rows,
@@ -1480,13 +1584,20 @@ def _reserve_final_verification_target(
             stage_dirty=_is_dirty_excluding_okstra(wt_path) if wt_path else False,
         )
         ctx["EXECUTOR_WORKTREE_PATH"] = wt_path
+        ctx["EXECUTOR_WORKTREE_BRANCH"] = stage_branch
+        ctx["EXECUTOR_WORKTREE_BASE_REF"] = stage_base
+        ctx["EXECUTOR_WORKTREE_STATUS"] = "reused-stage"
+        ctx["EXECUTOR_WORKTREE_NOTE"] = (
+            f"final-verification uses implementation stage {n} worktree"
+        )
     else:
         wt_path = ctx["EXECUTOR_WORKTREE_PATH"]
         anchor = _reg.get_implementation_base(
             inp.project_id, inp.task_group, inp.task_id) or ""
         head = _git_out(wt_path, "rev-parse", "HEAD")
-        merged = {r["stage"]: _is_ancestor(wt_path, r.get("head_commit", ""), head)
-                  for r in done_rows}
+        from .consumers import latest_done_by_stage
+        merged = {s: _is_ancestor(wt_path, r.get("head_commit", ""), head)
+                  for s, r in latest_done_by_stage(done_rows).items()}
         target = _resolve_whole_task_target(
             stage_map=ctx_stage_map, done_rows=done_rows, anchor_base=anchor,
             task_worktree_path=wt_path, task_head=head,
@@ -1755,21 +1866,24 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     with worktree_provision_mutex(
         okstra_home(), inp.project_id, task_group_segment, task_id_segment,
     ):
-        try:
-            worktree = provision_task_worktree(
-                task_type=inp.task_type,
-                project_root=project_root,
-                project_id=inp.project_id,
-                task_group_segment=task_group_segment,
-                task_id_segment=task_id_segment,
-                work_category=inp.work_category,
-                base_ref=inp.base_ref,
-                require_base_ref=True,
-            )
-        except RuntimeError as exc:
-            raise PrepareError(
-                f"task worktree provisioning failed: {exc}"
-            ) from exc
+        if inp.task_type == "final-verification" and inp.stage and inp.stage != "auto":
+            worktree = _single_stage_final_verification_worktree(inp)
+        else:
+            try:
+                worktree = provision_task_worktree(
+                    task_type=inp.task_type,
+                    project_root=project_root,
+                    project_id=inp.project_id,
+                    task_group_segment=task_group_segment,
+                    task_id_segment=task_id_segment,
+                    work_category=inp.work_category,
+                    base_ref=inp.base_ref,
+                    require_base_ref=True,
+                )
+            except RuntimeError as exc:
+                raise PrepareError(
+                    f"task worktree provisioning failed: {exc}"
+                ) from exc
 
         # ---- implementation stage selection (path-independent) ----
         # Resolve + provision the stage BEFORE run-path compute so RUN_DIR
@@ -1784,6 +1898,10 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
                 task_key, worktree.status,
             )
             stage_arg = impl_stage_selection.stage
+            # Drop any stale waiver on this stage so the run actually verifies
+            # conformance (kept inside the per-task-key mutex so concurrent
+            # same-task runs don't race the manifest write).
+            _clear_stale_stage_waiver(inp, project_root, impl_stage_selection.stage)
         else:
             impl_stage_selection = None
             stage_arg = None
@@ -1959,10 +2077,19 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     if not inp.render_only:
         _provision_settings_symlink(inp)
 
+    concurrent_run: dict = {}
+    if impl_stage_selection is not None and impl_stage_selection.concurrent_stages:
+        concurrent_run = {
+            "detected": True,
+            "active_stages": impl_stage_selection.concurrent_stages,
+        }
     return PrepareOutputs(
         ctx=ctx,
         prompt_text=prompt_text,
-        extras={"profile_content": profile_content},
+        extras={
+            "profile_content": profile_content,
+            "concurrent_run": concurrent_run,
+        },
     )
 
 
@@ -2132,6 +2259,10 @@ def main(argv: list[str]) -> int:
     print(f"okstra instruction-set: {ctx['INSTRUCTION_SET_PATH']}")
     print(f"okstra reference expectations: {ctx['REFERENCE_EXPECTATIONS_FILE']}")
     print(f"okstra final report template: {ctx['FINAL_REPORT_TEMPLATE_PATH']}")
+    cr = out.extras.get("concurrent_run", {})
+    if cr.get("detected"):
+        stages_csv = ",".join(str(s) for s in cr["active_stages"])
+        print(f"okstra concurrent-run stages: {stages_csv}")
     if inputs.render_only:
         print()
         print(out.prompt_text, end="")