okstra 0.52.0 → 0.53.0

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

@@ -0,0 +1,303 @@
+# 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
+```