okstra 0.67.0 → 0.68.0

package/docs/superpowers/plans/2026-06-10-git-reconcile-stale-sha-recovery.md

@@ -0,0 +1,1408 @@
+# git-reconcile — stale SHA 회복 3단 방어 구현 계획
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** okstra 밖의 git 히스토리 변경(rebase / squash merge / 리뷰 amend / branch 삭제) 이후에도 `implementation` run 을 손편집 없이 이어가게 한다 — patch-id 증명 시 자동 화해, 내용 변경 시 확인 보정.
+
+**Architecture:** 신규 모듈 `scripts/okstra_ctl/git_reconcile.py` 가 감지(`classify_task`)·내용 동등성(`content_merged`)·보정(`apply_reconcile`)의 단일 reference point. prepare 경로(run.py)와 `okstra git-reconcile` subcommand(node 패스스루)와 okstra-run 스킬 picker 가 전부 이 모듈을 소비한다. 보정은 `consumers.jsonl` 에 done row 재-append(append-only 유지)이며, 선행 조건으로 done-row 읽기를 last-wins 로 통일한다.
+
+**Tech Stack:** Python 3.10+ (stdlib only, 실제 git subprocess), pytest (mock 금지 — 실 git repo fixture), Node ESM 패스스루, bash e2e.
+
+**스펙:** [`docs/superpowers/specs/2026-06-10-git-reconcile-stale-sha-recovery-design.md`](../specs/2026-06-10-git-reconcile-stale-sha-recovery-design.md)
+
+**중요 제약 (전 task 공통):**
+- `runtime/` 은 빌드 산출물 — 절대 직접 수정하지 않는다. 소스는 `scripts/`, `src/`, `bin/`, `skills/`.
+- 함수 효과 라인 50줄 초과 금지 — 초과 시 추출.
+- 커밋 메시지는 Conventional Commits, Claude trailer 금지.
+- 테스트는 `python3 -m pytest tests/<file>.py -v` (conftest.py 가 OKSTRA_HOME 을 격리).
+
+---
+
+### Task 1: `latest_done_by_stage` helper (last-wins 의 단일 구현)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/consumers.py` (171줄, `read_consumers` 아래에 추가)
+- Test: `tests/test_consumers_jsonl.py` (기존 파일에 테스트 추가)
+
+- [ ] **Step 1: 실패하는 테스트 작성** — `tests/test_consumers_jsonl.py` 끝에 추가:
+
+```python
+def test_latest_done_by_stage_last_wins(tmp_path):
+    from okstra_ctl.consumers import latest_done_by_stage
+    rows = [
+        {"impl_task_key": "k", "stage": 1, "status": "done", "head_commit": "aaa"},
+        {"impl_task_key": "k", "stage": 2, "status": "started", "head_commit": "x"},
+        {"impl_task_key": "k", "stage": 1, "status": "done", "head_commit": "bbb",
+         "reconciled": True},
+    ]
+    latest = latest_done_by_stage(rows)
+    assert latest[1]["head_commit"] == "bbb"
+    assert 2 not in latest  # started 는 제외
+
+
+def test_latest_done_by_stage_ignores_non_int_stage():
+    from okstra_ctl.consumers import latest_done_by_stage
+    assert latest_done_by_stage([{"stage": "x", "status": "done"}]) == {}
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_consumers_jsonl.py -v -k latest_done`
+Expected: FAIL — `ImportError: cannot import name 'latest_done_by_stage'`
+
+- [ ] **Step 3: 구현** — `consumers.py` 의 `read_consumers` 함수 바로 아래에 추가:
+
+```python
+def latest_done_by_stage(rows: List[Dict[str, Any]]) -> Dict[int, Dict[str, Any]]:
+    """stage → 마지막 done row. 보정(reconciled) row 가 같은 stage 에
+    재-append 되므로 done 읽기의 유일한 의미는 last-wins 다."""
+    out: Dict[int, Dict[str, Any]] = {}
+    for r in rows:
+        if r.get("status") == "done" and isinstance(r.get("stage"), int):
+            out[r["stage"]] = r
+    return out
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_consumers_jsonl.py -v`
+Expected: 전부 PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_ctl/consumers.py tests/test_consumers_jsonl.py
+git commit -m "feat(okstra-ctl): consumers done-row last-wins helper 추가"
+```
+
+---
+
+### Task 2: `append_consumer` 보정 재-append 지원
+
+`append_consumer` 는 `(impl_task_key, stage, status)` 동일 시 no-op([consumers.py:42-46](../../../scripts/okstra_ctl/consumers.py:42)) 이라 보정 row 가 막힌다. `force_reappend` 로 우회하되, 같은 `head_commit` 의 중복 보정은 여전히 no-op.
+
+**Files:**
+- Modify: `scripts/okstra_ctl/consumers.py:36-54` (`append_consumer`)
+- Test: `tests/test_consumers_jsonl.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+```python
+def test_append_consumer_force_reappend(tmp_path):
+    from okstra_ctl.consumers import append_consumer, read_consumers
+    append_consumer(tmp_path, impl_task_key="k", stage=1, status="done",
+                    head_commit="aaa")
+    # 기본: 동일 (key, stage, status) 는 no-op
+    append_consumer(tmp_path, impl_task_key="k", stage=1, status="done",
+                    head_commit="bbb")
+    assert len(read_consumers(tmp_path)) == 1
+    # force_reappend: 새 head_commit 이면 append
+    append_consumer(tmp_path, impl_task_key="k", stage=1, status="done",
+                    head_commit="bbb", force_reappend=True, reconciled=True)
+    rows = read_consumers(tmp_path)
+    assert len(rows) == 2 and rows[-1]["head_commit"] == "bbb"
+    # force_reappend 라도 동일 head_commit 중복은 no-op
+    append_consumer(tmp_path, impl_task_key="k", stage=1, status="done",
+                    head_commit="bbb", force_reappend=True)
+    assert len(read_consumers(tmp_path)) == 2
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_consumers_jsonl.py -v -k force_reappend`
+Expected: FAIL — `TypeError: append_consumer() got an unexpected keyword argument 'force_reappend'`
+
+- [ ] **Step 3: 구현** — `append_consumer` 시그니처와 idempotency 루프 수정:
+
+```python
+def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
+                    status: str, force_reappend: bool = False,
+                    **fields: Any) -> None:
+    if status not in ("started", "done"):
+        raise ValueError(f"status must be 'started' or 'done', got: {status!r}")
+    with consumers_mutex(plan_run_root):
+        existing = read_consumers(plan_run_root)
+        for row in existing:
+            if (row.get("impl_task_key") == impl_task_key
+                    and row.get("stage") == stage
+                    and row.get("status") == status):
+                if not force_reappend:
+                    return  # idempotent
+                if row.get("head_commit") == fields.get("head_commit"):
+                    return  # 동일 보정의 중복 재-append 방지
+        record: Dict[str, Any] = {
+            "impl_task_key": impl_task_key,
+            "stage": stage,
+            "status": status,
+            **fields,
+        }
+        with _path(plan_run_root).open("a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+```
+
+모듈 docstring(1-5행)의 identity 설명에 한 줄 추가: `force_reappend=True 인 보정 append 만 같은 tuple 을 다른 head_commit 으로 재기록할 수 있다.`
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_consumers_jsonl.py tests/test_consumers_carry_backfill.py -v`
+Expected: 전부 PASS (backfill 경로 회귀 없음)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_ctl/consumers.py tests/test_consumers_jsonl.py
+git commit -m "feat(okstra-ctl): append_consumer 에 보정 재-append(force_reappend) 지원"
+```
+
+---
+
+### Task 3: run.py done-row 읽기를 last-wins 로 통일
+
+첫 행 우선인 [run.py:489](../../../scripts/okstra_ctl/run.py:489)(다중 의존)·[run.py:527](../../../scripts/okstra_ctl/run.py:527)(단일 의존)과 마지막 행 우선인 [run.py:556](../../../scripts/okstra_ctl/run.py:556)·[run.py:1488](../../../scripts/okstra_ctl/run.py:1488)을 전부 Task 1 helper 로 수렴.
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py:482-536` (`_resolve_stage_base_commit`), `run.py:556` (`_resolve_whole_task_target`), `run.py:1488` (merged dict)
+- Test: `tests/test_okstra_run_stage_base.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성** — `tests/test_okstra_run_stage_base.py` 에 추가 (기존 테스트의 호출 형태를 따른다):
+
+```python
+def test_single_dep_uses_latest_done_row():
+    from okstra_ctl.run import _resolve_stage_base_commit
+    stage = {"stage_number": 2, "depends_on": [1]}
+    rows = [
+        {"stage": 1, "status": "done", "head_commit": "old111"},
+        {"stage": 1, "status": "done", "head_commit": "new222",
+         "reconciled": True},
+    ]
+    assert _resolve_stage_base_commit(stage, rows, anchor_base_commit="") == "new222"
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_run_stage_base.py -v -k latest_done_row`
+Expected: FAIL — 반환값이 `old111` (첫 행 우선)
+
+- [ ] **Step 3: 구현** — `_resolve_stage_base_commit` 본문에서 행 스캔 2곳을 교체:
+
+함수 도입부에 (docstring 직후):
+
+```python
+    from .consumers import latest_done_by_stage
+    latest = latest_done_by_stage(consumer_done_rows)
+```
+
+다중 의존의 `head = next((r.get("head_commit") for r in consumer_done_rows ...), None)` ([run.py:488-493](../../../scripts/okstra_ctl/run.py:488)) 을:
+
+```python
+            head = (latest.get(d) or {}).get("head_commit")
+```
+
+단일 의존의 `for row in consumer_done_rows:` 루프 ([run.py:527-531](../../../scripts/okstra_ctl/run.py:527)) 를:
+
+```python
+    pred = deps[0]
+    head = (latest.get(pred) or {}).get("head_commit") or ""
+    if head:
+        return head
+```
+
+`_resolve_whole_task_target` 의 `done_by_stage = {r["stage"]: r for r in done_rows}` ([run.py:556](../../../scripts/okstra_ctl/run.py:556)) 을:
+
+```python
+    from .consumers import latest_done_by_stage
+    done_by_stage = latest_done_by_stage(done_rows)
+```
+
+`_reserve_final_verification_target` 의 merged dict ([run.py:1488](../../../scripts/okstra_ctl/run.py:1488)) 를:
+
+```python
+        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()}
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_run_stage_base.py tests/test_e2e_impl_stage_artifact_isolation.py -v`
+Expected: 전부 PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_ctl/run.py tests/test_okstra_run_stage_base.py
+git commit -m "fix(okstra-ctl): done-row 읽기를 latest_done_by_stage 로 last-wins 통일"
+```
+
+---
+
+### Task 4: `git_reconcile.content_merged` — patch-id 내용 동등성 검사기
+
+**Files:**
+- Create: `scripts/okstra_ctl/git_reconcile.py`
+- Test: `tests/test_okstra_git_reconcile_content.py` (신규)
+
+- [ ] **Step 1: 실패하는 테스트 작성** — 실 git repo fixture (mock 금지):
+
+```python
+"""content_merged 의 ancestor / patch-equivalent / not-merged 판정 검증.
+실제 git 으로 rebase·squash·cherry-pick·amend 히스토리를 만들어 검사한다."""
+import subprocess
+from pathlib import Path
+
+import pytest
+
+
+def _git(repo: Path, *args: str) -> str:
+    r = subprocess.run(["git", "-C", str(repo), *args],
+                       capture_output=True, text=True, check=True)
+    return r.stdout.strip()
+
+
+@pytest.fixture()
+def repo(tmp_path: Path) -> Path:
+    r = tmp_path / "repo"
+    r.mkdir()
+    _git(r, "init", "-q", "-b", "main")
+    _git(r, "config", "user.email", "t@e")
+    _git(r, "config", "user.name", "t")
+    (r / "base.txt").write_text("base\n")
+    _git(r, "add", "."); _git(r, "commit", "-q", "-m", "base")
+    return r
+
+
+def _commit_file(repo: Path, name: str, content: str, msg: str) -> str:
+    (repo / name).write_text(content)
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", msg)
+    return _git(repo, "rev-parse", "HEAD")
+
+
+def test_ancestor_passes(repo):
+    from okstra_ctl.git_reconcile import content_merged
+    base = _git(repo, "rev-parse", "HEAD")
+    done = _commit_file(repo, "a.txt", "a\n", "stage work")
+    assert content_merged(repo, done, "main", base=base).status == "ancestor"
+
+
+def test_squash_merge_is_patch_equivalent(repo):
+    from okstra_ctl.git_reconcile import content_merged
+    base = _git(repo, "rev-parse", "HEAD")
+    _git(repo, "checkout", "-q", "-b", "stage")
+    _commit_file(repo, "a.txt", "a\n", "s1")
+    done = _commit_file(repo, "b.txt", "b\n", "s2")
+    _git(repo, "checkout", "-q", "main")
+    _git(repo, "merge", "--squash", "-q", "stage")
+    _git(repo, "commit", "-q", "-m", "squash stage")
+    squash_sha = _git(repo, "rev-parse", "HEAD")
+    _git(repo, "branch", "-q", "-D", "stage")
+    res = content_merged(repo, done, "main", base=base)
+    assert res.status == "patch-equivalent"
+    assert res.matched_commit == squash_sha
+
+
+def test_rebase_is_patch_equivalent(repo):
+    from okstra_ctl.git_reconcile import content_merged
+    base = _git(repo, "rev-parse", "HEAD")
+    _git(repo, "checkout", "-q", "-b", "stage")
+    _commit_file(repo, "a.txt", "a\n", "s1")
+    done = _commit_file(repo, "b.txt", "b\n", "s2")
+    _git(repo, "checkout", "-q", "main")
+    _commit_file(repo, "main.txt", "m\n", "main moves")
+    _git(repo, "rebase", "-q", "main", "stage")
+    rebased_tip = _git(repo, "rev-parse", "stage")
+    res = content_merged(repo, done, "stage", base=base)
+    assert res.status == "patch-equivalent"
+    assert res.matched_commit == rebased_tip
+
+
+def test_amended_content_is_not_merged(repo):
+    from okstra_ctl.git_reconcile import content_merged
+    base = _git(repo, "rev-parse", "HEAD")
+    _git(repo, "checkout", "-q", "-b", "stage")
+    done = _commit_file(repo, "a.txt", "a\n", "s1")
+    (repo / "a.txt").write_text("a-reviewed\n")  # 리뷰 반영 = 내용 변경
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "--amend", "-m", "s1'")
+    res = content_merged(repo, done, "stage", base=base)
+    assert res.status == "not-merged"
+
+
+def test_partial_cherry_pick_is_not_merged(repo):
+    """tip 만 cherry-pick 되고 선행 커밋이 빠지면 머지로 인정하지 않는다."""
+    from okstra_ctl.git_reconcile import content_merged
+    base = _git(repo, "rev-parse", "HEAD")
+    _git(repo, "checkout", "-q", "-b", "stage")
+    _commit_file(repo, "a.txt", "a\n", "s1")
+    done = _commit_file(repo, "b.txt", "b\n", "s2")
+    _git(repo, "checkout", "-q", "main")
+    _git(repo, "cherry-pick", "-q", done)  # s2 만
+    assert content_merged(repo, done, "main", base=base).status == "not-merged"
+
+
+def test_unresolvable_commit(repo):
+    from okstra_ctl.git_reconcile import content_merged
+    assert content_merged(repo, "0" * 40, "main").status == "unresolvable"
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_git_reconcile_content.py -v`
+Expected: FAIL — `ModuleNotFoundError: No module named 'okstra_ctl.git_reconcile'`
+
+- [ ] **Step 3: 구현** — `scripts/okstra_ctl/git_reconcile.py` 신규:
+
+```python
+"""Stale git SHA 감지·화해·보정 (3단 방어)의 단일 reference point.
+
+저장된 SHA(anchor / done.head_commit)가 okstra 밖의 히스토리 재작성으로
+stale 해졌을 때 — patch-id 로 내용 동일성이 증명되면 자동 화해(auto),
+내용이 바뀌었으면 사용자 확인 보정(confirm). prepare 경로(run.py)와
+`okstra git-reconcile` subcommand 와 okstra-run 스킬이 모두 이 모듈을
+소비한다. 설계:
+docs/superpowers/specs/2026-06-10-git-reconcile-stale-sha-recovery-design.md
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from .worktree import _resolve_commit_sha
+
+
+def _git(cwd: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", "-C", str(cwd), *args],
+                          capture_output=True, text=True)
+
+
+@dataclass
+class MatchResult:
+    status: str            # "ancestor" | "patch-equivalent" | "not-merged" | "unresolvable"
+    matched_commit: str = ""
+
+
+def _patch_ids_of_range(cwd: Path, base: str, head: str) -> List[Tuple[str, str]]:
+    """base..head 각 커밋의 (patch-id, sha). diff 없는 커밋은 제외된다."""
+    log = _git(cwd, "log", "-p", "--no-merges", f"{base}..{head}")
+    if log.returncode != 0:
+        return []
+    pid = subprocess.run(["git", "-C", str(cwd), "patch-id", "--stable"],
+                         input=log.stdout, capture_output=True, text=True)
+    out = []
+    for line in pid.stdout.splitlines():
+        parts = line.split()
+        if len(parts) == 2:
+            out.append((parts[0], parts[1]))
+    return out
+
+
+def _patch_id_of_diff(cwd: Path, base: str, head: str) -> str:
+    """base→head 전체를 한 diff 로 본 patch-id (squash 동등성용)."""
+    diff = _git(cwd, "diff", base, head)
+    if diff.returncode != 0 or not diff.stdout.strip():
+        return ""
+    pid = subprocess.run(["git", "-C", str(cwd), "patch-id", "--stable"],
+                         input=diff.stdout + "\n", capture_output=True, text=True)
+    parts = pid.stdout.split()
+    return parts[0] if parts else ""
+
+
+def content_merged(project_root: Path, commit: str, candidate: str,
+                   base: str = "") -> MatchResult:
+    """commit 의 내용이 candidate 히스토리에 포함되는가.
+
+    1) ancestor 면 그대로 통과. 2) patch-id fallback 두 granularity:
+    커밋 단위(rebase/cherry-pick — base..commit 의 *모든* 커밋이 매칭돼야 함)
+    + 범위 합산(squash — base..commit 전체 diff 가 한 커밋과 매칭).
+    증명 실패는 not-merged — 자동 진행 금지는 호출자 계약이다."""
+    resolved = _resolve_commit_sha(project_root, commit)
+    cand = _resolve_commit_sha(project_root, candidate)
+    if not resolved or not cand:
+        return MatchResult("unresolvable")
+    if _git(project_root, "merge-base", "--is-ancestor", resolved, cand).returncode == 0:
+        return MatchResult("ancestor", matched_commit=resolved)
+    mb = _git(project_root, "merge-base", resolved, cand).stdout.strip()
+    if not mb:
+        return MatchResult("not-merged")
+    range_base = _resolve_commit_sha(project_root, base) or mb
+    cand_ids: Dict[str, str] = dict(_patch_ids_of_range(project_root, mb, cand))
+    stage_ids = _patch_ids_of_range(project_root, range_base, resolved)
+    if stage_ids and all(pid in cand_ids for pid, _ in stage_ids):
+        # git log 는 최신 커밋부터 출력 → stage_ids[0] 이 tip. matched_commit
+        # 은 재기록 대상이므로 tip 의 매칭 SHA 여야 한다.
+        return MatchResult("patch-equivalent",
+                           matched_commit=cand_ids[stage_ids[0][0]])
+    whole = _patch_id_of_diff(project_root, range_base, resolved)
+    if whole and whole in cand_ids:
+        return MatchResult("patch-equivalent", matched_commit=cand_ids[whole])
+    return MatchResult("not-merged")
+```
+
+테스트 `test_rebase_is_patch_equivalent` 가 tip 매칭(`stage_ids[0]`)을 박제한다.
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_git_reconcile_content.py -v`
+Expected: 6 PASS. `test_rebase_is_patch_equivalent` 가 실패하면 위 주의사항(stage_ids[0])을 확인.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_ctl/git_reconcile.py tests/test_okstra_git_reconcile_content.py
+git commit -m "feat(okstra-ctl): patch-id 기반 content_merged 검사기 추가"
+```
+
+---
+
+### Task 5: `classify_task` — stale 분류기
+
+**Files:**
+- Modify: `scripts/okstra_ctl/git_reconcile.py`
+- Test: `tests/test_okstra_git_reconcile_classify.py` (신규)
+
+- [ ] **Step 1: 실패하는 테스트 작성** — registry/consumers 를 실제로 시딩 (conftest 가 OKSTRA_HOME 격리):
+
+```python
+"""classify_task 의 ok / auto / confirm 분류 검증 (실 git + 실 registry)."""
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from okstra_ctl import worktree_registry as reg
+from okstra_ctl.consumers import append_consumer
+
+
+def _git(repo: Path, *args: str) -> str:
+    r = subprocess.run(["git", "-C", str(repo), *args],
+                       capture_output=True, text=True, check=True)
+    return r.stdout.strip()
+
+
+@pytest.fixture()
+def env(tmp_path: Path):
+    repo = tmp_path / "repo"; repo.mkdir()
+    _git(repo, "init", "-q", "-b", "main")
+    _git(repo, "config", "user.email", "t@e")
+    _git(repo, "config", "user.name", "t")
+    (repo / "base.txt").write_text("base\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "base")
+    plan_root = tmp_path / "runs" / "implementation-planning"
+    plan_root.mkdir(parents=True)
+    reg.reserve(project_id="proj", task_group="grp", task_id="task",
+                worktree_path=str(repo), branch="fix-task", base_ref="main")
+    return repo, plan_root
+
+
+def _done(plan_root, stage, sha):
+    append_consumer(plan_root, impl_task_key="proj/grp/task", stage=stage,
+                    status="done", head_commit=sha)
+
+
+def test_intact_done_row_is_ok(env):
+    from okstra_ctl.git_reconcile import classify_task
+    repo, plan_root = env
+    _git(repo, "checkout", "-q", "-b", "fix-task-s1")
+    (repo / "a.txt").write_text("a\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "s1")
+    _done(plan_root, 1, _git(repo, "rev-parse", "HEAD"))
+    items = classify_task(project_root=repo, plan_run_root=plan_root,
+                          project_id="proj", task_group="grp", task_id="task",
+                          work_category="fix")
+    assert [i.classification for i in items if i.kind == "done"] == ["ok"]
+
+
+def test_rebased_branch_is_auto(env):
+    from okstra_ctl.git_reconcile import classify_task
+    repo, plan_root = env
+    _git(repo, "checkout", "-q", "-b", "fix-task-s1")
+    (repo / "a.txt").write_text("a\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "s1")
+    done = _git(repo, "rev-parse", "HEAD")
+    _done(plan_root, 1, done)
+    _git(repo, "checkout", "-q", "main")
+    (repo / "m.txt").write_text("m\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "main moves")
+    _git(repo, "rebase", "-q", "main", "fix-task-s1")
+    tip = _git(repo, "rev-parse", "fix-task-s1")
+    items = classify_task(project_root=repo, plan_run_root=plan_root,
+                          project_id="proj", task_group="grp", task_id="task",
+                          work_category="fix")
+    item = next(i for i in items if i.kind == "done" and i.stage == 1)
+    assert item.classification == "auto"
+    assert item.suggested_commit == tip
+
+
+def test_amended_branch_is_confirm(env):
+    from okstra_ctl.git_reconcile import classify_task
+    repo, plan_root = env
+    _git(repo, "checkout", "-q", "-b", "fix-task-s1")
+    (repo / "a.txt").write_text("a\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "s1")
+    _done(plan_root, 1, _git(repo, "rev-parse", "HEAD"))
+    (repo / "a.txt").write_text("a-reviewed\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "--amend", "-m", "s1'")
+    items = classify_task(project_root=repo, plan_run_root=plan_root,
+                          project_id="proj", task_group="grp", task_id="task",
+                          work_category="fix")
+    item = next(i for i in items if i.kind == "done" and i.stage == 1)
+    assert item.classification == "confirm"
+
+
+def test_unresolvable_anchor_is_confirm(env):
+    from okstra_ctl.git_reconcile import classify_task
+    repo, plan_root = env
+    reg.set_implementation_base("proj", "grp", "task", "0" * 40)
+    items = classify_task(project_root=repo, plan_run_root=plan_root,
+                          project_id="proj", task_group="grp", task_id="task",
+                          work_category="fix")
+    anchor = next(i for i in items if i.kind == "anchor")
+    assert anchor.classification == "confirm"
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_git_reconcile_classify.py -v`
+Expected: FAIL — `ImportError: cannot import name 'classify_task'`
+
+- [ ] **Step 3: 구현** — `git_reconcile.py` 에 추가:
+
+```python
+@dataclass
+class StaleItem:
+    kind: str                  # "anchor" | "done"
+    stage: Optional[int]
+    recorded: str
+    classification: str        # "ok" | "auto" | "confirm"
+    reason: str
+    suggested_commit: str = "" # auto 일 때 재기록 대상
+    impl_task_key: str = ""
+
+
+def _classify_done_row(project_root: Path, stage: int, row: dict,
+                       branch: str, stage_base: str) -> StaleItem:
+    recorded = row.get("head_commit", "")
+    item = StaleItem(kind="done", stage=stage, recorded=recorded,
+                     classification="ok", reason="",
+                     impl_task_key=row.get("impl_task_key", ""))
+    if not _resolve_commit_sha(project_root, recorded):
+        item.classification, item.reason = "confirm", "recorded SHA unresolvable"
+        return item
+    tip = _resolve_commit_sha(project_root, branch)
+    if not tip or tip == recorded:
+        return item  # branch 없음(히스토리 intact) 또는 일치
+    if _git(project_root, "merge-base", "--is-ancestor",
+            recorded, tip).returncode == 0:
+        return item  # 커밋이 단순히 더 쌓임 — stale 아님
+    match = content_merged(project_root, recorded, tip, base=stage_base)
+    if match.status in ("ancestor", "patch-equivalent"):
+        item.classification = "auto"
+        item.reason = f"branch {branch} rewritten, patch-equivalent"
+        item.suggested_commit = tip
+    else:
+        item.classification = "confirm"
+        item.reason = f"branch {branch} rewritten with content changes"
+    return item
+
+
+def classify_task(*, project_root: Path, plan_run_root: Path,
+                  project_id: str, task_group: str, task_id: str,
+                  work_category: str) -> List[StaleItem]:
+    """task 의 anchor + 최신 done row 들을 ok/auto/confirm 으로 분류한다.
+    다중 의존 gate(spec §3.2 표 5-6행)는 candidate 가 필요한 prepare 경로에서
+    content_merged 로 직접 평가된다 — 여기서 중복 평가하지 않는다."""
+    from . import worktree_registry as _reg
+    from .consumers import read_consumers, latest_done_by_stage
+    from .worktree import compute_branch_name
+
+    items: List[StaleItem] = []
+    anchor = _reg.get_implementation_base(project_id, task_group, task_id) or ""
+    if anchor:
+        ok = bool(_resolve_commit_sha(project_root, anchor))
+        items.append(StaleItem(
+            kind="anchor", stage=None, recorded=anchor,
+            classification="ok" if ok else "confirm",
+            reason="" if ok else "anchor SHA unresolvable",
+        ))
+    latest = latest_done_by_stage(read_consumers(plan_run_root))
+    for stage in sorted(latest):
+        row = latest[stage]
+        branch = compute_branch_name(
+            work_category=work_category, task_id_segment=task_id,
+            stage_number=stage,
+        )
+        srow = _reg.get_stage_row(project_id, task_group, task_id, stage) or {}
+        items.append(_classify_done_row(
+            project_root, stage, row, branch, srow.get("base_ref", "")))
+    return items
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_git_reconcile_classify.py -v`
+Expected: 4 PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_ctl/git_reconcile.py tests/test_okstra_git_reconcile_classify.py
+git commit -m "feat(okstra-ctl): stale SHA 분류기 classify_task 추가"
+```
+
+---
+
+### Task 6: `apply_reconcile` + `reset_implementation_base` + enforcement 가드
+
+**Files:**
+- Modify: `scripts/okstra_ctl/git_reconcile.py`, `scripts/okstra_ctl/worktree_registry.py:218` 아래
+- Test: `tests/test_okstra_git_reconcile_apply.py` (신규), `tests/test_okstra_worktree_registry.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성** — `tests/test_okstra_git_reconcile_apply.py` (Task 5 의 `env`/`_git`/`_done` fixture 를 복사해 동일하게 사용):
+
+```python
+def test_auto_items_are_recorded(env):
+    """rebase 된 stage(auto)는 --use-ref 없이 보정되고 reconciled 필드가 남는다."""
+    from okstra_ctl.git_reconcile import apply_reconcile
+    from okstra_ctl.consumers import read_consumers, latest_done_by_stage
+    repo, plan_root = env
+    # Task 5 test_rebased_branch_is_auto 와 동일한 rebase 히스토리 구성
+    _git(repo, "checkout", "-q", "-b", "fix-task-s1")
+    (repo / "a.txt").write_text("a\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "s1")
+    _done(plan_root, 1, _git(repo, "rev-parse", "HEAD"))
+    _git(repo, "checkout", "-q", "main")
+    (repo / "m.txt").write_text("m\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "main moves")
+    _git(repo, "rebase", "-q", "main", "fix-task-s1")
+    tip = _git(repo, "rev-parse", "fix-task-s1")
+
+    result = apply_reconcile(project_root=repo, plan_run_root=plan_root,
+                             project_id="proj", task_group="grp",
+                             task_id="task", work_category="fix")
+    assert result["applied"] and not result["remaining_confirm"]
+    row = latest_done_by_stage(read_consumers(plan_root))[1]
+    assert row["head_commit"] == tip
+    assert row["reconciled"] is True
+    assert row["reconcile_reason"] == "auto-patch-id"
+    assert row["replaced_commit"]
+
+
+def test_confirm_item_never_auto_applied(env):
+    """enforcement: confirm(내용 변경) 항목은 use_ref 없이 절대 보정되지 않는다."""
+    from okstra_ctl.git_reconcile import apply_reconcile
+    from okstra_ctl.consumers import read_consumers
+    repo, plan_root = env
+    _git(repo, "checkout", "-q", "-b", "fix-task-s1")
+    (repo / "a.txt").write_text("a\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "s1")
+    _done(plan_root, 1, _git(repo, "rev-parse", "HEAD"))
+    (repo / "a.txt").write_text("a-reviewed\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "--amend", "-m", "s1'")
+
+    result = apply_reconcile(project_root=repo, plan_run_root=plan_root,
+                             project_id="proj", task_group="grp",
+                             task_id="task", work_category="fix")
+    assert not result["applied"]
+    assert [i.stage for i in result["remaining_confirm"]] == [1]
+    assert len(read_consumers(plan_root)) == 1  # 원본 row 만
+
+
+def test_use_ref_resolves_and_records(env):
+    from okstra_ctl.git_reconcile import apply_reconcile
+    from okstra_ctl.consumers import read_consumers
+    repo, plan_root = env
+    _git(repo, "checkout", "-q", "-b", "fix-task-s1")
+    (repo / "a.txt").write_text("a\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "s1")
+    _done(plan_root, 1, "0" * 40)  # GC 로 소멸한 SHA 가정
+    result = apply_reconcile(project_root=repo, plan_run_root=plan_root,
+                             project_id="proj", task_group="grp",
+                             task_id="task", work_category="fix",
+                             stage=1, use_ref="fix-task-s1")
+    assert result["applied"]
+    row = read_consumers(plan_root)[-1]
+    assert row["head_commit"] == _git(repo, "rev-parse", "fix-task-s1")
+    assert row["reconcile_reason"] == "user-ref"
+
+
+def test_use_ref_requires_stage_and_resolvable(env):
+    from okstra_ctl.git_reconcile import apply_reconcile, ReconcileError
+    repo, plan_root = env
+    import pytest as _pt
+    with _pt.raises(ReconcileError):
+        apply_reconcile(project_root=repo, plan_run_root=plan_root,
+                        project_id="proj", task_group="grp", task_id="task",
+                        work_category="fix", use_ref="fix-task-s1")  # stage 없음
+    with _pt.raises(ReconcileError):
+        apply_reconcile(project_root=repo, plan_run_root=plan_root,
+                        project_id="proj", task_group="grp", task_id="task",
+                        work_category="fix", stage=1, use_ref="no-such-ref")
+
+
+def test_reset_anchor(env):
+    from okstra_ctl.git_reconcile import apply_reconcile
+    from okstra_ctl import worktree_registry as reg
+    repo, plan_root = env
+    reg.set_implementation_base("proj", "grp", "task", "0" * 40)
+    apply_reconcile(project_root=repo, plan_run_root=plan_root,
+                    project_id="proj", task_group="grp", task_id="task",
+                    work_category="fix", reset_anchor="main")
+    assert reg.get_implementation_base("proj", "grp", "task") == \
+        _git(repo, "rev-parse", "main")
+```
+
+`tests/test_okstra_worktree_registry.py` 에 추가:
+
+```python
+def test_reset_implementation_base_overrides():
+    from okstra_ctl import worktree_registry as reg
+    reg.reserve(project_id="p", task_group="g", task_id="t",
+                worktree_path="/wt/p/g/t", branch="feat-t", base_ref="main")
+    reg.set_implementation_base("p", "g", "t", "aaa")
+    assert reg.set_implementation_base("p", "g", "t", "bbb") == "aaa"  # 기존 불변
+    assert reg.reset_implementation_base("p", "g", "t", "bbb") == "bbb"
+    assert reg.get_implementation_base("p", "g", "t") == "bbb"
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_git_reconcile_apply.py tests/test_okstra_worktree_registry.py -v`
+Expected: FAIL — `ImportError` (apply_reconcile / reset_implementation_base 부재)
+
+- [ ] **Step 3: 구현** — `worktree_registry.py` 의 `set_implementation_base` 아래에:
+
+```python
+def reset_implementation_base(
+    project_id: str, task_group: str, task_id: str, commit: str,
+) -> str:
+    """anchor 를 의식적으로 재고정한다. 유일한 호출자는 git-reconcile 의
+    `--reset-anchor` — prepare 경로는 절대 anchor 를 움직이지 않는다."""
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if row is None:
+            raise RuntimeError(
+                f"no task-key entry to reset implementation base: {key}"
+            )
+        row["implementation_base_commit"] = commit
+        _save(data)
+        return commit
+```
+
+`git_reconcile.py` 에 추가:
+
+```python
+class ReconcileError(Exception):
+    pass
+
+
+def _record_reconciled(plan_run_root: Path, *, impl_task_key: str, stage: int,
+                       new_commit: str, replaced: str, reason: str) -> None:
+    from .consumers import append_consumer
+    append_consumer(
+        plan_run_root, impl_task_key=impl_task_key, stage=stage,
+        status="done", force_reappend=True, head_commit=new_commit,
+        reconciled=True, reconcile_reason=reason, replaced_commit=replaced,
+    )
+
+
+def _apply_user_ref(project_root, plan_run_root, latest, stage, use_ref) -> dict:
+    if stage is None:
+        raise ReconcileError("--use-ref requires --stage")
+    sha = _resolve_commit_sha(project_root, use_ref)
+    if not sha:
+        raise ReconcileError(f"could not resolve ref `{use_ref}`")
+    row = latest.get(stage)
+    if not row:
+        raise ReconcileError(f"stage {stage} has no done row to reconcile")
+    _record_reconciled(plan_run_root, impl_task_key=row.get("impl_task_key", ""),
+                       stage=stage, new_commit=sha,
+                       replaced=row.get("head_commit", ""), reason="user-ref")
+    return {"stage": stage, "new_commit": sha}
+
+
+def apply_reconcile(*, project_root: Path, plan_run_root: Path,
+                    project_id: str, task_group: str, task_id: str,
+                    work_category: str, stage: Optional[int] = None,
+                    use_ref: str = "", reset_anchor: str = "") -> dict:
+    """auto 항목 일괄 보정 + (옵션) confirm 항목 1건 보정 + (옵션) anchor 재고정.
+
+    enforcement(spec §3.6): confirm 항목은 `use_ref` 가 명시된 그 stage 만
+    보정된다 — 어떤 경로로도 무확인 자동 보정되지 않는다."""
+    from . import worktree_registry as _reg
+    from .consumers import read_consumers, latest_done_by_stage
+
+    applied: List[dict] = []
+    if reset_anchor:
+        sha = _resolve_commit_sha(project_root, reset_anchor)
+        if not sha:
+            raise ReconcileError(f"could not resolve ref `{reset_anchor}`")
+        _reg.reset_implementation_base(project_id, task_group, task_id, sha)
+        applied.append({"anchor": sha})
+    if use_ref:
+        latest = latest_done_by_stage(read_consumers(plan_run_root))
+        applied.append(_apply_user_ref(
+            project_root, plan_run_root, latest, stage, use_ref))
+    items = classify_task(
+        project_root=project_root, plan_run_root=plan_run_root,
+        project_id=project_id, task_group=task_group, task_id=task_id,
+        work_category=work_category)
+    for item in items:
+        if item.classification != "auto":
+            continue
+        _record_reconciled(plan_run_root, impl_task_key=item.impl_task_key,
+                           stage=item.stage, new_commit=item.suggested_commit,
+                           replaced=item.recorded, reason="auto-patch-id")
+        applied.append({"stage": item.stage, "new_commit": item.suggested_commit})
+    remaining = [i for i in items if i.classification == "confirm"
+                 and not (use_ref and i.stage == stage)]
+    return {"applied": applied, "remaining_confirm": remaining}
+```
+
+주의: `use_ref` 보정을 classify **이전에** 수행하므로, 같은 stage 가 confirm 으로 재분류되지 않도록 classify 는 use_ref 보정 *후* 의 consumers 를 읽는다 (위 코드 순서가 이미 그렇게 되어 있다 — classify 가 `read_consumers` 를 다시 읽음).
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_git_reconcile_apply.py tests/test_okstra_worktree_registry.py -v`
+Expected: 전부 PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_ctl/git_reconcile.py scripts/okstra_ctl/worktree_registry.py \
+  tests/test_okstra_git_reconcile_apply.py tests/test_okstra_worktree_registry.py
+git commit -m "feat(okstra-ctl): apply_reconcile 보정 + anchor 재고정 + confirm enforcement"
+```
+
+---
+
+### Task 7: CLI — `python3 -m okstra_ctl.git_reconcile` + `okstra git-reconcile` (node)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/git_reconcile.py` (main 추가)
+- Create: `src/git-reconcile.mjs`
+- Modify: `bin/okstra` (COMMANDS map + USAGE)
+- Test: `tests/test_okstra_git_reconcile_cli.py` (신규)
+
+- [ ] **Step 1: 실패하는 테스트 작성** — main() 을 subprocess 없이 직접 호출:
+
+```python
+def test_main_check_json_exit_codes(env, capsys):
+    """stale 없음 → 0, confirm 잔존 → 2."""
+    import json
+    from okstra_ctl.git_reconcile import main
+    repo, plan_root = env
+    args = ["--project-root", str(repo), "--plan-run-root", str(plan_root),
+            "--project-id", "proj", "--task-group", "grp",
+            "--task-id", "task", "--work-category", "fix", "--json"]
+    assert main(args) == 0  # done row 없음 = stale 없음
+    _git(repo, "checkout", "-q", "-b", "fix-task-s1")
+    (repo / "a.txt").write_text("a\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "s1")
+    _done(plan_root, 1, _git(repo, "rev-parse", "HEAD"))
+    (repo / "a.txt").write_text("a-reviewed\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "--amend", "-m", "s1'")
+    capsys.readouterr()
+    assert main(args) == 2
+    report = json.loads(capsys.readouterr().out)
+    assert report["items"][0]["classification"] == "confirm"
+
+
+def test_main_apply_use_ref(env, capsys):
+    from okstra_ctl.git_reconcile import main
+    from okstra_ctl.consumers import read_consumers
+    repo, plan_root = env
+    _git(repo, "checkout", "-q", "-b", "fix-task-s1")
+    (repo / "a.txt").write_text("a\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "s1")
+    _done(plan_root, 1, "0" * 40)
+    code = main(["--project-root", str(repo), "--plan-run-root", str(plan_root),
+                 "--project-id", "proj", "--task-group", "grp",
+                 "--task-id", "task", "--work-category", "fix",
+                 "--apply", "--stage", "1", "--use-ref", "fix-task-s1"])
+    assert code == 0
+    assert read_consumers(plan_root)[-1]["reconcile_reason"] == "user-ref"
+```
+
+(fixture `env`/`_git`/`_done` 은 Task 5 테스트 파일과 동일 — 파일 상단에 복사.)
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_git_reconcile_cli.py -v`
+Expected: FAIL — `ImportError: cannot import name 'main'`
+
+- [ ] **Step 3: 구현** — `git_reconcile.py` 끝에 ([migrate.py:378](../../../scripts/okstra_ctl/migrate.py:378) 패턴):
+
+```python
+def _items_as_json(items: List[StaleItem]) -> list:
+    return [{"kind": i.kind, "stage": i.stage, "recorded": i.recorded,
+             "classification": i.classification, "reason": i.reason,
+             "suggested_commit": i.suggested_commit} for i in items]
+
+
+def main(argv: Optional[list] = None) -> int:
+    import argparse
+    import json as _json
+
+    p = argparse.ArgumentParser(prog="okstra git-reconcile")
+    p.add_argument("--project-root", default=".")
+    p.add_argument("--plan-run-root", required=True,
+                   help="consumers.jsonl 이 있는 runs/implementation-planning/ 경로")
+    p.add_argument("--project-id", required=True)
+    p.add_argument("--task-group", required=True)
+    p.add_argument("--task-id", required=True)
+    p.add_argument("--work-category", required=True)
+    p.add_argument("--apply", action="store_true",
+                   help="auto 항목 일괄 보정 (+ --stage/--use-ref, --reset-anchor)")
+    p.add_argument("--stage", type=int)
+    p.add_argument("--use-ref", default="")
+    p.add_argument("--reset-anchor", default="")
+    p.add_argument("--json", action="store_true")
+    a = p.parse_args(argv)
+
+    kw = dict(project_root=Path(a.project_root).resolve(),
+              plan_run_root=Path(a.plan_run_root).resolve(),
+              project_id=a.project_id, task_group=a.task_group,
+              task_id=a.task_id, work_category=a.work_category)
+    try:
+        if a.apply:
+            result = apply_reconcile(**kw, stage=a.stage, use_ref=a.use_ref,
+                                     reset_anchor=a.reset_anchor)
+            out = {"applied": result["applied"],
+                   "remaining_confirm": _items_as_json(result["remaining_confirm"])}
+            print(_json.dumps(out, ensure_ascii=False,
+                              indent=None if a.json else 2))
+            return 2 if result["remaining_confirm"] else 0
+        items = classify_task(**kw)
+        stale = [i for i in items if i.classification != "ok"]
+        print(_json.dumps({"items": _items_as_json(stale)}, ensure_ascii=False,
+                          indent=None if a.json else 2))
+        return 2 if any(i.classification == "confirm" for i in stale) else 0
+    except ReconcileError as exc:
+        print(_json.dumps({"error": str(exc)}, ensure_ascii=False))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+```
+
+`src/git-reconcile.mjs` 신규 ([src/migrate.mjs](../../../src/migrate.mjs) 패턴 그대로):
+
+```javascript
+import { runPythonModule } from "./_python-helper.mjs";
+
+const USAGE = `okstra git-reconcile — okstra 밖 git 히스토리 변경 후 기록 화해
+
+A thin shim over \`python3 -m okstra_ctl.git_reconcile\`. 기본은 검사
+(--check 상당): stale 항목을 JSON 으로 출력하고, confirm 항목이 남으면
+exit 2. patch-id 로 내용 동일성이 증명되는 항목(auto)은 --apply 로 일괄
+보정되고, 내용이 바뀐 항목(confirm)은 --stage/--use-ref 로만 보정된다.
+
+Usage:
+  okstra git-reconcile --plan-run-root <dir> --project-id <id> \\
+    --task-group <g> --task-id <t> --work-category <c> \\
+    [--apply] [--stage <N> --use-ref <ref>] [--reset-anchor <ref>] [--json]
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.git_reconcile",
+    args,
+  });
+  return code ?? 1;
+}
+```
+
+`bin/okstra` 의 COMMANDS map 에 (`migrate` 항목 다음 줄):
+
+```javascript
+  [
+    "git-reconcile",
+    () => import("../src/git-reconcile.mjs").then((m) => m.run),
+  ],
+```
+
+USAGE 문자열의 `migrate` 라인 아래에:
+
+```
+  git-reconcile          Reconcile stale stage SHAs after external git history changes
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_git_reconcile_cli.py -v && node bin/okstra git-reconcile --help`
+Expected: pytest PASS, node 가 USAGE 출력 후 exit 0
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_ctl/git_reconcile.py src/git-reconcile.mjs bin/okstra \
+  tests/test_okstra_git_reconcile_cli.py
+git commit -m "feat(cli): okstra git-reconcile subcommand 추가"
+```
+
+---
+
+### Task 8: prepare 경로 통합 — 자동 화해 + gate fallback + 안내 에러
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py` — `_resolve_stage_base_commit`(465), `_select_and_provision_implementation_stage`(1295), `_reserve_final_verification_target`(1454)
+- Modify: `scripts/okstra_ctl/git_reconcile.py` (`auto_reconcile`, `guidance` 추가)
+- Test: `tests/test_okstra_run_stage_base.py`, `tests/test_okstra_git_reconcile_prepare.py` (신규)
+
+- [ ] **Step 1: `auto_reconcile` + `guidance` 를 git_reconcile.py 에 추가 (실패 테스트 먼저)** — `tests/test_okstra_git_reconcile_prepare.py` (fixture 는 Task 5 와 동일):
+
+```python
+def test_auto_reconcile_records_only_auto(env):
+    """prepare 진입 시 자동 화해: auto 만 기록, confirm 은 그대로."""
+    from okstra_ctl.git_reconcile import auto_reconcile
+    from okstra_ctl.consumers import read_consumers, latest_done_by_stage
+    repo, plan_root = env
+    _git(repo, "checkout", "-q", "-b", "fix-task-s1")
+    (repo / "a.txt").write_text("a\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "s1")
+    _done(plan_root, 1, _git(repo, "rev-parse", "HEAD"))
+    _git(repo, "checkout", "-q", "main")
+    (repo / "m.txt").write_text("m\n")
+    _git(repo, "add", "."); _git(repo, "commit", "-q", "-m", "main moves")
+    _git(repo, "rebase", "-q", "main", "fix-task-s1")
+    applied = auto_reconcile(project_root=repo, plan_run_root=plan_root,
+                             project_id="proj", task_group="grp",
+                             task_id="task", work_category="fix")
+    assert len(applied) == 1
+    assert latest_done_by_stage(read_consumers(plan_root))[1]["head_commit"] \
+        == _git(repo, "rev-parse", "fix-task-s1")
+
+
+def test_guidance_mentions_command(env):
+    from okstra_ctl.git_reconcile import guidance
+    repo, plan_root = env
+    text = guidance(plan_run_root=plan_root, project_id="proj",
+                    task_group="grp", task_id="task", work_category="fix")
+    assert "okstra git-reconcile" in text and "--use-ref" in text
+```
+
+- [ ] **Step 2: 실패 확인 후 구현** — `git_reconcile.py` 에:
+
+```python
+def auto_reconcile(*, project_root: Path, plan_run_root: Path,
+                   project_id: str, task_group: str, task_id: str,
+                   work_category: str) -> List[StaleItem]:
+    """classify 의 auto 항목만 보정 row 로 재기록한다 — patch-id 증명이
+    있으므로 확인 불필요(설계 §2 결정). confirm 은 건드리지 않는다."""
+    applied = []
+    items = classify_task(
+        project_root=project_root, plan_run_root=plan_run_root,
+        project_id=project_id, task_group=task_group, task_id=task_id,
+        work_category=work_category)
+    for item in items:
+        if item.classification != "auto" or item.kind != "done":
+            continue
+        _record_reconciled(plan_run_root, impl_task_key=item.impl_task_key,
+                           stage=item.stage, new_commit=item.suggested_commit,
+                           replaced=item.recorded, reason="auto-patch-id")
+        applied.append(item)
+    return applied
+
+
+def guidance(*, plan_run_root: Path, project_id: str, task_group: str,
+             task_id: str, work_category: str) -> str:
+    """PrepareError 에 첨부하는 회복 안내 (명령 예시 포함)."""
+    base = (f"okstra git-reconcile --plan-run-root {plan_run_root} "
+            f"--project-id {project_id} --task-group {task_group} "
+            f"--task-id {task_id} --work-category {work_category}")
+    return ("Recorded stage SHAs no longer match the git history "
+            "(external rebase/squash/amend?). Inspect and reconcile:\n"
+            f"  {base} --json\n"
+            f"  {base} --apply --stage <N> --use-ref <branch|sha>")
+```
+
+Run: `python3 -m pytest tests/test_okstra_git_reconcile_prepare.py -v` → PASS
+
+- [ ] **Step 3: run.py 통합 (실패 테스트 먼저)** — `tests/test_okstra_run_stage_base.py` 에 추가:
+
+```python
+def test_multi_dep_accepts_patch_equivalent(tmp_path):
+    """다중 의존 gate: ancestor 가 아니어도 squash 로 내용이 머지됐으면 통과."""
+    import subprocess
+    from okstra_ctl.run import _resolve_stage_base_commit
+
+    def g(*args):
+        return subprocess.run(["git", "-C", str(repo), *args],
+                              capture_output=True, text=True,
+                              check=True).stdout.strip()
+    repo = tmp_path / "repo"; repo.mkdir()
+    g("init", "-q", "-b", "main")
+    g("config", "user.email", "t@e"); g("config", "user.name", "t")
+    (repo / "base.txt").write_text("base\n")
+    g("add", "."); g("commit", "-q", "-m", "base")
+    anchor = g("rev-parse", "HEAD")
+    g("checkout", "-q", "-b", "s1")
+    (repo / "a.txt").write_text("a\n")
+    g("add", "."); g("commit", "-q", "-m", "s1")
+    done1 = g("rev-parse", "HEAD")
+    g("checkout", "-q", "main")
+    g("merge", "--squash", "-q", "s1"); g("commit", "-q", "-m", "squash s1")
+    candidate = g("rev-parse", "HEAD")
+
+    plan_root = tmp_path / "plan"; plan_root.mkdir()
+    stage = {"stage_number": 3, "depends_on": [1, 2]}
+    rows = [
+        {"impl_task_key": "k", "stage": 1, "status": "done", "head_commit": done1},
+        {"impl_task_key": "k", "stage": 2, "status": "done", "head_commit": candidate},
+    ]
+    base = _resolve_stage_base_commit(
+        stage, rows, anchor_base_commit=anchor, candidate_base=candidate,
+        project_root=repo, plan_run_root=plan_root)
+    assert base == candidate
+```
+
+Run → Expected: FAIL — `PrepareError ... not merged` (또는 unexpected kwarg `plan_run_root`)
+
+- [ ] **Step 4: run.py 구현**
+
+(a) `_resolve_stage_base_commit` 다중 의존 검사 블록 ([run.py:506-515](../../../scripts/okstra_ctl/run.py:506)) 을 추출 함수로 옮기고 content fallback 추가. 시그니처에 `plan_run_root=None` 추가 (기본값으로 기존 테스트 호환):
+
+```python
+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
+    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:
+                from .git_reconcile import _record_reconciled
+                _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."
+        )
+```
+
+`_resolve_stage_base_commit` 의 해당 for 루프를 `_check_multi_dep_merged(project_root, plan_run_root, latest, pred_commits, candidate_base, n)` 호출로 교체하고, 시그니처를 `def _resolve_stage_base_commit(stage, consumer_done_rows, anchor_base_commit, candidate_base="", project_root=None, plan_run_root=None)` 로 확장.
+
+(b) `_select_and_provision_implementation_stage` — [run.py:1317](../../../scripts/okstra_ctl/run.py:1317) `backfill_done_from_carry(plan_run_root)` 직후에 `_auto_reconcile_best_effort(inp, plan_run_root)` 호출(helper 정의는 아래). 같은 함수의 `_resolve_stage_base_commit(...)` 호출 ([run.py:1360](../../../scripts/okstra_ctl/run.py:1360)) 에 `plan_run_root=plan_run_root` 인자 추가. **주의:** auto_reconcile 이 row 를 추가했을 수 있으므로 `consumed = read_consumers(plan_run_root)` ([run.py:1318](../../../scripts/okstra_ctl/run.py:1318)) 는 반드시 화해 **이후에** 실행되도록 호출 순서를 유지한다.
+
+(c) 같은 함수에서 단일 의존 base 가 unresolvable 인 채 provision 으로 떨어지는 경우와 다중 의존 not-merged 의 `PrepareError` 에 회복 안내를 덧붙인다 — provision 예외 래핑 ([run.py:1374-1375](../../../scripts/okstra_ctl/run.py:1374)) 을:
+
+```python
+    except RuntimeError as 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
+```
+
+(d) `_reserve_final_verification_target` — [run.py:1466](../../../scripts/okstra_ctl/run.py:1466) `backfill_done_from_carry` 직후에 동일하게 `_auto_reconcile_best_effort(inp, plan_run_root)` 호출. whole-task merged 검사 ([run.py:1488](../../../scripts/okstra_ctl/run.py:1488), Task 3 에서 helper 화) 는 auto_reconcile 이 선행되므로 추가 fallback 불필요 — 화해된 row 의 새 SHA 가 ancestor 검사를 통과한다.
+
+(b)(d) 가 공유하는 helper — `run.py` 의 `_git_out` 부근에 정의:
+
+```python
+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)
+```
+
+- [ ] **Step 5: 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_run_stage_base.py tests/test_okstra_git_reconcile_prepare.py tests/test_e2e_impl_stage_artifact_isolation.py -v`
+Expected: 전부 PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add scripts/okstra_ctl/run.py scripts/okstra_ctl/git_reconcile.py \
+  tests/test_okstra_run_stage_base.py tests/test_okstra_git_reconcile_prepare.py
+git commit -m "feat(okstra-ctl): prepare 경로에 stale SHA 자동 화해 + gate patch-id fallback"
+```
+
+---
+
+### Task 9: okstra-run 스킬 picker 배선
+
+**Files:**
+- Modify: `skills/okstra-run/SKILL.md` — qa-waiver 문단 ([SKILL.md:189-197](../../../skills/okstra-run/SKILL.md:189) 부근, `--qa-waiver` 설명 블록) **다음**에 새 소절 삽입
+
+- [ ] **Step 1: 소절 삽입** — 아래 마크다운을 그대로 추가:
+
+```markdown
+### Stale git SHA recovery (git-reconcile gate)
+
+`render-bundle` 이 `Recorded stage SHAs no longer match the git history` 를 포함한
+`PrepareError` 로 실패하면, okstra 밖에서 git 히스토리가 바뀐 것이다(rebase /
+squash / 리뷰 반영 amend / branch 삭제). 절대 registry/consumers 를 손으로
+고치지 말고 다음 순서로 회복한다:
+
+1. 에러 메시지에 인쇄된 `okstra git-reconcile … --json` 명령을 그대로 실행해
+   stale 리포트를 얻는다. (patch-id 로 내용 동일성이 증명되는 항목은 prepare
+   가 이미 자동 화해했으므로, 여기 남는 것은 confirm 항목뿐이다.)
+2. confirm 항목별로 사용자에게 3-옵션 picker 를 제시한다:
+   - **`stage-<N>` branch 의 현재 tip 으로 재기록 (추천)** — 리뷰 반영 등
+     의도된 수정이 그 branch 에 있을 때.
+   - **다른 ref 직접 입력** — 사용자가 commit/branch/tag 를 직접 지정.
+   - **중단** — 회복하지 않고 run 을 멈춘다.
+3. 선택된 ref 로 `okstra git-reconcile … --apply --stage <N> --use-ref <ref>`
+   를 실행한 뒤, 실패했던 `render-bundle` 을 동일 인자로 재시도한다.
+
+anchor(`implementation_base_commit`)가 unresolvable 로 보고되면 같은 명령의
+`--reset-anchor <ref>` 를 사용자 확인 후 실행한다. picker 없이 confirm 항목을
+보정하는 것은 금지 — 런타임도 `--use-ref` 없는 confirm 보정을 거부한다.
+```
+
+- [ ] **Step 2: 검증** — 스킬 빌드 동기화 확인:
+
+Run: `npm run build && grep -n "git-reconcile" runtime/skills/okstra-run/SKILL.md | head -3`
+Expected: build 성공, runtime 에 소절 반영
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add skills/okstra-run/SKILL.md
+git commit -m "feat(skills/okstra-run): stale SHA 회복 picker 단계 추가"
+```
+
+---
+
+### Task 10: e2e 시나리오 + 문서 + 최종 검증
+
+**Files:**
+- Create: `tests-e2e/scenario-13-git-reconcile-squash.sh`
+- Modify: `docs/superpowers/specs/2026-06-10-git-reconcile-stale-sha-recovery-design.md` (okstra.sh 패스스루 제거 — 검증 결과 [scripts/okstra.sh](../../../scripts/okstra.sh) 에는 subcommand dispatch 가 없어 ops 명령은 node CLI 전용)
+- Modify: `CHANGES.md` (최상단에 항목 추가)
+
+- [ ] **Step 1: e2e 시나리오** — 기존 시나리오 패턴(mktemp OKSTRA_HOME + trap 정리). 핵심 흐름: 실 git repo 에서 stage1 done 기록 → squash merge + branch 삭제 → `python3 -m okstra_ctl.git_reconcile` 검사가 auto 화해 가능을 보고하는지 확인:
+
+```bash
+#!/usr/bin/env bash
+# scenario-13: squash merge + branch 삭제 후 git-reconcile 이 patch-equivalent
+# 를 자동 화해하는지 검증.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+WORK="$(mktemp -d)"
+export OKSTRA_HOME="$WORK/okstra-home"
+mkdir -p "$OKSTRA_HOME"
+trap 'rm -rf "$WORK"' EXIT
+export PYTHONPATH="$ROOT/scripts"
+
+REPO="$WORK/repo"; mkdir -p "$REPO"
+git -C "$REPO" init -q -b main
+git -C "$REPO" config user.email t@e
+git -C "$REPO" config user.name t
+echo base > "$REPO/base.txt"
+git -C "$REPO" add . && git -C "$REPO" commit -q -m base
+
+git -C "$REPO" checkout -q -b fix-task-s1
+echo a > "$REPO/a.txt"
+git -C "$REPO" add . && git -C "$REPO" commit -q -m s1
+DONE_SHA="$(git -C "$REPO" rev-parse HEAD)"
+git -C "$REPO" checkout -q main
+git -C "$REPO" merge --squash -q fix-task-s1
+git -C "$REPO" commit -q -m "squash s1"
+SQUASH_SHA="$(git -C "$REPO" rev-parse HEAD)"
+git -C "$REPO" branch -q -D fix-task-s1
+
+PLAN_ROOT="$WORK/runs/implementation-planning"; mkdir -p "$PLAN_ROOT"
+python3 - "$PLAN_ROOT" "$DONE_SHA" <<'PY'
+import sys
+from pathlib import Path
+from okstra_ctl.consumers import append_consumer
+append_consumer(Path(sys.argv[1]), impl_task_key="p/g/t", stage=1,
+                status="done", head_commit=sys.argv[2])
+PY
+
+OUT="$(python3 -m okstra_ctl.git_reconcile \
+  --project-root "$REPO" --plan-run-root "$PLAN_ROOT" \
+  --project-id p --task-group g --task-id t --work-category fix --json)" || true
+# branch 삭제됨 → done SHA 는 여전히 resolve 되므로 stale 항목 없음(exit 0).
+# squash 머지의 자동 화해는 prepare 의 multi-dep gate 경로이므로 여기서는
+# content_merged 단위로 직접 검증한다:
+python3 - "$REPO" "$DONE_SHA" "$SQUASH_SHA" <<'PY'
+import sys
+from pathlib import Path
+from okstra_ctl.git_reconcile import content_merged
+res = content_merged(Path(sys.argv[1]), sys.argv[2], "main")
+assert res.status == "patch-equivalent", res
+assert res.matched_commit == sys.argv[3], res
+print("scenario-13 OK: squash content reconciled")
+PY
+```
+
+Run: `bash tests-e2e/scenario-13-git-reconcile-squash.sh`
+Expected: `scenario-13 OK: squash content reconciled`
+
+- [ ] **Step 2: 스펙 보정** — 스펙 §3.3 의 문장 `` `okstra.sh` 도 동일 패스스루.`` 를 다음으로 교체:
+
+```
+`okstra.sh` 는 run 런처(flag 기반)라 ops subcommand dispatch 가 없으므로 배선하지 않는다 — ops 명령은 node CLI 전용(기존 `migrate` 와 동일).
+```
+
+- [ ] **Step 3: CHANGES.md 항목** — 파일 최상단 기존 첫 항목 위에 추가 (기존 항목 형식 그대로):
+
+```markdown
+### feat(okstra-ctl): okstra 밖 git 히스토리 변경 후 stale SHA 자동 회복 (git-reconcile)
+
+- **배경**: stage 기록(anchor / done `head_commit`)은 commit SHA 로 고정되는데, PR 리뷰 반영 amend·rebase·squash merge·branch 삭제 등 okstra 밖의 작업이 히스토리를 재작성하면 ancestor 게이트가 "not merged" 로 거부하고 회복 경로가 없어 registry/consumers 손편집이 필요했다.
+- **변경**: 신규 [`scripts/okstra_ctl/git_reconcile.py`](scripts/okstra_ctl/git_reconcile.py) 가 3단 방어를 제공 — ① patch-id(커밋 단위 + 범위 합산) 로 내용 동일성이 증명되면 prepare 가 자동 화해(보정 done row 재-append), ② 내용이 바뀐 항목은 `okstra git-reconcile --apply --stage N --use-ref <ref>` 로만 보정(무확인 자동 보정은 런타임이 거부), ③ anchor 는 `--reset-anchor` 로 재고정. done-row 읽기는 `latest_done_by_stage` 로 last-wins 통일. okstra-run 스킬은 PrepareError 회복 안내를 받아 3-옵션 picker 를 제시한다. 설계: [`docs/superpowers/specs/2026-06-10-git-reconcile-stale-sha-recovery-design.md`](docs/superpowers/specs/2026-06-10-git-reconcile-stale-sha-recovery-design.md).
+- 사용자 영향: 다음 release + `npx -y okstra@latest install` 후, PR 리뷰 수정·rebase·squash merge 이후에도 `implementation` run 이 손편집 없이 이어진다 — 내용이 같으면 자동, 내용이 바뀌었으면 picker 확인 한 번.
+```
+
+- [ ] **Step 4: 최종 검증 (critique mode)**
+
+```bash
+npm run build
+python3 -m pytest tests/ -q
+bash validators/validate-workflow.sh
+bash tests-e2e/scenario-13-git-reconcile-squash.sh
+node bin/okstra git-reconcile --help
+grep -rn "force_reappend\|latest_done_by_stage\|reset_implementation_base\|content_merged\|auto_reconcile" scripts/ src/ bin/ skills/ --include='*.py' --include='*.mjs' --include='*.md' -l
+```
+
+Expected: build 성공, pytest 전체 PASS, validator PASS, e2e OK, help 출력, grep 으로 신규 식별자의 정의·사용처가 의도한 파일에만 존재함을 확인.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests-e2e/scenario-13-git-reconcile-squash.sh CHANGES.md \
+  docs/superpowers/specs/2026-06-10-git-reconcile-stale-sha-recovery-design.md
+git commit -m "test(e2e): git-reconcile squash 회복 시나리오 + CHANGES 항목"
+```
+
+---
+
+## Self-Review 체크 결과 (작성 시점)
+
+- **스펙 커버리지**: §3.1→Task 4, §3.2→Task 5, §3.3→Task 6·7, §3.4→Task 1·3, §3.5→Task 6, §3.6→Task 8·9, §5 테스트→각 task TDD + Task 10. 스펙의 "classify 가 다중 의존 gate 도 평가" 는 prepare 경로 평가로 단순화(Task 5 docstring + Task 10 Step 2 스펙 보정으로 정합).
+- **타입 일관성**: `MatchResult.status` 4값, `StaleItem.classification` 3값, `reconcile_reason` ∈ {`auto-patch-id`, `user-ref`} 를 전 task 가 공유.
+- **함수 50줄 캡**: `content_merged`·`classify_task`·`apply_reconcile` 는 보조 함수 추출로 캡 이내. 구현 중 초과 시 추가 추출.