okstra 0.102.1 → 0.102.3

package/docs/superpowers/specs/2026-06-12-codex-lead-adapter-design.md

@@ -1,358 +0,0 @@
-# Claude Code / Codex lead adapter split design
-
-- 날짜: 2026-06-12
-- 상태: 설계 초안
-- 대상: okstra runtime, installed skills, lead orchestration contract
-
-## 1. 배경
-
-okstra 의 core runtime 은 이미 비교적 플랫폼 중립적이다.
-`prepare_task_bundle()` 이 task bundle, manifests, prompts, worktree,
-validators 를 생성하고, Node CLI 는 이 Python core 를 호출한다.
-
-문제는 lead 실행 계층이 Claude Code 전용 계약을 강하게 전제한다는 점이다.
-
-- skills 는 `~/.claude/skills/` 에 설치된다.
-- worker agents 는 `~/.claude/agents/` 에 설치된다.
-- in-session run 은 `AskUserQuestion` 과 Claude Code slash skill 흐름을 전제한다.
-- team execution 은 `TeamCreate` / `Agent(...)` / `team_name` 을 전제한다.
-- resume, token usage, team reconcile 은 Claude session jsonl 과
-  `~/.claude/projects`, `~/.claude/teams` 를 읽는다.
-
-따라서 Codex 에서 같은 저장소를 사용하려면 프로젝트를 통째로 둘로 복사하는 대신
-**lead adapter** 를 나눠야 한다.
-
-## 2. 결정
-
-okstra 는 하나의 공통 core 와 두 lead adapter 로 분리한다.
-
-```text
-okstra core
-  - prepare_task_bundle
-  - task/run manifests
-  - worktree registry
-  - final-report schema/render/validators
-  - wizard state machine
-  - worker result / convergence schemas
-
-lead adapters
-  - claude-code adapter
-  - codex adapter
-```
-
-Claude Code adapter 는 현재 동작을 유지한다. Codex adapter 는 Claude Teams 를
-흉내내지 않고 Codex 가 제공하는 방식으로 같은 artifact contract 를 채운다.
-
-## 3. 비목표
-
-- `prepare_task_bundle()` 를 Claude/Codex 별로 복제하지 않는다.
-- phase profile, schema, validator 를 provider 별로 fork 하지 않는다.
-- Codex adapter 가 Claude Code 의 `TeamCreate` 나 `Agent(...)` 를 동일하게
-  재현한다고 주장하지 않는다.
-- 기존 Claude Code slash skill UX 를 깨지 않는다.
-
-## 4. Adapter 경계
-
-### 4.1 공통 core 로 남길 것
-
-| 영역 | 이유 |
-|---|---|
-| `scripts/okstra_ctl/run.py::prepare_task_bundle` | task identity 와 artifact layout 의 single authority |
-| `scripts/okstra_ctl/worktree*.py` | provider 와 무관한 격리/동시성 계약 |
-| `scripts/okstra_ctl/workers.py` | phase profile 이 허용하는 logical roster 검증 |
-| `scripts/okstra_ctl/render*.py` | manifests, prompts, final report rendering |
-| `schemas/`, `validators/`, `templates/` | output contract 의 SSOT |
-| `prompts/profiles/*.md` | lifecycle phase 규칙의 SSOT |
-
-### 4.2 Claude Code adapter 로 남길 것
-
-| 영역 | 현재 결합 |
-|---|---|
-| installed skills | `~/.claude/skills/okstra-*` |
-| installed agents | `~/.claude/agents/*-worker.md` |
-| interactive UI | `AskUserQuestion` |
-| worker dispatch | `TeamCreate`, `Agent(...)`, `team_name` |
-| resume | `claude --resume <session-id>` |
-| session accounting | Claude session jsonl, `~/.claude/projects` |
-| team cleanup | `~/.claude/teams`, `TeamDelete` |
-
-### 4.3 Codex adapter 로 새로 둘 것
-
-Codex adapter 는 다음을 담당한다.
-
-| 책임 | Codex 방식 |
-|---|---|
-| input collection | CLI wizard JSON 을 Codex 대화/질문으로 relay |
-| task bundle prepare | 기존 `okstra render-bundle` / `prepare_task_bundle()` 호출 |
-| lead progress logging | `PROGRESS:` line 을 assistant text + run artifact 에 기록 |
-| worker fan-out | Codex sub-agent tool, or CLI wrapper process, or sequential fallback |
-| worker result persistence | 기존 `worker-results/*.md` contract 에 맞춰 파일 작성 |
-| convergence | 기존 `okstra-convergence` 알고리즘을 lead-local 로 실행 |
-| report writing | report-writer worker 가 없으면 explicit fallback status 를 기록한 뒤 lead-authored path 사용, 또는 Codex 전용 report-writer role 을 정의 |
-| resume | Codex session resume 가 아니라 run artifact checkpoint 기준 재진입 |
-
-## 5. Execution modes
-
-### 5.1 `leadRuntime=claude-code`
-
-현재 기본값이다.
-
-- 설치: `okstra install` 이 `~/.claude/skills` 와 `~/.claude/agents` 를 채운다.
-- 실행: slash skill 또는 `okstra.sh` 가 Claude lead 를 시작한다.
-- worker dispatch: `TeamCreate` / `Agent(...)`.
-- validator: 기존 session conformance 를 그대로 적용한다.
-
-### 5.2 `leadRuntime=codex`
-
-신규 모드다.
-
-- 설치: Claude assets 는 선택 설치로 바꾸고, Codex adapter assets 를 별도 설치한다.
-- 실행: `okstra codex-run` 또는 `okstra run --lead-runtime codex`.
-- worker dispatch:
-  - 가능한 경우 Codex sub-agent fan-out 사용.
-  - 불가능하면 CLI wrapper 또는 sequential local analysis 로 degrade.
-- team-state 는 Claude team fields 대신 `leadRuntime: "codex"` 와
-  `dispatchMode` 를 명시한다.
-- validator 는 `leadRuntime` 별 conformance rule 을 고른다.
-
-## 6. Contract changes
-
-### 6.1 manifest
-
-`task-manifest.json` 또는 run manifest 에 다음 필드를 추가한다.
-
-```json
-{
-  "leadRuntime": "claude-code",
-  "leadAdapter": {
-    "name": "claude-code",
-    "dispatchMode": "team",
-    "sessionAccounting": "claude-jsonl"
-  }
-}
-```
-
-Codex run 예:
-
-```json
-{
-  "leadRuntime": "codex",
-  "leadAdapter": {
-    "name": "codex",
-    "dispatchMode": "codex-subagents",
-    "sessionAccounting": "artifact-only"
-  }
-}
-```
-
-### 6.2 validator
-
-`validate_session_conformance.py` 는 현재 Claude session jsonl 을 검사한다.
-이를 다음처럼 분기한다.
-
-| runtime | conformance source |
-|---|---|
-| `claude-code` | existing Claude session jsonl scan |
-| `codex` | run artifact event log scan |
-
-Codex adapter 는 `runs/<task-type>/state/lead-events-<task-type>-<seq>.jsonl`
-에 진행 이벤트를 기록한다.
-
-Token/cost validation is runtime-aware. `claude-code` keeps the existing
-fail-close `okstra token-usage --substitute-data` requirement. `codex` does
-not run the Claude session-jsonl auto-recovery path. Codex runtime worker
-usage is collected from `lead-events-*.jsonl` dispatch windows matched against
-Codex rollout / Gemini session logs, so CLI-backed worker and report-writer
-cost can be summarized without Claude wrapper jsonls. Codex lead token
-accounting is still unavailable, and validator does not yet force
-final-report token substitution for Codex runs.
-
-### 6.3 report author
-
-기존 규칙은 "report-writer worker 가 roster 에 있으면 lead 가 직접 쓰지 않는다"이다.
-Codex adapter 에서도 이 원칙은 유지하되, report-writer role 의 구현을 runtime 별로 둔다.
-
-```text
-logical role: report-writer
-  claude-code implementation: Agent(subagent_type=report-writer-worker)
-  codex implementation: Codex report-writer subagent or explicit recorded fallback
-```
-
-## 7. Install layout
-
-현재 설치는 Claude Code 를 전제로 한다. 설치 command 를 runtime-aware 로 분리한다.
-
-```bash
-okstra install --runtime claude-code   # default, current behavior
-okstra install --runtime codex         # codex adapter assets only
-okstra install --runtime all           # both adapters
-```
-
-권장 내부 구조:
-
-```text
-adapters/
-  claude-code/
-    skills/
-    agents/
-    settings/
-  codex/
-    skills/
-    prompts/
-    adapter.md
-```
-
-단, 첫 구현에서는 물리 디렉터리 이동 없이 installer option 과 manifest field 만
-도입해도 된다. 대규모 파일 이동은 후속 cleanup 으로 둔다.
-
-## 8. 단계별 구현 계획
-
-### Stage 1 — runtime marker only
-
-- `--lead-runtime <claude-code|codex>` flag 를 `render-bundle` / `okstra.sh` /
-  `prepare_task_bundle()` 에 추가한다.
-- 기본값은 `claude-code`.
-- manifests 와 team-state 에 `leadRuntime` / `leadAdapter` 를 기록한다.
-- `codex` 는 dispatch adapter 가 생기기 전까지 `--render-only` 에서만 허용하고,
-  non-render prepare 는 명확히 fail 한다.
-
-### Stage 2 — Codex dry-run adapter
-
-- `okstra codex-run` 를 추가한다.
-- wrapper 가 `--render-only --lead-runtime codex` 를 소유하고, 사용자가 직접
-  중복 전달하면 거부한다.
-- wizard/render-bundle 로 task bundle 을 만들고, Codex lead prompt 를 출력한다.
-- worker dispatch 는 하지 않는다.
-- 목적: Codex 에서 task bundle intake, profile reading, phase boundary 를 안정화.
-
-### Stage 3 — Codex artifact event log
-
-- `lead-events-*.jsonl` writer/reader 를 추가한다.
-- `runs/<task-type>/state/lead-events-<task-type>-<seq>.jsonl` 를
-  team-state / run-manifest / task-manifest artifacts 에 노출한다.
-- Codex render-only adapter 는 우선 `bundle-prepared` event 를 기록한다.
-- validator 는 `leadRuntime=codex` 일 때 Claude session jsonl 대신 event log 를
-  읽고 `progress` / `artifact-read` 이벤트를 checkpoint / implementation
-  sidecar-read 증거로 사용한다.
-- 후속 dispatch 단계에서 `worker-dispatched`, `worker-result-collected` event 를
-  기록한다.
-
-### Stage 4 — Codex worker dispatch
-
-- logical worker role 을 유지하면서 Codex adapter 의 dispatch backend 를 붙인다.
-- backend 우선순위:
-  1. Codex sub-agent dispatch
-  2. CLI wrapper dispatch
-  3. sequential fallback with terminal status markers
-- 모든 backend 는 기존 `worker-results/*.md`, prompt history, errors sidecar 를
-  같은 path 에 써야 한다.
-- 첫 구현 범위(2026-06-12): `okstra codex-run` 으로 준비된 run manifest 를
-  입력으로 받는 `okstra codex-dispatch` 보조 명령을 추가한다.
-  - 지원 worker: 기존 CLI wrapper 계약이 있는 `codex`, `gemini`.
-  - `report-writer` 는 Stage 5 의 명시 opt-in 경로에서 지원한다.
-  - 미지원 worker: `--workers` 를 생략한 기본 dispatch 에서는 `claude` 같은
-    Codex-side 미지원 roster 항목을 건너뛴다. 사용자가 `--workers claude` 처럼
-    명시 요청하면 Codex-native 구현 전까지 즉시 unsupported 로 실패한다.
-  - 실행 방식: shell 없이 wrapper 를 `subprocess.run([...])` 으로 호출하고,
-    team-state worker status 와 `lead-events-*.jsonl` 의
-    `worker-dispatched` / `worker-result-collected` / `worker-failed` 이벤트를
-    갱신한다.
-  - prompt history 파일이 아직 없으면 run manifest / active-run-context 에서
-    자동 생성한다. 기존 prompt 파일은 덮어쓰지 않는다.
-  - dispatch plan 과 lead-events 는 worker 별 `backend` / `dispatchMode` 를
-    기록한다. 현재 값은 모두 `cli-wrapper` 이며, `_run_worker()` 는 backend router
-    로 분리되어 미지원 backend 를 wrapper 실행 전에 거부한다.
-  - 비범위: Claude TeamCreate 대체, final-report Phase 7 token substitution,
-    report-writer 후처리, token/session accounting. 이후 Stage 5 에서
-    report-writer 후처리가 추가됐고, Stage 5.5 에서 worker CLI token accounting
-    이 추가됐다.
-
-### Stage 5 — Codex report-writer
-
-- report-writer logical role 을 Codex sub-agent 로 구현한다.
-- 실패 시 기존 fallback 규칙처럼 dispatch attempt 와 terminal status 를 기록한다.
-- final-report data.json -> renderer -> views -> token/cost placeholder 처리 순서는
-  Claude adapter 와 동일하게 유지한다.
-- 첫 구현 범위(2026-06-12): `okstra codex-dispatch` 에 준비된
-  report-writer prompt 를 Codex wrapper 로 실행하는 opt-in 경로를 추가한다.
-  - 사용자는 `--workers report-writer --enable-codex-report-writer
-    --report-writer-codex-model <model>` 을 명시해야 한다.
-  - 이유: run manifest 의 report-writer model assignment 는 아직 Claude provider
-    기준(`REPORT_WRITER_MODEL_EXECUTION_VALUE`)으로 렌더되므로, Codex CLI 에
-    넘길 모델은 dispatch 단계에서 명시 override 해야 한다.
-  - dispatcher 는 prompt 의 `**Model:** Report writer worker, ...` header 를
-    override 값으로 갱신하고, wrapper 실행 성공 후 세 artifact 를 모두 확인한다:
-    `reports/final-report-*.data.json`, 렌더된 `reports/final-report-*.md`,
-    `worker-results/report-writer-worker-*.md` audit sidecar.
-  - artifact 확인 후 idempotent 한 후처리 네 개를 실행한다:
-    `okstra-token-usage.py --write --substitute-data` 로 token/cost 값을
-    data.json 과 markdown 에 치환하고,
-    `okstra-render-report-views.py` 로 HTML view 를 렌더하고,
-    `okstra-spawn-followups.py` 로 `followUpTasks[]` 의 auto-spawn 항목을
-    task stub 으로 만들고,
-    `validators/validate-run.py` 로 final-report schema / markdown contract /
-    report-view contract 를 검증한다. HTML view 가 치환 후 markdown 을 읽도록
-    token substitution 이 항상 render-views 보다 먼저 실행되며, validation 은
-    더 이상 실패할 후처리 단계가 없는 마지막 gate 로 실행된다. 후처리가 실패하면
-    report-writer 는 failed 로 기록한다.
-  - report-writer prompt history 파일이 아직 없으면 dispatcher 가 자동 생성한다.
-    이때 `Result Path` 는 `.data.json`, `Worker Result Path` 는 audit sidecar,
-    `Report Language` 는 project/global config 또는 task brief 추론값으로 채운다.
-  - 비범위: Codex lead 자체 token/cost accounting.
-
-### Stage 5.5 — Codex worker CLI token accounting
-
-- Codex runtime 은 Claude Agent wrapper session 을 생성하지 않으므로,
-  `okstra token-usage` 가 `lead-events-*.jsonl` 의 worker dispatch window 를
-  session source 로 사용한다.
-- `codex` worker 와 Codex opt-in `report-writer` 는 Codex rollout JSONL 을,
-  `gemini` worker 는 Gemini chat session JSON 을 window 안에서 매칭한다.
-- `usageSummary.workerTotalTokens` 와 `estimatedCostUsd.cliWorkers` 는 CLI worker
-  totals 를 반영한다.
-- report-writer 후처리 중에는 `worker-result-collected` 이벤트가 아직 append
-  되기 전이므로, collector 는 `status=running` worker 의 active dispatch 를
-  수집 시각까지의 open window 로 사용할 수 있다.
-- Codex lead 자체 token/cost 는 아직 공식 수집원이 없어 `leadUsage.source =
-  "unavailable"` 로 남긴다.
-- validator 는 Codex run 에 대해 token substitution auto-recovery 를 강제하지
-  않는다. 이 단계의 목적은 collector data 를 먼저 정확히 채우는 것이다.
-
-### Stage 6 — install packaging cleanup
-
-- `okstra install --runtime <claude-code|codex|all>` 을 추가한다.
-  - `claude-code` 기본값은 기존 동작 그대로 공유 runtime + Claude skills/agents 를
-    설치한다.
-  - `codex` 는 공유 runtime/bin/templates/schema/validators/settings 만 설치하고
-    `~/.claude/skills` / `~/.claude/agents` 를 건드리지 않는다.
-  - `all` 은 Claude assets 포함 설치와 동일하다. 별도 Codex-only asset tree 가
-    생기면 여기서 함께 설치한다.
-- `okstra ensure-installed --runtime <...>` 는 같은 runtime 으로 재설치하며,
-  `codex` 는 Claude skill/agent drift 검사를 건너뛴다.
-- `okstra doctor --runtime <...>` 는 `codex` 에서 Claude skill checks 를 제외하고
-  JSON 출력에 선택 runtime 을 포함한다.
-- `~/.okstra/installed-runtimes.json` 을 추가해 선택 runtime 과 asset 범위를
-  `installed-skills.json` / `installed-agents.json` 과 분리해 기록한다.
-  codex-only manifest 는 uninstall 이 레거시 fallback 으로 `~/.claude` 자산을
-  제거하지 않도록 막는다.
-- README / docs 는 Codex-only install + doctor 경로를 노출한다.
-- 남은 cleanup: Codex 전용 skill/adapter asset 이 생기면
-  `installed-runtimes.json` 의 Codex asset 범위를 실제 파일 manifest 로 확장한다.
-
-## 9. 위험과 대응
-
-| 위험 | 대응 |
-|---|---|
-| validator 가 Claude session jsonl 만 신뢰 | `leadRuntime` 별 conformance source 분기 |
-| worker output contract drift | logical worker role/schema 는 공유하고 dispatch backend 만 교체 |
-| report-writer authorship 규칙 훼손 | runtime 별 report-writer implementation 을 두고 fallback 은 명시 기록 |
-| 설치 경로 혼란 | `okstra doctor --runtime <name>` 로 runtime 별 진단 |
-| 두 버전 문서 drift | phase profile/schema/validator 는 fork 금지, adapter docs 만 분리 |
-
-## 10. 결론
-
-가능하다. 단, "Claude Code 버전"과 "Codex 버전"을 제품 복사본으로 나누는 것이
-아니라, **lead runtime adapter 를 나누는 방식**이어야 한다.
-
-가장 작고 안전한 첫 PR 은 `leadRuntime` marker 와 Codex dry-run adapter 이다.
-이 PR 은 기존 Claude Code 사용자를 깨지 않으면서 Codex 실행 경로를 공식적으로
-받아들일 수 있는 구조를 만든다.

package/docs/superpowers/specs/2026-06-12-html-plan-approval-design.md

@@ -1,85 +0,0 @@
-# final-report HTML 승인·옵션 선택 설계
-
-- 날짜: 2026-06-12
-- 상태: 설계 승인됨 (구현 전)
-- 대상: implementation-planning final-report 의 HTML 뷰 + implementation 시작 마법사
-
-## 1. 배경과 목표
-
-implementation-planning 보고서의 승인은 현재 (a) frontmatter `approved:` 수동 편집 또는 (b) CLI `--approve` 플래그로만 가능하고, 구현 옵션 선택은 `--implementation-option <name>` CLI 플래그뿐이다 (`scripts/okstra_ctl/run.py:305`, `scripts/okstra_ctl/run.py:744`). 사용자가 보고서를 검토하는 화면은 HTML 뷰인데, 그 화면에는 §1 clarification 폼만 있고 승인·옵션 선택 수단이 없다.
-
-목표: 사용자가 보고서 HTML 안에서 승인 의사와 구현 옵션을 기록하고, implementation 시작 시 그 기록이 확인 절차를 거쳐 기존 승인 경로로 적용되게 한다.
-
-설계 원칙 (기존 계약 유지):
-
-- HTML 은 원본 md / data.json 을 **절대 직접 수정하지 않는다** — 기록은 user-response sidecar 로만 나간다 (`templates/reports/user-response.template.md:6`).
-- data.json 이 SSOT — 적용은 data.json 플립 + md 재렌더 경로만 사용한다 (`scripts/okstra_ctl/run.py:222`).
-- 승인 게이트 검증(`_validate_approved_plan`, `scripts/okstra_ctl/run.py:331`)은 무변경 — sidecar 는 검증을 우회하지 않는다.
-
-## 2. 기각한 대안
-
-**§1 C-행 재사용안**: report-writer 가 승인/옵션을 §1 decision 행으로 발행해 기존 폼을 재사용하는 방법. §1 응답의 소비자는 resume-clarification(= planning 재실행)이라 적용 경로가 어긋나고, "§1 미해소 행 = 승인 차단" 게이트 규칙(`scripts/okstra_ctl/run.py:360`)과 자기모순이 생기므로 기각.
-
-**run-prep 무확인 자동 적용안**: HTML 버튼 클릭이 사실상 승인 행위가 되어 명시적 승인 원칙에 어긋나므로 기각. 마법사 확인 단계를 거친다.
-
-## 3. 설계
-
-### 3.1 HTML 위젯 — "Plan Approval" 섹션
-
-- 렌더 조건: `task-type == implementation-planning` **이고** sibling `.data.json` 이 존재할 때만. 둘 중 하나라도 아니면 섹션 자체를 생략한다.
-- 데이터 소스: md 파싱이 아니라 sibling data.json 의 `implementationPlanning.optionCandidates[].name` 과 `recommendedOption.name` (`schemas/final-report-v1.0.schema.json:1062`, `schemas/final-report-v1.0.schema.json:1102`). 렌더 시점(`render_html_view`)에 Python 이 읽어 HTML 에 정적으로 박는다.
-- 구성: 보고서 끝(footer 위)에
-  - 옵션 `<select>` — 후보 = optionCandidates 이름 목록, 기본 선택 = recommendedOption 이름에 "(권장)" 라벨.
-  - 승인 체크박스 — "이 plan 을 승인합니다".
-- 활성 조건 (fail-closed, run-prep 게이트와 동일 기준): §1 의 `Blocks: approval` 행이 전부 `resolved`/`obsolete` 일 때만 활성. 미해소(open/answered) 행이 있으면 disabled + "§1 승인 차단 항목 N건 미해소 — 답변 후 resume-clarification 으로 다음 보고서에서 승인" 사유를 표시한다. 판정은 렌더 시 Python 이 §1 을 스캔(`scan_approval_gate` 재사용)해 박는다.
-- Export: 기존 "Export user response" 버튼 하나에 합류 — 별도 버튼을 만들지 않는다.
-
-### 3.2 sidecar 스키마 확장
-
-`user-response-<task-type>-<seq>.md` 본문 끝에 APPROVAL 블록 1개를 허용한다:
-
-```markdown
-## APPROVAL
-- Approved: true
-- Implementation-Option: <optionCandidates[].name 그대로>
-```
-
-- 승인 체크 없이 Export 하면 블록 자체를 생략한다 (기존 출력과 동일).
-- 옵션을 추천 그대로 두면 `Implementation-Option:` 라인을 생략한다 → 기존 Recommended 폴백 의미 유지 (`scripts/okstra_ctl/run.py:308`).
-- Python `serialize_user_response` 와 JS `buildUserResponseMarkdown` 의 byte-identical 계약은 유지하고, 동일성 테스트를 APPROVAL 케이스로 확장한다 (`templates/reports/user-response.template.md:69`).
-
-### 3.2.1 user-responses/ 디렉토리 선생성
-
-사용자 확인(폼 입력 또는 승인)이 필요한 HTML 을 렌더하는 시점에 `render_html_view` 가 저장 대상 디렉토리 `runs/<task-type>/.../user-responses/` (reports/ 의 sibling) 를 함께 생성한다. 사용자가 Export 파일을 저장할 위치를 직접 만들 필요가 없어야 한다. HTML 을 생성하지 않는 보고서(인터랙티브 요소 없음)에는 만들지 않는다.
-
-### 3.3 소비 — implementation 마법사
-
-`approved_plan` 단계(`skills/okstra-run/SKILL.md:126`)에서:
-
-1. 지정된 plan 이 `approved: false` 이고, 같은 run 의 `user-responses/` 에 source-report 와 seq 가 일치하며 APPROVAL 블록을 가진 sidecar 가 있으면, pick 단계를 노출한다:
-   - "HTML 승인 기록 발견(옵션: X) — 적용 (추천)" / "무시하고 진행" / "중단".
-2. "적용" 선택 시 기존 함수만 호출한다:
-   - `_set_data_json_approved_true_if_present` (`scripts/okstra_ctl/run.py:222`) — data.json 플립 + md 재렌더.
-   - sidecar 에 `Implementation-Option:` 이 있으면 `_apply_cli_implementation_option` (`scripts/okstra_ctl/run.py:744`).
-   - audit 라인에 HTML user-response 경유임을 명시 (기존 `--approve` audit 라인 형식 확장).
-3. 적용 후 게이트 검증(`_validate_approved_plan`)은 기존 그대로 수행된다.
-
-### 3.4 엣지 케이스
-
-| 상황 | 처리 |
-|---|---|
-| sidecar 의 옵션 이름이 현 data.json optionCandidates 에 없음 | 적용 거부 + 에러 메시지에 유효 후보 나열 |
-| sidecar seq ≠ 보고서 seq | 해당 sidecar 무시 (소스 보고서 기준) |
-| APPROVAL 블록이 있는데 §1 차단 행 미해소 (조작/구버전 HTML) | 적용 시도해도 기존 게이트가 거부 — 추가 방어 불요 |
-| plan 이 이미 `approved: true` | pick 단계 생략, 기존 흐름 그대로 |
-
-### 3.5 테스트
-
-- `tests/test_report_views.py`: 위젯 렌더 조건 3종 — (a) planning + data.json + 차단 없음 → 활성 렌더, (b) 차단 행 존재 → disabled + 사유, (c) 타 task-type 또는 data.json 부재 → 섹션 생략.
-- 직렬화 동일성: APPROVAL 블록 포함/생략 케이스에서 Python ↔ JS byte-identical.
-- 마법사: sidecar 감지 → pick 노출, "적용" 경로가 data.json 플립 + 옵션 치환을 수행하는 단위 테스트.
-
-## 4. 범위 제외 (후속 과제)
-
-- sidecar 없이 마법사 단독으로 옵션을 고르는 standalone pick 단계 — 이번 범위 아님 (현행 CLI 플래그 유지).
-- implementation-planning 외 task-type 의 승인 위젯 — frontmatter `approved:` 를 소비하는 진입점이 implementation 뿐이므로 대상 없음.

package/docs/superpowers/specs/2026-06-12-stage-discipline-rule-design.md

@@ -1,108 +0,0 @@
-# Stage discipline 규칙 — 선행 stage 동작 동결 설계
-
-- 날짜: 2026-06-12
-- 상태: 설계 승인됨 (구현 전)
-- 대상: `implementation` · `implementation-planning` 프로파일
-
-## 1. 배경과 목표
-
-implementation 은 stage-isolated 다 — 한 run = 한 stage 이고, dependent stage 는 선행(`depends-on`) stage 의 done commit 을 base 로 시작한다(`prompts/profiles/implementation.md:27`). 선행 stage 는 이미 conformance 를 통과해 `done` 으로 닫힌 상태인데, 이후 stage 가 그 코드의 **동작을 바꾸면** "verified-stays-verified" 불변식이 깨진다 — 닫힌 stage 가 조용히 회귀한다.
-
-목표: "선행 stage 가 추가·수정한 코드의 기능(동작)은 이후 stage 에서 변경하지 않는다" 라는 규율을 `implementation` 과 `implementation-planning` 양쪽에 도입하고, 이런 stage 규율을 **별도 단일 파일**로 관리한다.
-
-## 2. 결정 사항 (brainstorming 합의)
-
-| 항목 | 결정 |
-|---|---|
-| 규칙 파일 소유권 | okstra 내장 공유 파일 (모든 프로젝트 적용, okstra 레포에서 편집·전파) |
-| 강제 수준 | 선언 + 보고서 증거 (validator/wrapper sentinel 없음) |
-| 규칙 언어 | English (기존 Forbidden actions·stage-scope 규칙과 일관) |
-| executor 전사 포인터 | 둔다 (CLI executor 가 규칙을 받도록) |
-
-YAGNI 로 제외: validator/wrapper 강제, data.json 스키마 필드, 프로젝트별 override.
-
-## 3. 아키텍처 근거
-
-- 프로파일은 `{{INCLUDE:<name>}}` 로 공유 계약을 합친다 — resolver 는 임의 파일을 지원한다(`scripts/okstra_ctl/run.py:973` `_expand_profile_includes`, 재귀 depth ≤4, 누락 시 `PrepareError` fail-fast). 추가 코드 변경 없이 새 사이드카를 INCLUDE 할 수 있다.
-- `implementation-planning` 의 행위자는 lead/planner 본인이라 INCLUDE 로 직접 바인딩된다.
-- `implementation` 의 실제 행위자인 **executor(codex/gemini CLI)는 lead 컨텍스트를 공유하지 않는다**. 기존 계약은 lead 가 규칙을 executor 프롬프트에 **verbatim 전사**하게 한다(`prompts/profiles/_implementation-executor.md:27` "CLI executor transcription"). 따라서 implementation 규칙이 CLI executor 에 닿으려면 전사 포인터가 필요하다.
-- executor 사이드카(`_implementation-executor.md`)는 lead 가 Phase 5 에 raw 로 lazy-load 하며 `{{INCLUDE}}` resolver 를 거치지 않는다(`_implementation-executor.md:3`). 그래서 사이드카에는 규칙 **텍스트를 복사하지 않고** 단일 출처를 가리키는 **전사 지시 한 줄**만 둔다(DRY).
-
-## 4. 설계
-
-### 4.1 신규 단일 파일 `prompts/profiles/_stage-discipline.md` (SSOT)
-
-규칙의 유일한 출처. 핵심 원칙 + phase 별 적용 + 보고서 증거 절을 담는다. 전체 본문:
-
-```markdown
-<!--
-Shared stage-discipline rule. INCLUDEd by implementation-planning.md (binds the
-planner) and implementation.md (binds the lead). The implementation executor
-sidecar instructs the lead to transcribe this rule into a CLI executor prompt,
-since codex/gemini executors do not share lead context.
-
-Do NOT write the literal include directive token in this file's body — the
-resolver matches it anywhere and would recurse on this file itself.
--->
-
-## Stage discipline — preceding stages are behavior-frozen
-
-A stage that is already `done` (a `depends-on` predecessor whose work is merged
-into this run's base) is **behavior-frozen**: code it added or modified keeps its
-existing behavior. Later stages MAY call, extend, or compose with that code, but
-MUST NOT change what it already does. This preserves the verified-stays-verified
-invariant — a completed, conformance-passed stage must not silently regress when
-a later stage runs.
-
-- **implementation-planning** — decompose stages forward-only. No stage's scope
-  may require altering an earlier stage's behavior; each stage builds additively
-  on its predecessors' Stage Exit Contracts. If delivering an increment would
-  force changing an earlier stage's behavior, that earlier stage was mis-scoped —
-  fold the change into that stage or re-partition; do not plan a later stage that
-  rewrites it.
-- **implementation** — the executor MUST NOT alter the behavior of any file added
-  or modified by a preceding done stage. Touching such a file to *extend* it (a
-  new branch, a new caller, an additive field) is allowed; changing its existing
-  behavior is not. If a plan step appears to require a behavior change to
-  prior-stage code, treat it as a planning defect: record the finding and route
-  to a new `implementation-planning` run — never silently rewrite it.
-  - **Report evidence (declaration-level).** When this stage modifies a file that
-    a preceding stage added or modified, the final report MUST record — in the
-    deliverable's existing edits / validation evidence section — which file, why
-    it was touched, and how the prior stage's behavior was preserved. Absent that
-    note, a reviewer treats a prior-stage edit as an unverified regression risk.
-```
-
-### 4.2 INCLUDE 배선
-
-- `prompts/profiles/implementation.md`: 기존 `{{INCLUDE:_common-contract.md}}`(line 17) 바로 다음 줄에 `{{INCLUDE:_stage-discipline.md}}` 추가.
-- `prompts/profiles/implementation-planning.md`: 기존 `{{INCLUDE:_common-contract.md}}`(line 10) 바로 다음 줄에 `{{INCLUDE:_stage-discipline.md}}` 추가.
-
-### 4.3 executor 전사 포인터
-
-`prompts/profiles/_implementation-executor.md` 의 기존 전사 규칙(`:27` "CLI executor transcription") 근처에 형제 bullet 한 줄 추가 (규칙 텍스트 복사 없음):
-
-```markdown
-- **Stage discipline transcription (when a preceding stage is `done`):** the lead
-  MUST transcribe the `Stage discipline` rule (from this run's rendered profile)
-  verbatim into the dispatched CLI executor prompt, so a codex/gemini executor
-  honors the prior-stage behavior-freeze. Declaration-level — no wrapper sentinel.
-```
-
-### 4.4 전파
-
-`tools/build.mjs` 가 `prompts/` → `runtime/` 를 동기화하고 install 이 사용자 머신으로 복사한다. INCLUDE resolver 가 임의 파일을 이미 지원하므로 추가 코드 변경은 없다.
-
-## 5. 테스트
-
-`tests/test_okstra_profile_includes.py` 확장:
-- `implementation.md` 렌더 결과에 `Stage discipline — preceding stages are behavior-frozen` 헤딩과 `behavior-frozen` 본문이 INCLUDE 로 들어오는지 단언.
-- `implementation-planning.md` 렌더 결과에 같은 규칙 텍스트가 들어오는지 단언.
-- `_stage-discipline.md` 파일 존재 + `implementation` / `implementation-planning` 두 프로파일에 INCLUDE 디렉티브가 있는지 단언 (executor 사이드카에는 전사 포인터 문자열이 있는지 단언).
-
-(누락 INCLUDE 는 `_expand_profile_includes` 가 이미 `PrepareError` 로 fail-fast.)
-
-## 6. 영향받지 않는 것
-
-- 다른 phase(`requirements-discovery` / `error-analysis` / `final-verification` / `release-handoff` / `improvement-discovery`)는 무변경 — 규칙은 두 프로파일에만 INCLUDE 된다.
-- data.json 스키마, validator, CLI 플래그, wizard 무변경.