okstra 0.70.0 → 0.71.1

package/docs/kr/architecture.md

@@ -373,7 +373,9 @@ okstra phase 는 PRD / issue file 을 직접 쓰지 않습니다. 동등한 결
 - **whole-task (기본)**: task 전체를 1개 PR 로 내보냅니다. 기존 동작입니다.
 - **stage-group**: 단독-stage final-verification 에서 `accepted` 를 받은 stage 들 중 일부를 골라, 수집(collector) 브랜치로 묶어 1개 PR 로 내보냅니다. task 전체가 끝나기를 기다리지 않고 검증 완료된 stage 묶음 단위로 PR 을 낼 수 있습니다.
 
-stage-group 의 상호작용 순서: **G1 base 선택 → G2 stage multi-select → assemble(수집 브랜치 생성 + 선택 stage 머지) → 충돌 프로브 → PR 초안 → push/PR**.
+진입은 brief 없이 **task-id 기반**입니다 — brief 는 entry phase 의 입력물이고, release-handoff 는 prepare 가 approved plan 의 Stage Map + `consumers.jsonl` 로 자격을 판정한 뒤 검증 보고서를 인용하는 input 문서(`<task_root>/release-handoff-input.md`)를 자동 생성합니다. stage 선택은 okstra-run wizard 의 `handoff_stage_pick` 멀티선택(eligible stage 묶음 / accepted whole-task 보고서가 있으면 전체 task) 또는 CLI `--stages <csv>` 로 들어오고, run-context 의 `HANDOFF_MODE` / `HANDOFF_STAGES` 로 lead 에 노출됩니다.
+
+stage-group 의 상호작용 순서: **G1 base 선택 → G2 stage 확인(선택은 prepare 전에 끝남 — 재질문 없음) → assemble(수집 브랜치 생성 + 선택 stage 머지) → 충돌 프로브 → PR 초안 → push/PR**.
 
 - 자격 판정의 SSOT 는 `consumers.jsonl` 의 두 행입니다 — `verified`(어떤 stage 가 단독-stage final-verification 에서 accepted 됨), `pr`(어떤 stage 들이 어느 PR 로 나갔는지). `verified` 인데 아직 `pr` 에 안 들어간 stage 가 자격 후보입니다.
 - worktree registry 는 stage-group 점유를 `<task-key>#group-<id>` 키로 예약하고, 수집 브랜치 이름은 `<work-category-prefix>-<task-id-segment>-g2-3` (예: 선택한 stage 가 2·3 이면 `-g2-3`) 형태입니다.
@@ -680,6 +682,8 @@ canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니
 
 `okstra`는 brief-first 구조입니다. brief 는 외부 입력과 okstra 보강을 보존하는 정본 source material 이며, 워커가 필요로 할 추가 자료(보고서, 코드 스니펫, 로그 등)는 brief 내부의 `Evidence and Source Materials` 섹션에 inline 또는 path 로 모두 포함시킵니다.
 
+brief 의 **입력 시점은 entry phase 전용**입니다 — 사용자가 brief 경로를 직접 대는 것은 `requirements-discovery` / `error-analysis` / `improvement-discovery` 뿐이고, downstream phase(implementation-planning / implementation / final-verification)는 task manifest 의 `taskBriefPath` 를 자동 carry-in 합니다 (okstra-run wizard 가 묻지 않음; 미등록 시 entry 전환을 추천하는 fallback picker). `release-handoff` 는 brief 자체가 없으며 prepare 가 검증 보고서 인용 input 문서를 생성합니다.
+
 brief 는 **translation layer** 입니다 — 외부 입력 (이슈 트래커 ticket, 요구사항 문서, 사용자 메시지) 을 okstra-readable 형식으로 옮기되, 원문은 verbatim 으로 보존하고 okstra 가 추가한 부분은 labelled augmentation 으로 명확히 구분합니다. `okstra-brief` skill 의 산출이 source SSOT 이고, `prepare_task_bundle()` 은 분석 phase 마다 여기서 필요한 frontmatter, task-specific brief 섹션, reference expectations, carry-in clarification, directive 를 추출해 `instruction-set/analysis-packet.md` 를 만듭니다. 분석 워커의 1차 입력은 이 compact packet 이며, 원본 brief 와 profile/material 파일은 근거 확인이나 누락 보완이 필요할 때만 여는 fallback evidence 입니다.
 
 brief에는 보통 아래를 포함합니다.

package/docs/kr/cli.md

@@ -132,6 +132,12 @@ interactive terminal에서 실행하면 다음 규칙이 추가로 적용됩니
 분석의 기준이 되는 task brief 문서 경로입니다.
 상대 경로는 대상 프로젝트 루트를 기준으로 해석됩니다.
 
+`release-handoff` 에는 적용되지 않습니다 — brief 는 entry phase
+(requirements-discovery / error-analysis / improvement-discovery)의 입력물이고,
+release-handoff 는 prepare 가 검증 보고서를 인용하는 input 문서
+(`<task_root>/release-handoff-input.md`)를 자동 생성해 brief 자리를 채웁니다.
+release-handoff 에 비어 있지 않은 `--task-brief` 를 주면 즉시 거부됩니다.
+
 예:
 
 - `.project-docs/linear/feature/8858/okstra-task-brief.md`
@@ -593,9 +599,9 @@ chmod +x ~/.local/bin/okstra-ctl
 | `okstra task-show <task-key> [--project-root <path>]` | task-manifest.json 의 workflow / phase / status 요약 |
 | `okstra worktree-lookup <task-key>` | `worktree_registry.lookup` 결과 (예약된 path / branch / base ref / 현재 상태) |
 | `okstra plan-validate <plan-path>` | `_validate_approved_plan` — frontmatter `approved` 인식 결과와 Blocks=approval 미해결 행 진단 |
-| `okstra render-bundle <args…> [--stage <auto\|N>]` | `prepare_task_bundle(render_only=True)` 의 thin shim — `python3 -m okstra_ctl.run --render-only` 와 동일 시그니처. `--stage` 는 `implementation` / `final-verification` 전용: 실행(검증)할 Stage Map 항목 지정. `implementation` 은 `auto` (기본값) = 의존성이 만족된 가장 빠른 미완료 stage, `<N>` = 강제 지정. `final-verification` 은 `<N>` = 해당 stage 단독 검증(산출물이 `runs/final-verification/stage-<N>/` 에 격리되고 팀 이름에 `-fv-s<N>` 접미사), 빈 값 = 전체-task 검증(평면 구조 유지) |
+| `okstra render-bundle <args…> [--stage <auto\|N>] [--stages <csv>]` | `prepare_task_bundle(render_only=True)` 의 thin shim — `python3 -m okstra_ctl.run --render-only` 와 동일 시그니처. `--stage` 는 `implementation` / `final-verification` 전용: 실행(검증)할 Stage Map 항목 지정. `implementation` 은 `auto` (기본값) = 의존성이 만족된 가장 빠른 미완료 stage, `<N>` = 강제 지정. `final-verification` 은 `<N>` = 해당 stage 단독 검증(산출물이 `runs/final-verification/stage-<N>/` 에 격리되고 팀 이름에 `-fv-s<N>` 접미사), 빈 값 = 전체-task 검증(평면 구조 유지). `--stages <csv>` 는 `release-handoff` 전용(별개 채널): PR 로 묶을 stage 번호들(stage-group 모드), 빈 값 = whole-task 모드. prepare 가 eligibility(`done`+`verified` accepted+미-`pr`)를 강제하고 검증 보고서 인용 input 문서를 자동 생성한다 |
 | `okstra render-views <final-report.md>` | Phase 7 step 1.5 — 토큰 치환된 final-report MD 한 본을 입력으로 sibling `*.slim.md` (AI 입력용) + `*.html` (사람용 self-contained) 두 view 를 결정론적으로 생성. 원본 MD 는 수정하지 않음. Node 위임 wrapper는 `scripts/okstra-render-report-views.py` 를 호출. `validators/validate-report-views.py` 가 substring 보존 / form-control 위치 / Response ID parity 를 검사 |
-| `okstra wizard <init\|step\|render-args\|confirmation> --state-file <path>` | okstra-run 인터랙티브 입력 상태머신 (`okstra_ctl.wizard`). `init` 으로 state file 을 시드한 뒤 skill 이 `step --answer <val>` 을 반복 호출하면 다음 `Prompt` JSON 을 받음. `--answer` 는 **필수**. 응답을 주지 않고 다음 prompt 만 미리 보고 싶다면 `--no-submit` 으로 peek. `render-args` 는 최종 `render-bundle` 인자 맵, `confirmation` 은 사용자 echo 블록을 반환. `implementation` task type 에서는 `approved_plan_pick` 직후 `stage_pick` 단계가 추가되어 실행할 stage 를 선택하고, `executor_pick` 으로 넘어갑니다 |
+| `okstra wizard <init\|step\|render-args\|confirmation> --state-file <path>` | okstra-run 인터랙티브 입력 상태머신 (`okstra_ctl.wizard`). `init` 으로 state file 을 시드한 뒤 skill 이 `step --answer <val>` 을 반복 호출하면 다음 `Prompt` JSON 을 받음. `--answer` 는 **필수**. 응답을 주지 않고 다음 prompt 만 미리 보고 싶다면 `--no-submit` 으로 peek. `render-args` 는 최종 `render-bundle` 인자 맵, `confirmation` 은 사용자 echo 블록을 반환. `implementation` task type 에서는 `approved_plan_pick` 직후 `stage_pick` 단계가 추가되어 실행할 stage 를 선택하고, `executor_pick` 으로 넘어갑니다. brief 단계는 entry task-type(requirements-discovery / error-analysis / improvement-discovery)에서만 나오며, downstream 은 manifest 의 brief 를 자동 carry-in 하고(미등록 시 `brief_carry` 3-옵션 fallback), `release-handoff` 는 brief 없이 `handoff_stage_pick` 멀티선택(eligible stage 묶음 / 전체 task)으로 진입합니다 |
 | `okstra token-usage ...` | 설치된 `okstra-token-usage.py` 를 감싸 run token usage 수집/치환을 수행. 세션 jsonl 은 기본적으로 `$OKSTRA_HOME/cache/token-usage/` 의 byte cursor 캐시로 증분 스캔하며, `--no-cache` 로 캐시를 우회해 전체 재스캔을 강제할 수 있음(정확성 폴백) |
 
 > 모든 subcommand 는 `bin/okstra` 가 spawn 하는 python 헬퍼 (`src/_python-helper.mjs`) 가 `PYTHONPATH` 와 `~/.okstra/lib/python` 을 wire 합니다. 직접 `python3 -m okstra_ctl.*` 으로 호출하면 `PYTHONPATH` 를 사용자가 직접 셋업해야 합니다.

package/docs/superpowers/specs/2026-06-11-brief-entry-only-handoff-stage-entry-design.md

@@ -0,0 +1,158 @@
+# brief entry-phase 한정 + release-handoff task-id 기반 stage 진입 — 설계
+
+- 날짜: 2026-06-11
+- 상태: 구현 완료 (사용자 승인 후 구현 — §5.3 의 manifest 갱신 항목만 구현 시 수정)
+- 선행 설계: [2026-06-10-stage-group-handoff-design.md](2026-06-10-stage-group-handoff-design.md) (stage-group 백엔드), [2026-06-06-stage-worktree-isolation-design.md](2026-06-06-stage-worktree-isolation-design.md)
+
+## 1. 배경 / 문제
+
+brief 는 비개발자·타 팀·아이디어·에러 신고 초안을 담는 **entry-phase 입력물**인데, 현재 구조는 모든 phase 에서 brief 를 의식처럼 요구한다. 사용자가 실제 run 에서 확인한 문제 세 가지:
+
+1. **위저드가 전 task-type 에 brief 를 묻는다.** brief 단계에 task-type 필터가 없고([wizard.py:2367-2382](../../../scripts/okstra_ctl/wizard.py:2367)), 기존 task 면 `brief_keep` 으로 유지/변경을 또 묻는다([wizard.py:2418-2425](../../../scripts/okstra_ctl/wizard.py:2418)). downstream phase 의 brief 는 task manifest 의 `taskBriefPath` 로 이미 자동 해소 가능한데도([wizard.py:830-837](../../../scripts/okstra_ctl/wizard.py:830)) 사용자 입력을 요구한다.
+2. **release-handoff 의 실질 입력은 final-verification final-report 인데 위저드는 brief 경로를 요구한다.** stage-group 모드 진입 조건이 "brief 가 단독-stage 검증 보고서 N 개를 인용"이라는 수동 의식이고([release-handoff.md:15](../../../prompts/profiles/release-handoff.md:15)), 그 brief 를 만들어 주는 자동화는 없다 — [release-handoff-input.template.md](../../../templates/reports/release-handoff-input.template.md) 는 렌더러가 없는 죽은 템플릿이며 단수 인용 슬롯뿐이다. 모드(whole-task/stage-group)를 사용자에게 보여주는 지점도 위저드·brief·게이트 어디에도 없다.
+3. **stage 자격 판정 인프라는 이미 있다.** `okstra_ctl.handoff.compute_eligibility` 가 approved plan 의 Stage Map + `consumers.jsonl`(done + `verified` accepted + 미-`pr`)로 stage 별 PR 자격을 판정한다([handoff.py:36-39](../../../scripts/okstra_ctl/handoff.py:36)). task-id 만 있으면 계산되는 정보를 brief 인용으로 중복 선언하게 하는 것은 단일 참조점 위반이다.
+
+## 2. 결정 요약 (사용자 Q&A)
+
+| 질문 | 결정 |
+|---|---|
+| brief 는 어느 phase 입력인가 | entry phase(requirements-discovery / error-analysis / improvement-discovery) 전용. downstream 은 task-id 로 자동 carry-in |
+| release-handoff 진입 입력 | brief 경로가 아니라 task-id. 검증 완료(eligible) stage 를 멀티선택하거나 전체 선택 |
+| stage 선택 근거 | implementation-planning final-report 의 Stage Map + consumers 상태 (`handoff eligible` 재사용) |
+| PR 생성 후 stage worktree 정리 | **범위 제외** (사용자 결정 — PR 리뷰 수정이 stage 브랜치를 재사용하는 흐름과 충돌 위험) |
+
+## 3. 목표 / 비목표
+
+목표:
+
+- 위저드 brief 단계(`brief_path_pick`/`brief_path`/`brief_keep`)를 entry phase 에만 적용하고, downstream phase 는 manifest `taskBriefPath` 로 자동 해소한다.
+- release-handoff 위저드 진입을 brief picker 대신 **eligible stage picker** 로 교체한다. 모드는 선택 결과로 자동 결정된다.
+- prepare 가 release-handoff 의 입력 문서(검증 보고서 인용 래퍼)를 [release-handoff-input.template.md](../../../templates/reports/release-handoff-input.template.md) 로 **자동 생성**한다 — 죽은 템플릿의 부활, 수동 brief 작성 제거.
+- `--stage`(impl/fv 의 Stage Map 실행/검증 선택)와 release-handoff 의 stage 묶음 선택을 **별개 채널**로 유지하되, 후자를 위저드 → render-bundle 로 전달하는 `--stages` flag 를 신설한다.
+
+비목표:
+
+- PR 생성 후 worktree/branch/registry 정리 (사용자 결정으로 제외).
+- `handoff eligible / assemble / record-*` 백엔드 로직 변경 — 그대로 재사용한다.
+- 다른 phase 의 죽은 input 템플릿(`error-analysis-input` 등) 정비 — 후속 과제(§9).
+- okstra-brief 스킬 변경 — entry phase 용도 그대로.
+- prepare 의 `--task-brief` 필수 계약 변경 — 위저드/prepare 가 채워 넣는 방식만 바뀐다.
+
+## 4. 설계 A — brief 를 entry phase 전용으로
+
+### 4.1 task-type 분류 (SSOT 상수)
+
+`wizard.py` 에 상수 신설 (기존 `_STAGE_SCOPED_TASK_TYPES` [wizard.py:89](../../../scripts/okstra_ctl/wizard.py:89) 와 나란히):
+
+```python
+_BRIEF_ENTRY_TASK_TYPES = ("requirements-discovery", "error-analysis",
+                           "improvement-discovery")
+```
+
+downstream = 그 외 전부(implementation-planning, implementation, final-verification, release-handoff).
+
+### 4.2 위저드 단계 변경
+
+- `S_BRIEF_PATH_PICK` / `S_BRIEF_PATH` / `S_BRIEF_KEEP` 의 `applies` 에 `s.task_type in _BRIEF_ENTRY_TASK_TYPES` 게이트 추가.
+  - 주의: 현재 신규 task 흐름은 brief 선택이 task-type 선택보다 **앞선다**([wizard.py:2373](../../../scripts/okstra_ctl/wizard.py:2373) `is_new_task is True and bool(task_group)`). 게이트를 넣으려면 신규 task 의 단계 순서를 task-type 먼저로 재배열해야 한다(§8 테스트로 고정). 기존 task 흐름은 이미 task-type 이후에 brief 를 묻는다.
+- downstream + 기존 task: `_existing_task_brief()` 결과를 `state.brief_path` 에 **자동 주입**하고 brief 관련 단계를 모두 건너뛴다. 사용자에게 echo 한 줄로만 알린다 (`brief (carry-in): <path>`).
+- downstream + brief 미등록 (신규 task 로 downstream type 을 고르거나 manifest 에 `taskBriefPath` 없음): 3-옵션 picker (run-prompt 추천 규칙 준수):
+  1. (추천) entry phase 로 task-type 변경 — picker 가 entry 3종을 보여주고 task-type 단계로 되돌린다.
+  2. brief 경로 직접 입력 — 탈출구. 손으로 쓴 brief 로 downstream 부터 시작하는 기존 워크플로 보존.
+  3. 중단.
+- release-handoff 는 §5 의 자동 생성 입력이 brief 역할을 대체하므로 이 picker 대상에서도 제외된다.
+
+### 4.3 계약 불변 사항
+
+- prepare 의 `--task-brief` 필수 검증([run.py:2209-2212](../../../scripts/okstra_ctl/run.py:2209))과 downstream profile 들의 brief 인용(예: Requirement Coverage 가 brief heading 인용 — [implementation-planning.md:86](../../../prompts/profiles/implementation-planning.md:86))은 그대로다. brief 는 여전히 전 phase 의 요구사항 anchor 다 — 바뀌는 것은 "누가 경로를 대는가"(사용자 → 위저드 자동) 뿐이다.
+
+## 5. 설계 B — release-handoff: task-id 진입 + eligible stage picker
+
+### 5.1 위저드 흐름 (release-handoff 한정)
+
+```
+task 선택(기존 task 전제) → task-type=release-handoff
+  → approved-plan 자동 해소 (fv 와 동일: _latest_implementation_planning_report
+     + frontmatter approved: true 확인; 실패 시 implementation-planning 선행 안내)
+  → S_HANDOFF_STAGE_PICK (신규):
+       compute_eligibility 직접 호출 (python import — shell-out 금지, 단일 참조점)
+       옵션:
+         - "전체 task (whole-task 검증 기반)" — whole-task fv 보고서(accepted,
+           verificationScope=whole-task)가 존재할 때만 노출 → whole-task 모드
+         - eligible stage 멀티선택 (전체 eligible 선택 = "다 같이") → stage-group 모드
+         - blocked stage 는 reasons 와 함께 비선택 표시
+  → (이후 기존 단계: pr-template, 모델/directive 등 — 변경 없음)
+```
+
+- brief 단계 없음, base-ref 단계 없음(현행 유지 — PR base 는 run 중 G1/Q2 가 묻는다).
+- 모드 질문은 별도 단계가 아니라 **이 picker 의 선택지로 흡수**된다.
+
+### 5.2 인자 전달 — `--stages` 신설
+
+- `render_args()` 가 release-handoff 일 때 신규 키 `stages` 를 채운다: whole-task = `""`, stage-group = `"2,3"` (csv).
+- `render-bundle` / `okstra.sh` / `okstra_ctl.run` argparse 에 `--stages` 추가. **release-handoff 외 task-type 에서 비어 있지 않은 `--stages` 는 PrepareError** (어제 고친 `--stage` 빈 값 규칙과 동일하게, 빈 문자열은 미지정으로 통과 — [run.py:1124](../../../scripts/okstra_ctl/run.py:1124) 패턴).
+- `--stage` 와 `--stages` 는 다른 채널이다: 전자 = impl/fv 의 Stage Map 실행/검증 선택, 후자 = release-handoff 의 PR 묶음 선택. 도움말에 명시한다.
+
+### 5.3 prepare — 입력 문서 자동 생성
+
+release-handoff prepare 시:
+
+1. `compute_eligibility` 로 선택 stage 들의 자격을 **재검증** (위저드를 거치지 않은 CLI 경로도 같은 강제 지점을 통과).
+2. 각 선택 stage 의 단독 검증 보고서 경로·verdict 를 `consumers.jsonl` 의 `verified` 행(last-wins, [consumers.py:107-111](../../../scripts/okstra_ctl/consumers.py:107))에서 수집. whole-task 면 최신 whole-task fv final-report 에서 수집.
+3. [release-handoff-input.template.md](../../../templates/reports/release-handoff-input.template.md) 를 렌더링해 `<task_root>/release-handoff-input.md` 로 저장(매 run 덮어씀) → 이 파일이 그 run 의 brief 자리(`inp.brief_path`)를 채운다. manifest `taskBriefPath` 는 **갱신하지 않는다** — entry brief 포인터를 덮으면 이후 다른 phase 의 carry-in 이 handoff input 을 brief 로 오인하기 때문(구현 시 확정한 spec 수정).
+4. run-context 에 `HANDOFF_MODE` (`whole-task` | `stage-group`) 와 `HANDOFF_STAGES` 를 기록.
+
+### 5.4 템플릿 개정
+
+`## Source Verification Report` 를 단수/복수 겸용으로 교체:
+
+```markdown
+## Source Verification Report
+
+- Mode: `whole-task` | `stage-group`
+- Reports (one row per cited final-verification report):
+
+| Stage | Report path | Verdict Token (verbatim) | Run timestamp |
+|---|---|---|---|
+```
+
+whole-task 모드는 Stage 열을 `(all)` 한 행으로 채운다.
+
+### 5.5 profile 개정 ([release-handoff.md](../../../prompts/profiles/release-handoff.md))
+
+- 진입 게이트(:13-15): "brief 가 인용해야 한다" → "prepare 가 생성한 input 문서 + run-context 의 `HANDOFF_MODE`/`HANDOFF_STAGES` 를 읽고, 인용된 각 Verdict Token 이 `accepted` 인지 확인한다" 로 교체.
+- G2(:27): 위저드/CLI 에서 stage 가 이미 선택돼 있으므로 **재선택이 아니라 확인 표시**로 축소 — 선택 목록을 보여주고 진행. `okstra handoff eligible` 직접 호출 분기는 stage 선택 없이 진입한 비정상 경로의 방어로만 남긴다.
+- assemble(:28) 이후 흐름(G1 base → assemble → Q2b → Q3, record-pr)은 불변.
+
+## 6. 설계 C — final-verification
+
+stage picker(done 마킹 + 전체 task 검증)는 최근 작업으로 이미 사용자 모델과 일치한다. 이 설계에서는 §4 의 brief 자동 carry-in 만 적용된다.
+
+## 7. 영향 파일
+
+| 파일 | 변경 |
+|---|---|
+| [scripts/okstra_ctl/wizard.py](../../../scripts/okstra_ctl/wizard.py) | `_BRIEF_ENTRY_TASK_TYPES`, brief 단계 게이트·자동 주입·미등록 picker, 신규 task 단계 순서 재배열, `S_HANDOFF_STAGE_PICK`, `render_args` `stages` 키 |
+| [scripts/okstra_ctl/run.py](../../../scripts/okstra_ctl/run.py) | `--stages` argparse + 검증 + prepare 의 input 자동 생성·`HANDOFF_MODE`/`HANDOFF_STAGES` |
+| [scripts/okstra_ctl/handoff.py](../../../scripts/okstra_ctl/handoff.py) | (변경 없음 — import 재사용) |
+| [templates/reports/release-handoff-input.template.md](../../../templates/reports/release-handoff-input.template.md) | Source Verification Report 복수 양식 |
+| [prompts/profiles/release-handoff.md](../../../prompts/profiles/release-handoff.md) | 진입 게이트·G2 개정 |
+| [prompts/wizard/prompts.ko.json](../../../prompts/wizard/prompts.ko.json) | 신규/변경 prompt 문구 |
+| [skills/okstra-run/SKILL.md](../../../skills/okstra-run/SKILL.md) | render-bundle 호출부 `--stages`, brief 단계 서술 갱신 |
+| [scripts/okstra.sh](../../../scripts/okstra.sh) | `--stages` 전달 |
+| [docs/kr/cli.md](../../../docs/kr/cli.md), [docs/kr/architecture.md](../../../docs/kr/architecture.md), [docs/task-process/release-handoff.md](../../../docs/task-process/release-handoff.md) | 계약 서술 갱신 |
+
+## 8. 테스트
+
+- 위저드 단계 적용 매트릭스: entry 3종 = brief 단계 노출, downstream 4종 = 미노출 + 자동 주입 echo. 신규 task 단계 순서(task-type 이 brief 보다 먼저) 회귀.
+- downstream + brief 미등록 → 3-옵션 picker 노출, 각 분기 동작.
+- `S_HANDOFF_STAGE_PICK`: eligible/blocked 구성, whole-task 옵션 노출 조건, 멀티선택 → `render_args["stages"]` csv.
+- `--stages` 게이트: release-handoff 외 task-type 의 비어 있지 않은 값 거부, 빈 값 통과 (기존 [tests/test_prepare_stage_flag_gate.py](../../../tests/test_prepare_stage_flag_gate.py) 패턴).
+- prepare 입력 자동 생성: verified 행 인용 정확성(단위) + subprocess `--render-only` e2e 로 생성 파일·manifest 갱신 확인.
+- profile 계약: validators 의 release-handoff 관련 체크가 있다면 갱신분 통과.
+
+## 9. 미해결 / 후속
+
+- 다른 phase 의 죽은 input 템플릿([render.py:113-118](../../../scripts/okstra_ctl/render.py:113) 태그만 존재) 정리 또는 부활 — 별도 과제.
+- PR 생성 후 stage worktree/branch/registry 정리 — 이번 범위에서 명시적으로 제외(사용자 결정). 재논의 시 PR 리뷰 수정 흐름([okstra-run SKILL.md:228](../../../skills/okstra-run/SKILL.md:228))과의 충돌을 먼저 풀어야 한다.
+- okstra-brief 체인 다이어그램([SKILL.md:44-57](../../../skills/okstra-brief/SKILL.md:44))의 release-handoff 종단 표기 정합화.

package/docs/task-process/release-handoff.md

@@ -51,8 +51,9 @@ sequenceDiagram
     participant WT as worktree registry
     participant FS as task artifacts
 
-    W->>P: task-type=release-handoff, brief, optional pr-template-path
-    P->>P: validate profile and brief
+    W->>P: task-type=release-handoff, approved-plan, stages csv, optional pr-template-path
+    P->>P: enforce stage eligibility (consumers verified/pr rows)
+    P->>FS: generate release-handoff-input.md (cited verification reports)
     P->>P: force workers=[]
     P->>T: resolve PR template
     P->>WT: reuse or provision task worktree
@@ -67,7 +68,7 @@ profile에 `Required workers:` block이 없고 `run.py`도 `release-handoff`에
 
 ```mermaid
 flowchart TD
-    Brief[task brief] --> Source{Source Verification Report present?}
+    Brief[release-handoff-input.md<br/>generated by prepare] --> Source{Source Verification Report present?}
     Source -->|no| Block[blocked<br/>route final-verification]
     Source -->|yes| Verdict{Verdict Token == accepted?}
     Verdict -->|no| Block
@@ -82,8 +83,8 @@ flowchart TD
 
 lead는 사용자에게 push/PR 여부를 묻기 전에 다음을 확인한다.
 
-- task brief가 `## Source Verification Report`를 가리킨다.
-- 그 report의 `## 7. Final Verdict`에 `Verdict Token = accepted`가 정확히 있다.
+- prepare 가 생성한 input 문서(`release-handoff-input.md`)의 `## Source Verification Report` 가 모드(`HANDOFF_MODE`)와 인용 보고서 표를 담고 있다. brief 는 entry phase 의 입력물이라 release-handoff 에는 없다 — 사용자의 stage 선택은 wizard `handoff_stage_pick` 또는 CLI `--stages` 로 prepare 전에 끝난다.
+- 인용된 각 report 의 `## 7. Final Verdict`에 `Verdict Token = accepted`가 정확히 있다.
 - working tree가 clean이다.
 - 현재 branch가 `main`, `master`, `prod`, `preprod`, `staging`, `dev` 같은 base branch가 아니다.
 - `<base>..HEAD` commit range가 비어 있지 않다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.70.0",
+  "version": "0.71.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.70.0",
-  "builtAt": "2026-06-10T17:00:34.215Z",
+  "package": "0.71.1",
+  "builtAt": "2026-06-11T03:33:31.499Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/lib/okstra/cli.sh

@@ -24,7 +24,10 @@ collect_required_arguments() {
   prompt_for_required_argument TASK_GROUP "Task Group"
   prompt_for_required_argument TASK_ID "Task ID"
   prompt_for_required_argument TASK_TYPE "Task Type"
-  prompt_for_required_argument BRIEF_PATH "Task Brief Path"
+  if [[ "$TASK_TYPE" != "release-handoff" ]]; then
+    # release-handoff 는 brief 가 없다 — prepare 가 검증 보고서 인용 input 을 생성.
+    prompt_for_required_argument BRIEF_PATH "Task Brief Path"
+  fi
 }
 
 require_option_value() {
@@ -103,6 +106,10 @@ while [[ $# -gt 0 ]]; do
       STAGE="$(require_option_value --stage "${2-}")"
       shift 2
       ;;
+    --stages)
+      STAGES="$(require_option_value --stages "${2-}")"
+      shift 2
+      ;;
     --qa-waiver)
       QA_WAIVER="$(require_option_value --qa-waiver "${2-}")"
       shift 2

package/runtime/bin/lib/okstra/interactive.sh

@@ -215,14 +215,16 @@ PY
     esac
   done <<<"$autofill_output"
 
-  if [[ -z "$BRIEF_PATH" && -n "$manifest_brief" ]]; then
-    BRIEF_PATH="$manifest_brief"
-    printf 'autofill: brief-path from task-manifest.json: %s\n' "$BRIEF_PATH" >&2
-  fi
   if [[ -z "$TASK_TYPE" && -n "$manifest_type" ]]; then
     TASK_TYPE="$manifest_type"
     printf 'autofill: task-type from manifest workflow.nextRecommendedPhase: %s\n' "$TASK_TYPE" >&2
   fi
+  # release-handoff 는 brief 입력이 없다 (prepare 가 검증 보고서 인용 input 을
+  # 생성) — task-type autofill 이후에 판정해야 하므로 순서가 위와 바뀌면 안 된다.
+  if [[ -z "$BRIEF_PATH" && -n "$manifest_brief" && "$TASK_TYPE" != "release-handoff" ]]; then
+    BRIEF_PATH="$manifest_brief"
+    printf 'autofill: brief-path from task-manifest.json: %s\n' "$BRIEF_PATH" >&2
+  fi
 }
 
 missing_required_arguments_summary() {
@@ -232,7 +234,8 @@ missing_required_arguments_summary() {
   [[ -z "$TASK_GROUP" ]] && missing+=("<task-group>")
   [[ -z "$TASK_ID" ]] && missing+=("<task-id>")
   [[ -z "$TASK_TYPE" ]] && missing+=("<task-type>")
-  [[ -z "$BRIEF_PATH" ]] && missing+=("<brief-path>")
+  # release-handoff 는 brief 입력이 없다 — prepare 가 input 문서를 생성한다.
+  [[ -z "$BRIEF_PATH" && "$TASK_TYPE" != "release-handoff" ]] && missing+=("<brief-path>")
 
   if (( ${#missing[@]} == 0 )); then
     printf '%s' ""

package/runtime/bin/okstra.sh

@@ -124,6 +124,7 @@ PY_ARGS=(
 [[ -n "${WORK_CATEGORY-}" ]] && PY_ARGS+=(--work-category "$WORK_CATEGORY")
 [[ -n "${BASE_REF-}" ]] && PY_ARGS+=(--base-ref "$BASE_REF")
 [[ -n "${STAGE-}" ]] && PY_ARGS+=(--stage "$STAGE")
+[[ -n "${STAGES-}" ]] && PY_ARGS+=(--stages "$STAGES")
 [[ -n "${QA_WAIVER-}" ]] && PY_ARGS+=(--qa-waiver "$QA_WAIVER")
 [[ "$RENDER_ONLY" == "true" ]] && PY_ARGS+=(--render-only)
 [[ "$PLAN_VERIFICATION_ENABLED" == "false" ]] && PY_ARGS+=(--no-plan-verification)

package/runtime/prompts/profiles/_implementation-deliverable.md

@@ -50,6 +50,6 @@ are collected and convergence finished. Phase 1-5 do not need it.
 
 - Parse the executor's `### Stage Carry Evidence` JSON block. If absent or unparsable, end with status `contract-violated` and route to a follow-up `error-analysis`.
 - For this run's single stage: write its JSON verbatim to `runs/<impl-task-key>/carry/stage-<N>.json`. Refuse to overwrite an existing file (one stage = one sidecar; re-runs are out of scope for this version).
-- For this run's single stage: append a `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` with `completed_at`, `carry_path`, `report_path` (this run's final-report path relative to the run root), and the SHA of HEAD. Use the okstra runtime's `consumers_mutex` helper (NOT a raw filesystem write) to honour the lock. `report_path` lets `final-verification` cite each stage's originating report when assembling its Source Implementation Report list.
+- For this run's single stage: append a `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` with `completed_at`, `carry_path`, `report_path` (this run's final-report path relative to the run root), and the SHA of HEAD. Append it with `okstra_ctl.consumers.append_consumer` (NOT a raw filesystem write) — it honours the consumers lock AND releases this stage's worktree-registry occupancy, so later runs stop seeing a finished stage as a concurrent run. `report_path` lets `final-verification` cite each stage's originating report when assembling its Source Implementation Report list.
 - The verifier round, Phase 5.5 convergence, and this Phase 6 report run **once per run** over this stage's diff — NOT per step.
 - Quote this stage's new contents (the sidecar JSON in full and the new consumers row by itself) in the final report's `Stage sidecar evidence` deliverable section.

package/runtime/prompts/profiles/release-handoff.md

@@ -11,8 +11,9 @@
   - The shared "authority & permissions assumption" rule from the common contract still applies: assume the user holds every permission needed; do not block on hypothetical approvals.
   - The shared "MCP read-only" rule still applies if the brief lists MCP servers, though most release-handoff runs do not use MCP.
 - Pre-handoff entry gate (mandatory — refuse to start if any item fails):
-  - **whole-task mode**: the task brief MUST cite the originating `final-verification` final-report path under `## Source Verification Report`; the lead confirms its `Verdict Token` is exactly `accepted` and its `verificationScope` is `whole-task`.
-  - **stage-group mode**: the brief cites N single-stage `final-verification` reports (one per candidate stage); the lead confirms each `Verdict Token` is `accepted`. Eligibility is re-enforced by `okstra handoff` — the lead never hand-computes it.
+  - the run's input document (`release-handoff-input.md`, generated by prepare in place of a task brief — briefs belong to entry phases only) carries a `## Source Verification Report` section with `Mode`, `Stages`, and one table row per cited `final-verification` final-report. The run context exposes the same selection as `HANDOFF_MODE` (`whole-task` | `stage-group`) and `HANDOFF_STAGES` (csv, empty for whole-task).
+  - **whole-task mode** (`HANDOFF_MODE=whole-task`): the lead opens the cited report and confirms its `Verdict Token` is exactly `accepted` and its `verificationScope` is `whole-task`.
+  - **stage-group mode** (`HANDOFF_MODE=stage-group`): the lead opens each cited single-stage report and confirms every `Verdict Token` is `accepted`. Eligibility was already enforced at prepare time (`okstra_ctl.handoff.compute_eligibility`) and is re-enforced by `okstra handoff assemble` — the lead never hand-computes it.
   - if the verdict is `conditional-accept`, `blocked`, or any other token (including ambiguous phrasing like "looks good"), the run MUST end immediately with status `blocked` and a routing recommendation back to `error-analysis` or `implementation-planning`. Do NOT prompt the user; Do NOT run any git command.
   - the lead MUST capture `git status --short` and confirm the working tree is clean. Dirty state aborts the run; release-handoff packages the commits produced by `implementation`, it does not stage or commit changes.
   - the lead MUST capture `git rev-parse --abbrev-ref HEAD` and record it as the **feature branch**. If the current branch is itself `main`, `master`, `prod`, `preprod`, `staging`, or `dev`, the run MUST end immediately — release-handoff never operates on a base branch.
@@ -23,11 +24,10 @@
      - `push + PR` — push the feature branch, then open or reuse a pull request.
      - `skip` — record the verified state and end the run without any git command.
      If the user picks `skip`, route directly to the final-report self-review pass.
-  - **stage-group mode order**: G1 base branch first (same options as Q2 — the dependency-closure check needs `origin/<base>`), then G2 stage selection, then assemble, then Q2b/Q3 as usual with the collector branch as the PR head.
-  1g. **G2 — stage selection**: run `okstra handoff eligible --plan-run-root <plan-run-root> --approved-plan <approved plan path>` and present the returned stages (eligible ones selectable, blocked ones listed with their `reasons`) as a multi-select. At least one stage must be selected.
+  - **stage-group mode order**: G1 base branch first (same options as Q2 — the dependency-closure check needs `origin/<base>`), then G2 stage confirmation, then assemble, then Q2b/Q3 as usual with the collector branch as the PR head.
+  1g. **G2 — stage confirmation**: the stage selection already happened before the run (wizard `handoff_stage_pick`, or the CLI `--stages` flag) and is fixed in `HANDOFF_STAGES`. Display it as a one-line confirmation (`PR 대상 stage: <csv> — 진행합니다`) and proceed; do NOT re-ask the multi-select. Only if `HANDOFF_MODE` is `stage-group` but `HANDOFF_STAGES` is empty (defensive, should not happen) run `okstra handoff eligible --plan-run-root <plan-run-root> --approved-plan <approved plan path>` and ask the user to pick from the eligible stages.
   2g. **assemble**: run `okstra handoff assemble --plan-run-root <...> --approved-plan <...> --project-root <project root> --project-id <id> --task-group <g> --task-id <t> --work-category <c> --stages <csv> --base <chosen-base>`. Exit 2 means a stage-vs-stage merge conflict: show the `conflicts` paths and stop (route: reshape the group or resolve manually). Exit 1 means an eligibility/closure violation: show the error verbatim and re-ask G2. On success the returned `branch` is the PR head branch for every subsequent step.
   2. **PR base branch** (only when the user picked `push + PR`) — present four options and capture exactly one:
-     - `staging`
      - `preprod`
      - `main`
      - `직접 입력` (free-form branch name; lead validates the name exists on origin via `git ls-remote --heads origin <name>` and re-asks on failure)

package/runtime/prompts/wizard/prompts.ko.json

@@ -123,8 +123,44 @@
       "label": "task brief markdown 의 경로를 알려주세요 (project root 기준 상대경로 또는 절대경로)",
       "echo_template": "brief: {value}"
     },
+    "handoff_stage_pick": {
+      "label": "PR 로 내보낼 범위를 선택하세요 (복수 선택 가능 — 검증 accepted + 미-PR stage 만 표시). 제외된 stage: {blocked}",
+      "echo_template": "handoff-scope: {value}",
+      "labels": {
+        "whole_task": "전체 task — whole-task 검증 기반 단일 PR (단독 선택)",
+        "stage": "stage {stage} (depends-on: {deps})",
+        "blocked_none": "없음"
+      },
+      "echo_variants": {
+        "whole_task": "handoff scope: 전체 task (whole-task 검증 기반)",
+        "stage_group": "handoff scope: stage-group ({stages})"
+      },
+      "errors": {
+        "no_plan": "release-handoff 는 이 task 의 implementation-planning final-report 가 필요합니다 — implementation-planning → implementation → final-verification 을 먼저 진행하세요.",
+        "plan_not_approved": "최신 plan 이 approved 상태가 아닙니다: {plan} — implementation 이 완료된 task 에서만 release-handoff 를 시작할 수 있습니다.",
+        "no_stage_map": "approved plan 에서 Stage Map 을 읽지 못했습니다: {plan}",
+        "nothing_eligible": "PR 로 내보낼 수 있는 범위가 없습니다 — 제외 사유: {blocked}. 단독-stage final-verification 의 accepted 기록(okstra handoff record-verified) 또는 whole-task 검증을 먼저 완료하세요.",
+        "none_selected": "최소 1개의 범위를 선택하세요",
+        "whole_task_exclusive": "'전체 task' 는 단독 선택만 가능합니다 — stage 묶음을 원하면 stage 번호들만 선택하세요",
+        "whole_task_missing": "accepted whole-task final-verification 보고서가 없습니다",
+        "not_eligible": "eligible 하지 않은 stage: {bad} (선택 가능: {eligible})"
+      }
+    },
+    "brief_carry": {
+      "label": "이 task 에 carry-in 할 brief 가 없습니다. {task_type} 는 entry phase 의 brief 를 이어받는 단계입니다 — 어떻게 진행할까요?",
+      "echo_template": "brief-carry: {value}",
+      "options": {
+        "__switch_entry__": "entry phase 로 전환 (추천) — requirements-discovery / error-analysis / improvement-discovery 부터 시작",
+        "__free_input__": "brief 경로 직접 입력",
+        "__abort__": "중단"
+      },
+      "echo_variants": {
+        "switch_entry": "brief-carry: entry phase 로 전환 — task-type 을 다시 선택합니다",
+        "abort": "brief-carry: 중단"
+      }
+    },
     "base_ref_pick": {
-      "label": "이 task worktree 의 base branch?",
+      "label": "이 task 의 base branch?",
       "echo_template": "base-ref: {value}",
       "options": {
         "_RECOMMENDED_SUFFIX": " (recommended)",
@@ -134,10 +170,13 @@
     "branch_confirm": {
       "label": "{summary}",
       "labels": {
-        "new": "새 브랜치 `{branch}` 를 base-ref `{base_ref}` 에서 새 worktree(`{path}`)에 생성합니다 — 진행할까요?",
-        "reuse": "현재 worktree(`{path}`, 브랜치 `{branch}`)를 재사용합니다 — 진행할까요?",
+        "new": "새 브랜치 `{branch}` 를 base-ref `{base_ref}` 에서 분기해 `{task_key}` 디렉터리(`{path}`)에 체크아웃합니다 — 진행할까요?",
+        "reuse": "기존 `{task_key}` 디렉터리(`{path}`, 브랜치 `{branch}`)에서 이어서 진행합니다 — 진행할까요?",
         "in_worktree": "현재 worktree(`{path}`)에서 그대로 진행합니다(이미 non-main worktree) — 진행할까요?",
-        "not_git": "git 저장소가 아니므로 `{path}` 에서 직접 진행합니다 — 진행할까요?"
+        "not_git": "git 저장소가 아니므로 `{path}` 에서 직접 진행합니다 — 진행할까요?",
+        "impl_stage_new": "implementation 은 stage 격리로 동작합니다 — stage {stage} worktree 를 `{path}` 에 브랜치 `{branch}` 로 새로 만들고, base 커밋은 의존 stage 의 done 커밋 기준으로 run 준비 시점에 해소됩니다 — 진행할까요?",
+        "impl_stage_reuse": "기존 stage {stage} worktree(`{path}`, 브랜치 `{branch}`)에서 이어서 진행합니다 — 진행할까요?",
+        "impl_stage_auto": "implementation 은 stage 격리로 동작합니다 — stage 번호는 run 준비 시점에 자동 선택되고, `{task_key}` 디렉터리(`{path}`) 아래 `stage-<N>/` worktree 가 새로 만들어지거나 재사용됩니다 — 진행할까요?"
       },
       "options": { "proceed": "진행", "edit": "base-ref 다시 고르기", "abort": "중단" },
       "echo_template": "branch-confirm: {value}"
@@ -371,6 +410,10 @@
   "confirmation": {
     "header": "선택 확인:",
     "workers_implementation_default": "  workers       : (프로필 기본 — executor + verifier 2 + report-writer)",
-    "stage_whole_task": "전체 task"
+    "base_ref_stage_isolated": "  base-ref      : (stage 격리 — 의존 stage 기준으로 run 준비 시점에 자동 해소)",
+    "base_ref_reuse_task_dir": "  base-ref      : (기존 `{task_key}` 디렉터리 재사용 — 최초 base 유지)",
+    "stage_whole_task": "전체 task",
+    "handoff_scope_whole_task": "전체 task (whole-task 검증 기반)",
+    "handoff_scope_stage_group": "stage-group ({stages})"
   }
 }

package/runtime/python/okstra_ctl/consumers.py

@@ -50,22 +50,52 @@ def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
     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,
-        }
-        _append_row(plan_run_root, record)
+        if not _equivalent_row_exists(plan_run_root, impl_task_key, stage,
+                                      status, force_reappend,
+                                      fields.get("head_commit")):
+            record: Dict[str, Any] = {
+                "impl_task_key": impl_task_key,
+                "stage": stage,
+                "status": status,
+                **fields,
+            }
+            _append_row(plan_run_root, record)
+    # done 은 점유 해제 이벤트이기도 하다 — 중복 append(no-op)에서도 풀어야
+    # release 없이 done 만 기록된 과거 run 의 잔존 점유가 다음 호출에서 치유된다.
+    if status == "done":
+        _release_stage_reservation(impl_task_key, stage)
+
+
+def _equivalent_row_exists(plan_run_root: Path, impl_task_key: str, stage: int,
+                           status: str, force_reappend: bool,
+                           head_commit: Any) -> bool:
+    for row in read_consumers(plan_run_root):
+        if (row.get("impl_task_key") == impl_task_key
+                and row.get("stage") == stage
+                and row.get("status") == status):
+            if not force_reappend:
+                return True
+            if row.get("head_commit") == head_commit:
+                return True  # 동일 보정의 중복 재-append 방지
+    return False
+
+
+def _release_stage_reservation(impl_task_key: str, stage: Any) -> None:
+    """done 이 기록된 stage 의 worktree-registry 점유(stage-key)를 해제한다.
+
+    release 는 점유 표시만 푼다 — worktree 디렉토리·브랜치는 보존된다.
+    registry 좌표는 TASK_KEY(`project:group:task`) 각 segment 의
+    safe-segment 와 같다(stage 예약이 그렇게 만들어진다). 형식이 다르면
+    점유 주체가 아니므로 건너뛴다."""
+    parts = impl_task_key.split(":")
+    if len(parts) != 3 or not isinstance(stage, int):
+        return
+    from .ids import _safe_fs_segment
+    from . import worktree_registry
+    worktree_registry.release(
+        _safe_fs_segment(parts[0]), _safe_fs_segment(parts[1]),
+        _safe_fs_segment(parts[2]), stage_number=stage,
+    )
 
 
 def _append_row(plan_run_root: Path, record: Dict[str, Any]) -> None:

package/runtime/python/okstra_ctl/handoff.py

@@ -62,6 +62,35 @@ def compute_eligibility(stage_map: List[Dict[str, Any]],
     return out
 
 
+def latest_whole_task_fv_accepted(project_root, project_id: str,
+                                  task_group: str, task_id: str) -> str:
+    """accepted whole-task final-verification 보고서 경로. 없으면 ''.
+
+    판정의 SSOT 는 final-report 의 data.json 이다 (record_verified 와 동일
+    필드: header.taskType / verificationScope / finalVerdict.verdictToken).
+    whole-task run 산출물만 평면 reports/ 에 남으므로 stage-* 는 걸리지 않는다."""
+    from okstra_project.state import find_task_root
+    root = find_task_root(Path(project_root),
+                          f"{project_id}:{task_group}:{task_id}")
+    if root is None:
+        return ""
+    reports_dir = root / "runs" / "final-verification" / "reports"
+    for dj in sorted(reports_dir.glob("final-report-*.data.json"),
+                     reverse=True):
+        try:
+            data = json.loads(dj.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        token = ((data.get("finalVerdict") or {}).get("verdictToken")
+                 or "").strip().lower()
+        if ((data.get("header") or {}).get("taskType") == "final-verification"
+                and data.get("verificationScope") == "whole-task"
+                and token == "accepted"):
+            md = dj.with_name(dj.name[:-len(".data.json")] + ".md")
+            return str(md if md.is_file() else dj)
+    return ""
+
+
 def check_dependency_closure(
     selected: List[int],
     stage_map: List[Dict[str, Any]],