okstra 0.102.2 → 0.102.3

package/docs/superpowers/plans/2026-06-06-stage-worktree-isolation-p4.md

@@ -1,303 +0,0 @@
-# Stage Worktree 격리 P4 — CLI 패스스루 + 프로파일/문서 정합 구현 계획
-
-> **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:** 사용자-facing 표면을 stage 격리에 맞춘다 — (B2) `okstra.sh`/`cli.sh`에 `--stage` 패스스루, (프로파일) `_implementation-executor.md`의 batch 문구를 spec §2.3 "한 run = 한 stage"로, (B1) okstra-run SKILL.md sub-flow에 stage_pick 문서화.
-
-**Architecture:** B2는 기존 `--base-ref` 등과 동일한 cli.sh case + okstra.sh PY_ARGS 패턴을 그대로 따른다(셸 변경, e2e로 검증). 프로파일/SKILL은 문서 정합 — P3가 `STAGE_BATCH_DIRECTIVE`를 단수("Stage for this implementation run")로 바꿨으므로 executor가 참조하는 backtick 토큰과 batch 가정 문장을 단일 stage로 맞춘다.
-
-**Tech Stack:** Bash (`scripts/okstra.sh`, `scripts/lib/okstra/cli.sh`), Markdown (`prompts/profiles/_implementation-executor.md`, `skills/okstra-run/SKILL.md`), pytest (e2e via subprocess).
-
-설계 문서: [docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md](../specs/2026-06-06-stage-worktree-isolation-design.md) §2.3 / §5 (dispatch UX). **비범위:** release-handoff stage PR 목록 수집(§5) → P5 별도 plan.
-
----
-
-## File Structure
-
-- Modify: `scripts/lib/okstra/cli.sh` — `--stage` case ([cli.sh:94](../../../scripts/lib/okstra/cli.sh) 의 `--base-ref` 패턴) + valid-options 문자열([cli.sh:188](../../../scripts/lib/okstra/cli.sh))
-- Modify: `scripts/okstra.sh` — PY_ARGS 패스스루 ([okstra.sh:124](../../../scripts/okstra.sh) 의 `--base-ref` 줄 옆)
-- Modify: `prompts/profiles/_implementation-executor.md` — batch 문구 → 단일 stage ([lines 30–46](../../../prompts/profiles/_implementation-executor.md))
-- Modify: `skills/okstra-run/SKILL.md` — sub-flow 에 stage pick ([SKILL.md:125](../../../skills/okstra-run/SKILL.md))
-- Test: `tests/test_okstra_sh_stage_passthrough.py` (신규, e2e)
-
----
-
-### Task 1: B2 — `okstra.sh`/`cli.sh` `--stage` 패스스루
-
-**Files:**
-- Modify: `scripts/lib/okstra/cli.sh`, `scripts/okstra.sh`
-- Test: `tests/test_okstra_sh_stage_passthrough.py` (신규)
-
-- [ ] **Step 1: Write the failing e2e test**
-
-```python
-# tests/test_okstra_sh_stage_passthrough.py (신규)
-"""okstra.sh 가 --stage 를 받아 python -m okstra_ctl.run 까지 전달하는지 검증."""
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-from pathlib import Path
-
-REPO = Path(__file__).resolve().parents[1]
-SCRIPT = REPO / "scripts" / "okstra.sh"
-
-
-def _git_init(repo: Path) -> None:
-    subprocess.run(["git", "init", "-q", str(repo)], check=True)
-    subprocess.run(["git", "-C", str(repo), "config", "user.email", "t@e"], check=True)
-    subprocess.run(["git", "-C", str(repo), "config", "user.name", "t"], check=True)
-    (repo / "README").write_text("seed\n")
-    subprocess.run(["git", "-C", str(repo), "add", "."], check=True)
-    subprocess.run(["git", "-C", str(repo), "commit", "-q", "-m", "init"], check=True)
-
-
-def _approved_plan(repo: Path) -> Path:
-    src = REPO / "tests" / "fixtures" / "plans" / "valid_one_stage.md"
-    # plan 은 .okstra/tasks/<...>/runs/implementation-planning/reports/ 모양일 필요 없이
-    # --approved-plan 는 파일 경로만 검사하므로 repo 안 임의 위치로 둔다.
-    dst = repo / "plan.md"
-    dst.write_text(
-        "---\ntitle: t\napproved: true\n---\n\n" + src.read_text(encoding="utf-8"),
-        encoding="utf-8",
-    )
-    return dst
-
-
-def test_okstra_sh_forwards_stage_to_run(tmp_path):
-    repo = tmp_path / "proj"
-    repo.mkdir()
-    _git_init(repo)
-    plan = _approved_plan(repo)
-    home = tmp_path / "okstra-home"
-    env = {**os.environ, "OKSTRA_HOME": str(home)}
-
-    result = subprocess.run(
-        [str(SCRIPT), "--render-only", "--yes",
-         "--task-type", "implementation",
-         "--project-id", "proj",
-         "--project-root", str(repo),
-         "--task-group", "demo", "--task-id", "demo-1",
-         "--task-brief", "README",
-         "--approved-plan", str(plan),
-         "--base-ref", "HEAD",
-         "--stage", "1"],
-        env=env, capture_output=True, text=True, check=False,
-    )
-    # cli.sh 가 --stage 를 모르면 "unknown option" / "valid options" 로 죽는다.
-    assert "unknown option" not in result.stderr.lower(), result.stderr
-    assert "--stage" not in result.stderr or "valid options" not in result.stderr, result.stderr
-    # python 까지 전달되면 run.py 가 stage 1 을 선택해 출력한다.
-    assert result.returncode == 0, f"stdout={result.stdout}\nstderr={result.stderr}"
-    assert "selected stages: 1" in result.stdout, result.stdout
-
-
-def test_okstra_sh_unknown_flag_still_rejected(tmp_path):
-    """가드: 진짜 미지원 플래그는 여전히 거부되어야 한다 (--stage 추가가 파서를
-    느슨하게 만들지 않았는지)."""
-    home = tmp_path / "okstra-home"
-    env = {**os.environ, "OKSTRA_HOME": str(home)}
-    result = subprocess.run(
-        [str(SCRIPT), "--render-only", "--yes",
-         "--task-type", "error-analysis",
-         "--project-id", "proj", "--project-root", str(tmp_path),
-         "--task-group", "demo", "--task-id", "demo-1",
-         "--task-brief", "x", "--bogus-flag", "v"],
-        env=env, capture_output=True, text=True, check=False,
-    )
-    assert result.returncode != 0
-    assert "bogus-flag" in result.stderr or "unknown" in result.stderr.lower()
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_sh_stage_passthrough.py -v`
-Expected: `test_okstra_sh_forwards_stage_to_run` FAILS — cli.sh rejects `--stage` as an unknown option (returncode != 0, "valid options" in stderr). The guard test may already pass.
-
-- [ ] **Step 3a: Add `--stage` case to cli.sh**
-
-[cli.sh](../../../scripts/lib/okstra/cli.sh) 의 `--base-ref)` case 블록(약 line 94–96) 바로 아래에 추가:
-
-```bash
-    --stage)
-      STAGE="$(require_option_value --stage "${2-}")"
-      shift 2
-      ;;
-```
-
-- [ ] **Step 3b: Add `--stage` to the valid-options help string in cli.sh**
-
-[cli.sh:188](../../../scripts/lib/okstra/cli.sh) 의 `valid options:` 문자열에서 `--implementation-option` 뒤에 ` --stage` 를 삽입:
-
-```bash
-      printf '  valid options: --render-only --resume-clarification --yes --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan --approve --implementation-option --stage --no-plan-verification -h|--help\n' >&2
-```
-
-- [ ] **Step 3c: Forward `--stage` in okstra.sh PY_ARGS**
-
-[okstra.sh:124](../../../scripts/okstra.sh) 의 `--base-ref` 줄 바로 아래에 추가:
-
-```bash
-[[ -n "${STAGE-}" ]] && PY_ARGS+=(--stage "$STAGE")
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_sh_stage_passthrough.py -v`
-Expected: PASS (2개).
-
-- [ ] **Step 5: Commit**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-git add scripts/lib/okstra/cli.sh scripts/okstra.sh tests/test_okstra_sh_stage_passthrough.py
-git commit -m "feat(cli): forward --stage through okstra.sh to run.py (B2)"
-```
-
----
-
-### Task 2: executor 프로파일 — batch 문구 → 단일 stage (spec §2.3)
-
-**Files:**
-- Modify: `prompts/profiles/_implementation-executor.md` (lines 30–46)
-
-> 문서 변경. 검증은 grep 토큰 + 전체 회귀. P3가 `STAGE_BATCH_DIRECTIVE` 를 단수("Stage for this implementation run")로 바꿨으므로, executor 가 참조하는 backtick 토큰과 batch 가정 문장을 단일 stage 로 맞춘다.
-
-- [ ] **Step 1: Replace line 30**
-
-before:
-```
-- re-read the approved plan end-to-end and parse the `## 5.5 Stage Map`. Read the **Stage batch** injected in the launch prompt (`Stage batch for this implementation run`): it lists the stage numbers this run owns, ascending. The runtime already selected and reserved this batch — do NOT recompute the start stage from `consumers.jsonl`.
-```
-after:
-```
-- re-read the approved plan end-to-end and parse the `## 5.5 Stage Map`. Read the **Stage** injected in the launch prompt (`Stage for this implementation run`): the single stage number this run owns. The runtime already selected and reserved this stage (one run = one stage) — do NOT recompute the start stage from `consumers.jsonl`.
-```
-
-- [ ] **Step 2: Replace lines 31–32**
-
-before:
-```
-  - for each stage in the batch, load every `runs/<plan-key>/carry/stage-<i>.json` for `i ∈ depends-on(stage)` and inject them into the executor's working context as "runtime carry-in". For `depends-on (none)` stages, no sidecar load — task-brief only.
-  - the batch's stages are mutually independent (each one's `depends-on` are all already `status:done`, never another batch member), so execute them in ascending order; each stage's file list, step order, Stage Validation commands, Stage Exit Contract, and rollback path are the authoritative scope for that stage.
-```
-after:
-```
-  - load every `runs/<plan-key>/carry/stage-<i>.json` for `i ∈ depends-on(this stage)` and inject them into the executor's working context as "runtime carry-in". For a `depends-on (none)` stage, no sidecar load — task-brief only.
-  - this stage's `depends-on` are all already `status:done`. Its file list, step order, Stage Validation commands, Stage Exit Contract, and rollback path are the authoritative scope.
-```
-
-- [ ] **Step 3: Replace line 40 (section heading)**
-
-before:
-```
-## Stage execution contract (this run owns the injected stage batch)
-```
-after:
-```
-## Stage execution contract (this run owns one stage)
-```
-
-- [ ] **Step 4: Replace lines 42–43**
-
-before:
-```
-- **Sidecar evidence writer (BLOCKING, per stage).** For each stage in the batch, when that stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object matching the schema in `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2 and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. Each file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal).
-- **Reverse link (BLOCKING, per stage).** The runtime already appended a `status:"started"` row per batch stage before this run began. On each stage's completion, append a `status:"done"` row with `carry_path` populated for that stage number.
-```
-after:
-```
-- **Sidecar evidence writer (BLOCKING).** When this stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object matching the schema in `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2 and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal).
-- **Reverse link (BLOCKING).** The runtime already appended a `status:"started"` row for this stage before the run began. On completion, append a `status:"done"` row with `carry_path` populated for this stage number.
-```
-
-- [ ] **Step 5: Replace lines 44–46 (PR section)**
-
-before:
-```
-- **One-PR-per-run.** This run creates exactly one PR titled `Stages <first>–<last>: <run summary>` (or `Stage <N>: <title>` when the batch is a single stage). The PR body MUST include:
-  - `## Stage <N>` — one section per batched stage: number, title (from Stage Map row), touched files, and validation result.
-  - `## Carry-In summary` — per stage, depends-on list + cited identifiers/SHAs from each loaded sidecar (omit when depends-on is empty).
-```
-after:
-```
-- **One-PR-per-run.** This run creates exactly one PR titled `Stage <N>: <title>`. The PR body MUST include:
-  - `## Stage <N>` — number, title (from Stage Map row), touched files, and validation result.
-  - `## Carry-In summary` — depends-on list + cited identifiers/SHAs from each loaded sidecar (omit when depends-on is empty).
-```
-
-- [ ] **Step 6: Verify no stale batch tokens remain + run build/regression**
-
-Run:
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-grep -nE "Stage batch|batched stage|batch's stages|Stages <first>" prompts/profiles/_implementation-executor.md && echo "STALE TOKENS REMAIN — fix" || echo "clean"
-npm run build >/dev/null 2>&1 && echo "build ok" || echo "build FAILED"
-python3 -m pytest tests/ -q
-```
-Expected: `clean`, `build ok`, full suite PASS (프로파일은 런타임 복사 대상이라 `npm run build` 가 `runtime/` 에 동기화한다 — build 실패 시 BLOCKED).
-
-- [ ] **Step 7: Commit**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-git add prompts/profiles/_implementation-executor.md
-git commit -m "docs(profiles): executor owns one stage, not a batch (spec §2.3)"
-```
-
----
-
-### Task 3: B1 — okstra-run SKILL.md sub-flow 에 stage pick 문서화
-
-**Files:**
-- Modify: `skills/okstra-run/SKILL.md:125`
-
-- [ ] **Step 1: Replace line 125**
-
-before:
-```
-- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + executor pick,
-```
-after:
-```
-- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = 의존성 충족된 가장 빠른 미완료 stage, 또는 특정 stage 번호) + executor pick,
-```
-
-- [ ] **Step 2: Verify + commit**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-grep -n "stage pick" skills/okstra-run/SKILL.md && echo "documented"
-npm run build >/dev/null 2>&1 && echo "build ok"
-git add skills/okstra-run/SKILL.md
-git commit -m "docs(okstra-run): document stage_pick step in implementation sub-flow (B1)"
-```
-
----
-
-## Self-Review
-
-**Spec coverage (P4 범위):**
-- §5 dispatch B2 (`--stage` CLI 패스스루) → Task 1 ✓ (e2e + unknown-flag 가드)
-- §2.3 한 run = 한 stage 프로파일 정합 → Task 2 ✓ (P3의 단수 DIRECTIVE 와 토큰 일치)
-- §5 dispatch B1 (stage_pick 문서) → Task 3 ✓
-- release-handoff stage PR 수집 → **P5 (비범위, 명시)**
-
-**Placeholder scan:** 없음 — Task 1 완전 코드, Task 2/3 완전 before/after.
-
-**Type/token consistency:** Task 2 의 after 토큰("Stage for this implementation run")이 P3 의 `STAGE_BATCH_DIRECTIVE` 문자열([run.py 의 `**Stage for this implementation run:**`])과 정확히 일치 — executor 가 launch prompt 에서 그 backtick 을 찾는다.
-
-**위험 플래그(구현자 주의):**
-- 프로파일/SKILL 은 `runtime/` 빌드 산출물로 복사된다(seed 규칙). Task 2/3 의 `npm run build` 가 동기화 단계 — 실패 시 BLOCKED.
-- Task 1 e2e 는 implementation 경로라 git `project_root` + `--base-ref HEAD` + approved-plan fixture 가 필수다. `valid_one_stage.md` fixture 가 frontmatter 없이 시작하므로 테스트가 `approved: true` frontmatter 를 prepend 한다(기존 `test_run_stage_arg.py` 패턴과 동일).
-
-## 검증 (P4 완료 기준)
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-python3 -m pytest tests/test_okstra_sh_stage_passthrough.py -v
-grep -nE "Stage batch|batched stage" prompts/profiles/_implementation-executor.md || echo "profile clean"
-grep -n "stage pick" skills/okstra-run/SKILL.md
-npm run build && python3 -m pytest tests/ -q
-```