okstra 0.36.2 → 0.37.0

package/docs/superpowers/plans/2026-05-25-okstra-project-root-rename.md

@@ -0,0 +1,159 @@
+# Okstra 프로젝트 산출물 루트 이전 Implementation Plan
+
+> **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:** okstra 가 프로젝트 안에 만드는 모든 산출물의 루트를 `<PROJECT_ROOT>/.project-docs/okstra/` 에서 `<PROJECT_ROOT>/.okstra/` 로 이전한다. 동시에 path 문자열이 60+ 파일에 산재해 있던 DRY 위반을 해소해 Python / Node / Shell 각 한 곳의 SSOT 만 바꾸면 전 코드가 따라오는 구조로 정리한다. 기존 사용자는 신규 `okstra migrate` 명령 한 번으로 이전.
+
+**Non-goals:**
+- `.project-docs/` 디렉토리 자체 제거. okstra 외 용도 (`.project-docs/agents/domain.md` 등) 가 살아 있을 수 있음 — okstra 하위만 빼낸다.
+- Backwards-compat shim. 사용자 글로벌 메모리의 *pre-1.0 means no backwards compatibility concerns* 정책 적용. 두 경로 동시 지원은 하지 않음.
+- 사용자 IDE workspace 파일이나 외부 스크립트의 path 수정. CHANGES.md 와 release notes 에 사용자 알림만.
+
+**확정된 결정 사항:**
+- 마이그레이션: `okstra migrate` 자동 명령 제공. 다음 v0.x 이후 제거.
+- SSOT: 이번 변경에서 path SSOT 동시 수렴 (Python `paths.OKSTRA_RELATIVE`, Node `config.mjs` export, Shell `validators/lib/paths.sh`).
+- 디렉토리 이름: `.okstra` (사용자 지정).
+
+---
+
+## 영향 범위 스냅샷 (2026-05-25 기준)
+
+| 카테고리 | 파일 수 | 핵심 경로 |
+|---|---|---|
+| Python SSOT 후보 | 3 | `scripts/okstra_ctl/paths.py:23`, `scripts/okstra_project/{resolver,state}.py` |
+| Node SSOT 후보 | 4 | `src/{config,setup,install,check-project,uninstall}.mjs` |
+| Python 호출자 (하드코드) | ~15 | `scripts/okstra_ctl/{render,run,seeding,wizard,worktree,backfill,pr_template,sequence}.py`, `okstra-spawn-followups.py`, `okstra_token_usage/collect.py`, `validators/validate-*.py` |
+| Shell 스크립트 | 5 | `scripts/lib/okstra/{interactive,project-resolver,usage}.sh`, `scripts/lib/okstra-ctl/cmd-rerun.sh`, `validators/{lib/paths,lib/fixtures,validate-brief,validate-workflow}.sh` |
+| 스킬 / 프로필 / 에이전트 | 13 | `skills/okstra-*/SKILL.md`, `prompts/profiles/*.md`, `agents/{SKILL.md,workers/claude-worker.md}` |
+| 템플릿 | 4 | `templates/okstra.CLAUDE.md`, `templates/reports/{brief,task-brief}.template.md`, `skills/okstra-run/templates/pr-body.template.md` |
+| 테스트 | ~20 | `tests/test_okstra_*.py`, `tests-e2e/scenario-*.sh` 2개 |
+| 문서 | ~12 | `README{,.kr}.md`, `CLAUDE.md`, `docs/kr/{architecture,cli}.md`, `docs/project-structure-overview.md`, `docs/task-process/common-flow.md`, `docs/superpowers/plans/*` |
+| 제외 | — | `graphify-out/` (다음 update 시 재생성), `.project-docs/2026-05-10/feature-checklist.md` (okstra 무관) |
+
+---
+
+## Track 1 — Path SSOT 수렴
+
+### Task 1.1: Python SSOT 신설 + 호출자 일괄 교체
+- [ ] `scripts/okstra_ctl/paths.py` 에 `OKSTRA_DIR_NAME = ".project-docs/okstra"` (이 단계에서는 값 유지) 와 `OKSTRA_RELATIVE = Path(OKSTRA_DIR_NAME)` 추가. 기존 `OKSTRA_RELATIVE` 정의는 새 상수로 치환.
+- [ ] `scripts/okstra_project/{resolver,state,__init__}.py` 의 path 하드코드를 `paths.OKSTRA_RELATIVE` import 로 교체. 문자열 메시지의 `.project-docs/okstra` 도 변수 보간으로 통일.
+- [ ] `scripts/okstra_ctl/{render,run,seeding,wizard,worktree,backfill,pr_template,sequence}.py`, `okstra-spawn-followups.py`, `okstra_token_usage/collect.py`, `validators/validate-{run,brief}.py` 가 path 빌드 시 헬퍼 사용.
+- [ ] `_infer_project_root` (`okstra_token_usage/collect.py:258`) 의 marker 디렉토리 — 지금은 `.project-docs` — 를 `OKSTRA_DIR_NAME` 사용으로 교체. 다른 용도의 `.project-docs/` 가 있는 디렉토리에서 오탐 방지.
+- [ ] `pytest tests/` 통과 (이 단계는 값 변경 없음, 회귀만 확인).
+
+### Task 1.2: Node SSOT 신설 + 호출자 일괄 교체
+- [ ] `src/config.mjs` 에 `export const OKSTRA_DIR = ".project-docs/okstra"` (값 유지) 와 `projectJsonPath(projectRoot)`, `claudeMdSymlinkPath(projectRoot)`, `claudeMdImportLine()` 헬퍼 신설.
+- [ ] `src/{setup,install,check-project,uninstall}.mjs` 의 `join(projectRoot, ".project-docs", "okstra", ...)` 패턴을 헬퍼 호출로 교체. `CLAUDE_MD_SYMLINK_REL`, `CLAUDE_MD_IMPORT_LINE` 도 동일 상수 기반.
+- [ ] `node bin/okstra --version`, `node bin/okstra doctor` 정상 동작 확인.
+
+### Task 1.3: Shell SSOT 승격
+- [ ] `validators/lib/paths.sh` 를 shell SSOT 로 승격 — `OKSTRA_DIR=".project-docs/okstra"` export (값 유지).
+- [ ] `scripts/lib/okstra/{interactive,project-resolver,usage}.sh`, `scripts/lib/okstra-ctl/cmd-rerun.sh`, `validators/lib/fixtures.sh`, `validators/validate-{brief,workflow}.sh` 가 `validators/lib/paths.sh` 를 source 하여 `$OKSTRA_DIR` 참조.
+- [ ] `bash validators/validate-workflow.sh` 통과.
+
+---
+
+## Track 2 — 값 전환
+
+### Task 2.1: SSOT 상수 값 교체
+- [ ] Python `OKSTRA_DIR_NAME = ".okstra"` (1 줄).
+- [ ] Node `OKSTRA_DIR = ".okstra"` (1 줄).
+- [ ] Shell `OKSTRA_DIR=".okstra"` (1 줄).
+
+### Task 2.2: 테스트 fixture 갱신
+- [ ] `tests/test_okstra_*.py` 의 fixture 가 만드는 임시 디렉토리 path 갱신 — 약 20개 파일.
+- [ ] `tests-e2e/scenario-08-improvement-discovery-render-only.sh`, `tests-e2e/scenario-09-improvement-brief-generation.sh` 의 fixture path 갱신.
+- [ ] `python3 -m pytest tests/` 전체 통과 (지금 시점에서 734 passed, 2 skipped 회귀 없음).
+
+### Task 2.3: 사용자 노출 문자열 일괄 sed
+- [ ] 명령 (Okstra 저장소 루트에서):
+  ```bash
+  grep -rln "\.project-docs/okstra" --include="*.md" --include="*.sh" --include="*.json" . \
+    | grep -v "^\./graphify-out/" \
+    | grep -v "^\./\.project-docs/" \
+    | xargs sed -i '' 's|\.project-docs/okstra|.okstra|g'
+  ```
+- [ ] 결과 확인 대상: `agents/`, `prompts/profiles/`, `skills/`, `templates/`, `docs/`, `README{,.kr}.md`, `CLAUDE.md`, `CHANGES.md`, `tests-e2e/README.md`.
+- [ ] `.claude/settings.local.json` 의 path-scoped permission 룰도 동시 갱신 (별도 수동 — JSON sed 위험).
+- [ ] `pytest tests/` 와 `validators/validate-workflow.sh` 재통과.
+
+---
+
+## Track 3 — `okstra migrate` 명령
+
+### Task 3.1: 코어 모듈 신설
+- [ ] `scripts/okstra_ctl/migrate.py` 신규:
+  - `prepare_migration_plan(project_root: Path) -> MigrationPlan` — 변경 대상 수집 (move, claude-md, gitignore, registry).
+  - `apply_migration_plan(plan, *, dry_run=True) -> MigrationResult` — 실행.
+  - 거부 가드: `.okstra/` 이미 존재 / `.project-docs/okstra/` 없음 / git 미사용 시 일반 `mv` fallback.
+  - 동작 항목:
+    1. `git mv .project-docs/okstra .okstra` (git 없는 곳은 `mv`).
+    2. `.project-docs/` 가 비면 `rmdir .project-docs`.
+    3. `<PROJECT_ROOT>/CLAUDE.md` 의 `@.project-docs/okstra/CLAUDE.md` import 라인 → `@.okstra/CLAUDE.md`.
+    4. `.gitignore` 의 `.project-docs/okstra/` 항목 → `.okstra/`.
+    5. `~/.okstra/{recent,active}.jsonl` 와 `~/.okstra/worktrees/registry.json` 의 해당 프로젝트 path 항목 갱신.
+- [ ] `MigrationPlan` 은 dataclass, JSON 직렬화 가능 (dry-run 출력에 그대로 사용).
+
+### Task 3.2: 진입점 3개 (단일 코어 호출 보장)
+- [ ] Node CLI: `bin/commands/migrate.mjs` — argparse + Python 모듈 호출.
+- [ ] Bash 진입점: `scripts/lib/okstra-ctl/cmd-migrate.sh` — thin adapter.
+- [ ] `bin/okstra` dispatcher 에 `migrate` 서브커맨드 등록.
+- [ ] `--dry-run` 기본, `--apply` 로 실제 실행, `--quiet` 로 출력 최소화.
+
+### Task 3.3: 테스트
+- [ ] `tests/test_okstra_migrate.py` — dry-run / apply / 거부 케이스 / git 없는 fallback / CLAUDE.md import 라인 교체 / 빈 `.project-docs/` rmdir / 글로벌 registry 갱신.
+- [ ] `tests-e2e/scenario-XX-migrate.sh` — 실제 fixture 프로젝트 생성 → `okstra setup` → `okstra migrate --apply` → `okstra status` 가 새 path 인식.
+
+---
+
+## Track 4 — 문서 / 릴리스
+
+### Task 4.1: 사용자 문서
+- [ ] `README.md` / `README.kr.md` Quick Start 섹션 — 신규 setup 후 산출물 위치, 기존 사용자용 `npx okstra migrate` 안내.
+- [ ] `docs/kr/architecture.md` Storage model 섹션 — `<PROJECT_ROOT>/.okstra/` 트리.
+- [ ] `docs/kr/cli.md` 에 `okstra migrate` 항목 신규.
+
+### Task 4.2: 저장소 내부 문서
+- [ ] `CLAUDE.md` Three layers / Project layer 섹션 + Artifact-home rule 갱신.
+- [ ] `CHANGES.md` 에 다음 형태의 BREAKING 엔트리 추가:
+
+  > ### feat(migrate)!: 프로젝트 산출물 루트가 `<PROJECT_ROOT>/.okstra/` 로 이전
+  >
+  > - **배경**: 기존 `<PROJECT_ROOT>/.project-docs/okstra/` 는 1) `.project-docs/` 디렉토리가 okstra 외 용도와 섞이기 쉽고, 2) 경로가 길어 사용자 settings/permission 룰에서 자주 잘리며, 3) 같은 문자열이 60+ 파일에 산재해 DRY 위반.
+  > - 변경: 모든 코드 경로 SSOT 가 `.okstra` 로 수렴. `okstra migrate` 명령 신설.
+  > - 사용자 영향: 다음 release + `npx -y okstra@latest install` 후 적용. 이미 okstra 를 쓰고 있는 프로젝트는 **`npx okstra@latest migrate` 한 번 실행**으로 자동 이전 (`git mv` + `CLAUDE.md` import 라인 + `.gitignore` + 글로벌 `~/.okstra/{recent,active}.jsonl` registry 동기화). `okstra migrate` 명령 자체는 v0.x 말까지 유지 후 제거 예정.
+
+---
+
+## Track 5 — 빌드 / 검증 / PR
+
+### Task 5.1: 빌드 / 통합 검증
+- [ ] `npm run build` — runtime/ 21/21 sources synced.
+- [ ] `python3 -m pytest tests/` — 전체 통과.
+- [ ] `bash validators/validate-workflow.sh` 통과.
+- [ ] `bash tests-e2e/scenario-01-record-start-reconcile.sh` 통과 + 신규 migrate scenario 통과.
+- [ ] `node bin/okstra --version`, `node bin/okstra doctor`, `node bin/okstra migrate --dry-run` 정상.
+
+### Task 5.2: PR 분할 (권장)
+- [ ] PR 1 — `refactor(paths): okstra-relative path SSOT 수렴 (Python/Node/Shell)`. Track 1 만. 값은 변하지 않으므로 회귀 위험 0.
+- [ ] PR 2 — `feat(migrate)!: 프로젝트 산출물 루트를 .okstra/ 로 이전 + okstra migrate`. Track 2~4 와 Task 5.1. PR 1 이 머지된 후.
+
+---
+
+## Risks & Gates
+
+- **risk**: `sed` 일괄 교체가 의도치 않은 매칭 (`.project-docs/agents/domain.md` 같은 non-okstra 참조) 까지 건드림. → 패턴을 `\.project-docs/okstra` 로 좁혀 안전.
+- **risk**: `okstra migrate` 가 이미 `.okstra/` 존재하는 프로젝트를 덮어쓸 위험. → 사전 거부 + dry-run 기본.
+- **risk**: 사용자 IDE workspace / 외부 스크립트가 `.project-docs/okstra/` 를 박아두고 있을 가능성. → CHANGES.md + release notes 에 명시.
+- **risk**: PR 1 이 단순 import 추가만으로 끝나도 60+ 파일 diff 가 됨. → 리뷰어가 변경의 의도를 빨리 파악할 수 있도록 PR description 에 "값 변경 0, SSOT 통합만" 명시.
+- **gate**: Track 3 (`okstra migrate`) 의 dry-run 출력이 Track 2 의 새 경로를 정확히 가리켜야 함. Track 2 가 먼저 머지된 base 위에서만 Track 3 작성.
+
+## 견적
+
+| Track | 변경 라인 | 신규 파일 |
+|---|---|---|
+| 1 SSOT 수렴 | ~80 | 0 |
+| 2 값 전환 + sed + fixture | ~200 | 0 |
+| 3 migrate 명령 + 테스트 | ~250 | 4 |
+| 4 문서 | ~60 | 1 (이 plan) |
+| **합계** | **~590 라인** | **5 파일** |