okstra 0.95.0 → 0.96.0

package/docs/kr/architecture.md

@@ -412,15 +412,18 @@ stage-group 의 상호작용 순서: **G1 base 선택 → G2 stage 확인(선택
 위상정렬이 담고, task 화 이후의 통합 일정은 okstra-schedule 이 맡는다. okstra-brief 는
 이 경로에 개입하지 않는다. 검증: `validators/validate_fanout.py`(validate-run 훅).
 
-### branch_confirm (worktree 결정 확인)
+### confirm 단계의 worktree 미리보기
 
-okstra-run wizard 는 최종 confirm 직전에 `branch_confirm` 단계로 "새 브랜치/worktree 생성 vs
-현재 worktree 재사용"을 명시 확인한다. 결정은 `worktree.preview_worktree_decision()`(부수효과 없음)
-으로 미리보고, 같은 헬퍼를 `provision_task_worktree` 가 실행에 쓰므로 미리보기와 실제가 일치한다.
-worktree 격리 동작 자체는 변경 없음(확인 게이트만). 옵션은 항상 `진행`/`중단` 을 포함하고,
-새 worktree 생성 케이스에만 `base-ref 다시 고르기`(edit) 가 추가된다 — 어떤 케이스든 picker 로
-렌더링 가능한 2-옵션 이상을 보장한다. `중단` 은 터미널이다: state 가 `aborted` 로 고정되고
-이후 `next_prompt` 는 `kind: "aborted"` 만 반환하며 `render-args` 는 `ok: false` 로 거부한다.
+okstra-run wizard 는 별도 분기 확인 단계를 두지 않고, 최종 `confirm` 직전 요약 블록
+(`confirmation_block`)에 "새 브랜치/worktree 생성 vs 현재 worktree 재사용"을 `worktree` 한 줄로
+보여준다. 결정은 `worktree.preview_worktree_decision()`(부수효과 없음)으로 미리보고, 같은 헬퍼를
+`provision_task_worktree` 가 실행에 쓰므로 미리보기와 실제가 일치한다. `implementation` 은 stage
+격리로 동작하므로 task-key 디렉터리가 아니라 이번 run 이 실제 쓸 stage worktree 관점으로
+미리본다(`preview_stage_worktree_decision` / stage `auto` 는 `compute_worktree_path`).
+`final-verification` 은 stage worktree 를 읽기 전용 재사용하므로 worktree 줄을 생략한다.
+`confirm` 옵션은 `Proceed`/`Edit`/`중단` 3-옵션이다 — `Edit` 은 임의 step 으로 되감기(base-ref
+재선택 포함), `중단` 은 터미널이다: state 가 `aborted` 로 고정되고 이후 `next_prompt` 는
+`kind: "aborted"` 만 반환하며 `render-args` 는 `ok: false` 로 거부한다.
 
 
 ---
@@ -469,9 +472,11 @@ task manifest, task index, instruction-set, runs, history가 이 루트 아래
 │       ├── logs/
 │       │   └── errors-<task-type>-<seq>.jsonl        # optional, lead-only writer
 │       └── worker-results/
-└── history/
-    ├── timeline.json
-    └── fix-cycles.jsonl          # optional, fix cycle 진입 시에만 생성 (append-only)
+├── history/
+│   ├── timeline.json
+│   └── fix-cycles.jsonl          # optional, fix cycle 진입 시에만 생성 (append-only)
+└── recap/
+    └── recap-log.jsonl          # optional, recap facet 의 전/후 요약·Q&A append-only 로그 (다른 산출물 불변)
 ```
 
 실제 디렉터리 세그먼트는 안전한 경로 생성을 위해 slug 형태로 정규화될 수 있습니다.

package/docs/project-structure-overview.md

@@ -189,6 +189,9 @@ Important modules:
 | Module | Role |
 |---|---|
 | `run.py` | `prepare_task_bundle()` single authority and CLI parser |
+| `implementation_stage.py` | `implementation` 단일-stage run 오케스트레이션 — consumer 상태 복구 → 가용 Stage Map entry 선택 → 격리 stage worktree provision → 선택 stage 를 run context 로 발행 (`run.py` 에서 추출) |
+| `stage_targets.py` | Stage readiness/verification 정책 SSOT — 어떤 stage 가 실행 가능한지, 어느 commit 에서 분기하는지, final-verification 이 무엇을 검사하는지 결정 (`consumers.jsonl` 행과 git ancestry 검사를 단일 인터페이스 뒤로 캡슐화) |
+| `stage_reconcile.py` | stage prepare 흐름 공용 best-effort git reconciliation (`git_reconcile.auto_reconcile` 위임; advisory — 실패는 stderr 보고만, dependency gate 가 권위 판정 유지) |
 | `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
 | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
 | `paths.py` | Path/sequence computation for task/run artifacts |