okstra 0.98.0 → 0.98.2

package/docs/for-ai/skills/okstra-inspect.md

@@ -0,0 +1,260 @@
+# okstra-inspect AI Manual
+
+## 원천
+
+- 스킬 원문: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
+- CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
+- context-cost CLI: `src/commands/inspect/context-cost.mjs`
+- time-report CLI: `src/commands/inspect/time-report.mjs`
+- log-report CLI: `src/commands/inspect/log-report.mjs`
+- error-report CLI: `src/commands/inspect/error-report.mjs`
+- container는 별도 스킬: [`okstra-container.md`](okstra-container.md)
+
+## 목적
+
+`okstra-inspect`는 okstra read-side 작업의 단일 진입점이다. 대부분은 읽기 전용이지만 두 예외가 있다.
+
+- `status.4`: 사용자가 요청한 `workStatus`를 `task-manifest.json`에 기록한다.
+- `errors`, `error-zip`, `recap record`: 읽은 정보를 바탕으로 report/zip/log 산출물을 만든다.
+
+## sub-command 목록
+
+| Sub-command | 역할 | 쓰기 여부 |
+|---|---|---|
+| `status` | task/phase/workflow 상태 확인, workStatus 변경 | `status.4`에서 manifest 수정 |
+| `history` | 과거 run 목록, rerun/resume command 조립 | 기본 읽기 |
+| `report` | final-report 경로 해석 및 선택적 읽기 | 읽기 |
+| `time` | task type/worker별 소요 시간 집계 | 읽기 |
+| `logs` | wrapper `.log` sidecar inventory와 cleanup command 제안 | 읽기 |
+| `cost` | task bundle context/read cost 추정 | 읽기 |
+| `errors` | task error logs를 timestamped markdown report로 집계 | report 생성 |
+| `error-zip` | cross-project error logs 익명화 zip 생성 | zip 생성 |
+| `recap` | task run 전후 요약과 Q&A 기록 | `recap-log.jsonl` append |
+
+## Preflight
+
+모든 sub-command 전에 한 번만 실행한다.
+
+```bash
+okstra ensure-installed --runtime claude-code
+okstra check-project --json
+```
+
+runtime이나 project setup이 없으면 `/okstra-setup` 안내 후 멈춘다. 이후 `projectRoot`를 literal 값으로 사용한다.
+
+## intent routing
+
+사용자 요청을 하나 이상의 facet으로 분류한다. 애매하면 sub-command 표 전체를 보여주고 번호/이름으로 선택하게 한다. AskUserQuestion option 제한 때문에 facet을 숨기지 않는다.
+
+여러 facet이 한 메시지에 있으면 순차 실행한다. Step 0은 한 번만 실행한다.
+
+## task-key 해석 공통 규칙
+
+많은 facet은 다음 target 형식을 받는다.
+
+1. full task-key: `<project-id>:<task-group>:<task-id>`
+2. bare task-id
+3. task root path
+
+bare task-id는 shared resolver를 사용한다.
+
+```bash
+okstra resolve-task-key <task-id> --project-root <projectRoot> --json
+```
+
+`matches[]` 처리:
+
+- 0개: 찾을 수 없다고 말하고 추측하지 않는다.
+- 1개: 해당 `taskKey` 사용.
+- N개: 후보 `taskKey`와 `updatedAt`를 보여주고 disambiguation을 받는다.
+
+## status
+
+### Project overview
+
+`.okstra/discovery/task-catalog.json`을 읽는다. overview에서는 개별 manifest를 다시 열지 않는다. catalog가 projected source다.
+
+정렬: `updatedAt` desc, `taskKey`.
+
+표는 좁게 유지한다.
+
+- Task Key
+- Category
+- Phase
+- workStatus
+- Next
+
+`awaitingApproval` 또는 `routingStatus == "pending"`이면 Next cell에 marker를 붙이고 설명한다.
+
+### Specific task
+
+task 하나의 detail은 catalog를 먼저 보고, 필요하면 `.okstra/tasks/<group>/<id>/task-manifest.json`, `history/timeline.json`, latest run manifest를 읽는다.
+
+보여줄 정보:
+
+- work category
+- current phase/state
+- last completed phase
+- next recommended phase
+- awaiting approval
+- routing status
+- task status, latest run status
+- latest report, resume command
+- workStatus, note
+- phase states
+- safe resume checkpoint
+
+### workStatus update
+
+사용자가 명시적으로 상태 변경을 요청할 때만 쓴다.
+
+허용값:
+
+- `todo`
+- `in-progress`
+- `blocked`
+- `done`
+
+절차:
+
+1. status 값 검증.
+2. `okstra resolve-task-key ... --json`으로 task 해석.
+3. catalog entry의 `taskManifestPath` 또는 `taskGroupPathSegment`/`taskIdPathSegment`로 manifest path를 만든다.
+4. `task-manifest.json` root의 `workStatus`, `workStatusUpdatedAt`, 선택적 `workStatusNote`만 targeted edit한다.
+5. JSON 전체를 parse/stringify로 round-trip하지 않는다. key order, indentation, trailing newline을 보존한다.
+
+읽기 표시에서 `workStatus`가 없으면 lifecycle state로 추론하되, 읽기만으로 back-fill하지 않는다.
+
+## history
+
+첫 분기: re-run과 resume을 구분한다.
+
+- Re-run: 이전 run parameters로 새 run을 만든다. 새 run-seq가 생긴다.
+- Resume: 중단된 기존 run을 이어간다. 새 run-seq를 만들지 않는다.
+
+catalog가 없으면 `.okstra/tasks/*/*/task-manifest.json` glob으로 fallback한다. disk manifest가 source of truth다.
+
+Re-run은 source run-manifest에서 `projectId`, `taskGroup`, `taskId`, `taskType`, `taskBriefPath`, workers, relatedTasks, model overrides 등을 뽑아 command를 조립한다. `implementation`의 `--base-ref`는 run-manifest에 없고 worktree registry에 있으므로 상황에 따라 묻는다.
+
+Resume은 `latestResumeCommandPath` 또는 timeline entry의 `resumeCommandPath`를 확인하고 파일이 있으면 `bash <resume-command-path>`를 안내/실행한다.
+
+## report
+
+report path 해석 우선순위:
+
+1. `.okstra/discovery/task-catalog.json`의 `latestReportPath`
+2. direct `task-manifest.json`의 `latestReportPath`
+3. `history/timeline.json`의 특정 run `reportPath`
+4. 특정 task-type fallback: `runs/<task-type>/reports/final-report-*.md`, stage-isolated path 포함
+
+report file 존재를 확인한 뒤, 읽을지 사용자에게 묻는다. 완료 signal은 있는데 file이 없으면 missing report로 말한다. 아직 완료되지 않았으면 current status와 workStatus를 보여준다.
+
+## time
+
+시간 계산은 CLI가 한다. AI가 duration을 직접 recompute하지 않는다.
+
+```bash
+okstra time-report <task-key> --project-root <projectRoot> --json
+```
+
+모든 `*Ms`는 `HH:MM:SS`로 변환해 보여준다. `CPU sum`은 lead와 workers 시간을 합친 overlapping cost이며 wall-clock이 아니다. 사용자가 wall-clock/phase breakdown을 물을 때만 `perRunWallClock`, `phaseTimelines`를 보여준다.
+
+`unavailable[]`은 totals에 합치지 않고 별도 note로 표시한다.
+
+## cost
+
+context/read cost는 CLI output이 source of truth다.
+
+```bash
+okstra context-cost <task-key> --project-root <projectRoot>
+```
+
+해석 포인트:
+
+- token estimate는 heuristic이지 billing 수치가 아니다.
+- `leadPhase1.mode == "active-run-context"`면 compact lead intake가 primary다.
+- `analysisWorker.mode == "analysis-packet-primary"`면 worker는 analysis-packet을 먼저 읽고 필요할 때 full source를 연다.
+- `skillAssets`가 크면 prompt diet 대상이다.
+- legacy timestamp artifacts가 많으면 destructive delete가 아니라 current-view/cold-artifact 분리를 제안한다.
+
+## logs
+
+wrapper sidecar log inventory:
+
+```bash
+okstra log-report --project-root <projectRoot> --json
+```
+
+`.okstra/tasks/**/runs/*/prompts/*.log`를 스캔한다. 삭제하지 않는다. cleanup command는 dry-run과 `-delete` pair를 fenced bash로 제시할 뿐이다.
+
+active run의 log를 지우면 live trace를 잃으므로 먼저 `status` 확인을 권한다.
+
+## errors
+
+task error logs를 markdown report로 집계한다.
+
+```bash
+okstra error-report <task-key> --project-root <projectRoot>
+```
+
+stdout JSON에서 `reportPath`, totals, byPhase, byAgent, parseSkipped를 읽어 요약한다. `reportPath`가 없고 errorCount가 0이면 기록된 error log가 없다고 말한다. `parseSkipped > 0`은 숨기지 않는다.
+
+## error-zip
+
+머신 내 cross-project okstra errors를 익명화 zip으로 묶는다.
+
+출력 경로는 `~/.okstra/error-zip.json`의 `lastOutputPath`를 우선 추천하고, 없으면 `~/okstra-error-feedback-<YYYY-MM-DD>.zip`을 제안한다.
+
+실행:
+
+```bash
+okstra error-zip --out <path>
+```
+
+요약 필드:
+
+- `outPath`
+- `errorCount`
+- `runCount`
+- `unreachableRuns`
+- `clusterCount`
+- `projectCount`
+
+마지막에 `/okstra-brief`의 error-feedback variant로 brief를 만든 뒤 okstra repo에서 `error-analysis`를 실행하라고 안내한다.
+
+## recap
+
+기본은 artifact mode다. `.okstra/` 산출물만 근거로 전후 요약과 질문 답변을 만든다.
+
+assemble:
+
+```bash
+okstra recap assemble <task-key> --project-root <projectRoot>
+```
+
+record:
+
+```bash
+okstra recap record <task-key> --project-root <projectRoot> --kind <summary|qa> --mode <artifact|code> --question "<question>" --answer "<summary>" --citation "<path:line>"
+```
+
+code mode는 사용자가 "diff까지", "코드 변경까지"처럼 명시적으로 요청할 때만 진입한다. recap 진입만으로 code diff를 읽지 않는다.
+
+## 출력 규칙
+
+- 한국어로 간결히 답한다.
+- project-relative path를 우선 표시한다.
+- disk field 값은 normalize하지 않고 그대로 보여준다.
+- approval 대기 상태는 명확히 표시한다.
+- 최신 report가 없으면 `--`로 표시한다.
+- 날짜는 `YYYY-MM-DD HH:MM`로 표시한다.
+
+## 금지 패턴
+
+- catalog가 없다고 바로 실패하기. manifest fallback이 있다.
+- `workStatus`와 `currentStatus`를 혼동하기.
+- time duration을 CLI 없이 손계산하기.
+- cleanup command를 직접 실행하기.
+- `errors`/`cost`/`time`에서 CLI output 대신 raw files를 임의로 재해석하기.
+- recap artifact mode에서 코드 변경까지 자동으로 읽기.
+

package/docs/for-ai/skills/okstra-memory.md

@@ -0,0 +1,127 @@
+# okstra-memory AI Manual
+
+## 원천
+
+- 스킬 원문: [`skills/okstra-memory/SKILL.md`](../../../skills/okstra-memory/SKILL.md)
+- CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
+- memory CLI: [`src/commands/memory/memory.mjs`](../../../src/commands/memory/memory.mjs)
+
+## 목적
+
+`okstra-memory`는 사용자 홈의 Memory Book을 관리한다.
+
+```text
+~/.okstra/memory-book/
+```
+
+프로젝트 local `.okstra/` artifact가 아니다. `<PROJECT_ROOT>/.okstra/project.json`이 없어도 사용할 수 있다.
+
+## 사용 조건
+
+사용한다:
+
+- 사용자가 "기억해둬", "대화 저장", "okstra에 정리해서 보관", "remember this", "save this decision"처럼 명시적으로 저장을 요청한다.
+- 저장된 memory를 검색, 목록화, 읽기, archive하려고 한다.
+
+사용하지 않는다:
+
+- 사용자가 단순 brainstorming 중이고 저장 요청이 없다. 이때는 확인 질문을 먼저 한다.
+- project task artifact로 남겨야 하는 내용. 이 경우 해당 okstra task의 brief/report/decision 경로를 사용한다.
+
+## safety rule
+
+명시적 저장 요청 없이 저장하지 않는다. credentials, API keys, tokens, private personal data, secrets는 저장하지 않는다. 대화에 민감한 내용이 있으면 summary에서 제외하고 omission을 기록한다.
+
+CLI도 high-confidence secret shape를 감지해 `memory add`를 거부할 수 있다. 거부되면 내용을 redact하고 재시도한다.
+
+## CLI availability
+
+먼저 help를 확인한다.
+
+```bash
+okstra memory --help
+```
+
+`okstra`가 PATH에 없으면 `npx okstra@latest install`을 직접 실행하지 말고, 한 번 설치 후 재시도하라고 안내한다.
+
+## project-group 선택
+
+모든 memory entry는 project-group에 속한다. 저장/검색 전에 group을 먼저 고른다.
+
+기존 group 조회:
+
+```bash
+okstra memory groups --json
+```
+
+추천:
+
+- 가장 많이 쓰인 existing group
+- 두 번째 existing group
+- 직접 입력
+
+개인 메모리는 `private`를 우선 추천한다. group이 없거나 선택이 없으면 CLI default인 `global`을 쓴다.
+
+선택 group은 `add`, `search`, `list`에 `--project-group <group>`으로 전달한다. 사용자가 cross-group search를 명시한 경우에만 flag를 생략한다.
+
+## 저장 절차
+
+대화 전체 transcript를 저장하지 않는다. 오래 남길 durable memory만 추출해 concise Markdown summary로 만든다.
+
+포함할 것:
+
+- 저장 이유
+- source: `conversation`
+- 관련 project id가 명확하면 `--project`
+- 검색용 tags
+- memory type
+
+type 값은 `okstra memory --help` 출력이 권위다. 원문 기준 category:
+
+- `decision`
+- `preference`
+- `requirement`
+- `person`
+- `project-hint`
+- `follow-up`
+- `context`
+
+저장 명령 형태:
+
+```bash
+okstra memory add --content "<summary markdown>" --title "<short title>" --type <type> --project-group <group> --tag <tag> --project <id> --source conversation --yes
+```
+
+필요하면 `--tag`, `--project`를 반복한다. 관련 project가 명확하지 않으면 `--project`를 생략한다.
+
+`--yes`는 사용자가 저장을 명시했을 때만 사용한다.
+
+## 검색/읽기/archive
+
+기본은 선택한 project-group scope다.
+
+```bash
+okstra memory search "<query>" --project-group "<group>"
+okstra memory list --project-group "<group>" --tag "<tag>"
+okstra memory groups
+okstra memory show "<memory-id>"
+okstra memory archive "<memory-id>"
+```
+
+ID parsing이 필요하면 `--json`을 선호한다. 사용자에게는 짧은 요약과 entry id/path 정도만 보여준다.
+
+## 출력 규칙
+
+- 저장 시 title, type, project-group, tags, generated id를 요약한다.
+- 검색 시 match count와 가장 관련 높은 entry를 먼저 보여준다.
+- archive는 사용자 의도가 명확할 때만 실행한다.
+- project `.okstra/`에 쓰지 않는다.
+
+## 금지 패턴
+
+- 명시 요청 없이 자동 저장.
+- secret/token/key를 저장.
+- full transcript를 그대로 저장.
+- project-local task memory처럼 `.okstra/`에 쓰기.
+- cross-group search를 사용자가 요청하지 않았는데 기본으로 수행하기.
+

package/docs/for-ai/skills/okstra-run.md

@@ -0,0 +1,229 @@
+# okstra-run AI Manual
+
+## 원천
+
+- 스킬 원문: [`skills/okstra-run/SKILL.md`](../../../skills/okstra-run/SKILL.md)
+- wizard CLI wrapper: [`src/commands/execute/wizard.mjs`](../../../src/commands/execute/wizard.mjs)
+- wizard state machine: [`scripts/okstra_ctl/wizard.py`](../../../scripts/okstra_ctl/wizard.py)
+- render-bundle CLI: [`src/commands/execute/render-bundle.mjs`](../../../src/commands/execute/render-bundle.mjs)
+- prepare entrypoint: [`scripts/okstra_ctl/run.py`](../../../scripts/okstra_ctl/run.py)
+
+## 목적
+
+`okstra-run`은 현재 Claude Code 세션 안에서 okstra task run을 시작한다. 입력 수집은 `okstra wizard` state machine이 전담하고, 스킬은 wizard prompt를 사용자에게 relay한 뒤 `okstra render-bundle`로 task bundle을 준비한다. bundle이 준비되면 현재 세션이 Claude lead로 전환된다.
+
+단일 권위:
+
+- 질문 순서, 분기, validation: `scripts/okstra_ctl/wizard.py`
+- task bundle materialization: `prepare_task_bundle()`
+- 스킬 문서: thin prompt-relay loop
+
+## 사용 조건
+
+사용한다:
+
+- 사용자가 현재 세션에서 okstra task를 시작하려고 한다.
+- 기존 task의 다음 phase를 이어서 실행하려고 한다.
+- "okstra run", "okstra start", "이 세션에서 okstra 시작", "다음 단계 실행" 등.
+
+사용하지 않는다:
+
+- 상태만 보려는 경우: `okstra-inspect status`
+- 과거 run이나 resume command를 보려는 경우: `okstra-inspect history`
+- 사용자가 새 terminal/new claude process를 명시한 경우: inspect history/resume 안내
+
+## Preflight
+
+각각 별도 Bash 호출:
+
+```bash
+okstra ensure-installed --runtime claude-code
+okstra paths --json
+okstra check-project --json
+```
+
+`paths --json`은 diagnostic context로만 읽는다. `export PYTHONPATH`를 만들지 않는다. runtime이나 project setup이 없으면 `/okstra-setup`을 안내하고 멈춘다.
+
+## Bash 호출 규칙
+
+모든 okstra 호출은 literal token `okstra`로 시작한다. `--state-file`, `--answer`, path, model, worker 값은 이전 JSON/tool output에서 읽어 literal string으로 붙인다.
+
+피해야 한다:
+
+- `$STATE_FILE`, `$ANSWER`
+- `$(...)`
+- `VAR=... okstra ...`
+- `eval`, `export`
+- `okstra ... && okstra ...`
+
+empty answer도 flag를 생략하지 않는다.
+
+```bash
+okstra wizard step --state-file /tmp/okstra-wizard/state.json --answer ""
+```
+
+## wizard 초기화
+
+state file 생성:
+
+```bash
+okstra wizard new-state-file
+```
+
+출력 absolute path를 그대로 들고 간다.
+
+wizard init:
+
+```bash
+okstra wizard init --state-file /tmp/okstra-wizard/state.json --project-root /abs/project --project-id project-id
+```
+
+결과는 `{ok, next}` JSON이다. 첫 step은 `task_pick`이다.
+
+## wizard JSON 해석
+
+`next.kind`에 따라 UI를 고른다.
+
+| kind | 처리 |
+|---|---|
+| `pick`, `multi: false` | 모든 `options[]`를 그대로 selectable choice로 렌더. 선택 option의 `value` 제출 |
+| `pick`, `multi: true` | 모든 선택 value를 comma-separated string으로 제출. 선택 없음도 `--answer ""` 제출 |
+| `pick_group` | wizard의 `questions[]`를 한 번의 multi-question UI로 렌더. step별 value를 JSON object로 만들어 한 번에 제출 |
+| `text` | picker를 쓰지 않고 plain text label을 보여준 뒤 다음 사용자 메시지를 verbatim 제출 |
+| `done` | 입력 수집 종료. render-args로 이동 |
+| `aborted` | state file을 지우고 중단. render-args/render-bundle 호출 금지 |
+
+`progress.label`은 wizard가 만든 문자열이다. UI prompt 뒤에 그대로 붙이고, 직접 계산하지 않는다.
+
+## wizard loop
+
+1. prompt 렌더.
+2. 사용자 답변을 literal `--answer`로 제출.
+3. `ok: true`: `result.echo`를 한 줄로 사용자에게 보여주고 다음 step.
+4. `ok: false`: `result.error`를 그대로 보여주고 `result.current`로 같은 step 재시도.
+5. `current: null`: prompt를 재구성할 수 없는 terminal 오류다. 에러를 보여주고 멈춘다.
+
+중요: wizard가 제공한 option을 줄이거나 숨기거나 "추천 + 직접 입력"으로 재구성하지 않는다. wizard의 `options[]`가 완전한 선택지다.
+
+## confirm step
+
+`next.step == "confirm"`이면 먼저 confirmation summary를 가져온다.
+
+```bash
+okstra wizard confirmation --state-file /tmp/okstra-wizard/state.json
+```
+
+`text`를 사용자에게 보여준 뒤 Proceed/Edit/중단 picker를 렌더한다. `Edit`은 wizard가 이전 step으로 rewind한다.
+
+## render-args와 render-bundle
+
+`next.kind == "done"`이면:
+
+```bash
+okstra wizard render-args --state-file /tmp/okstra-wizard/state.json
+```
+
+`args` object의 모든 key를 `okstra render-bundle` flag로 전달한다. 빈 string 값도 명시적으로 전달한다.
+
+```bash
+okstra render-bundle \
+  --lead-runtime claude-code \
+  --project-root "<args.project-root>" \
+  --project-id "<args.project-id>" \
+  --task-group "<args.task-group>" \
+  --task-id "<args.task-id>" \
+  --task-type "<args.task-type>" \
+  --task-brief "<args.task-brief>" \
+  --executor "<args.executor>" \
+  --critic "<args.critic>" \
+  --approved-plan "<args.approved-plan>" \
+  --stage "<args.stage>" \
+  --stages "<args.stages>" \
+  --base-ref "<args.base-ref>" \
+  --workers "<args.workers>" \
+  --directive "<args.directive>" \
+  --lead-model "<args.lead-model>" \
+  --claude-model "<args.claude-model>" \
+  --codex-model "<args.codex-model>" \
+  --antigravity-model "<args.antigravity-model>" \
+  --report-writer-model "<args.report-writer-model>" \
+  --related-tasks "<args.related-tasks>" \
+  --clarification-response "<args.clarification-response>" \
+  --pr-template-path "<args.pr-template-path>" \
+  --fix-cycle "<args.fix-cycle>"
+```
+
+stdout에서 다음 labeled line을 파싱한다.
+
+- `okstra task root:`
+- `okstra instruction-set:`
+- 선택적으로 `okstra concurrent-run stages:`
+
+render-bundle은 `prepare_task_bundle()`을 render-only로 호출해 manifests, run context, instruction set, discovery files를 준비하고 `~/.okstra/recent.jsonl`에 `prepared`로 등록한다.
+
+## conformance waiver
+
+implementation에서 Tier 3 conformance가 환경상 불가능할 때만 사용자에게 waiver를 제안한다. waiver는 사용자 승인과 verbatim reason이 있어야 한다. AI lead나 worker가 자체 면제를 만들지 않는다.
+
+선택 시 `render-bundle`에만 추가한다.
+
+```bash
+--qa-waiver "<stageKey>:<reason>"
+```
+
+값이 없으면 flag 자체를 생략한다.
+
+## concurrent-run 분기
+
+`render-bundle` stdout에 `okstra concurrent-run stages:`가 있으면 이미 no-team background gate가 prompt에 반영된 상태다.
+
+사용자에게 세 선택지를 준다.
+
+1. no-team background로 진행.
+2. 대기. prepared artifacts는 보존된다.
+3. 직접 입력.
+
+이 picker는 스킬이 만드는 것이므로 wizard option 축약 금지 규칙과 별개다.
+
+## stale git SHA recovery
+
+`Recorded stage SHAs no longer match the git history`류 `PrepareError`가 나오면 registry/consumers를 수동 수정하지 않는다.
+
+1. 에러 메시지에 나온 `okstra git-reconcile ... --check --json`을 그대로 실행한다.
+2. confirm 항목마다 사용자에게 current branch tip, 다른 ref, 중단을 묻는다.
+3. 선택 ref로 `okstra git-reconcile ... --apply --stage <N> --use-ref <ref>`를 실행한다.
+4. 실패했던 render-bundle을 같은 인자로 재시도한다.
+
+anchor가 unresolvable이면 `--reset-anchor <ref>`는 사용자 확인 후 실행한다.
+
+## PR template persistence
+
+release-handoff에서 `pr-template-path`와 scope가 있으면 render-bundle 전에 config를 저장한다.
+
+```bash
+okstra config set pr-template-path "<path>" --scope project
+okstra config set pr-template-path "<path>" --scope global
+```
+
+scope는 wizard state file의 `pr_template_scope`에 있다. 현재 별도 subcommand가 없으므로 raw state file을 Read tool로 읽는다. shell로 `jq`나 `python3 -c`를 호출하지 않는다.
+
+## Claude lead 전환
+
+render-bundle 후 `<INSTRUCTION_SET_PATH>/claude-execution-prompt.md`를 verbatim으로 읽고, 그 prompt 순서대로 Phase 1부터 진행한다.
+
+사용자에게 한 줄로 알린다.
+
+```text
+Took over as Claude lead for `<taskKey>` (`<task-type>`). Run dir: `<RUN_DIR_RELATIVE_PATH>`. Beginning Phase 1 (context loading).
+```
+
+## 금지 패턴
+
+- wizard가 내준 질문 순서를 바꾸기.
+- wizard option을 숨기거나 추천만 남기기.
+- `text` prompt를 picker로 바꾸기.
+- empty answer에서 `--answer` flag를 생략하기.
+- `okstra.sh`를 호출해 wizard/render-bundle 경로를 우회하기.
+- render-bundle 전에 사용자가 abort한 state로 render-args를 호출하기.
+- Claude lead prompt를 읽기 전에 phase 작업을 임의로 시작하기.
+