okstra 0.102.1 → 0.102.3

package/docs/superpowers/specs/2026-06-24-manual-user-test-section-design.md

@@ -1,121 +0,0 @@
-# Manual User Test 섹션 설계 (implementation → final-verification 연계)
-
-- 작성일: 2026-06-24
-- 상태: 설계 합의 완료, 구현 계획 대기
-- 범위: okstra 산출물(implementation / final-verification)에 "사람이 직접 손으로 확인하는 테스트 절차"를 담는 섹션 신설
-
-## 1. 배경 — 실재하는 공백과 단절
-
-현재 okstra 산출물에는 "사람이 환경을 띄운 뒤 직접 클릭·확인하는 절차"를 적을 자리가 없다.
-
-- implementation 딜리버러블의 테스트 섹션은 [final-report.template.md:458](../../../templates/reports/final-report.template.md) §5.7.6 Validation Evidence 하나뿐이며, 이는 `Phase | Command | Exit code | Output tail | TDD evidence` 구조의 **자동 검증 증거 전용**이다. 딜리버러블 명세 [_implementation-deliverable.md:19-20](../../../prompts/profiles/_implementation-deliverable.md) 의 Validation evidence / TDD evidence 도 전부 실행 명령 기반이다.
-- planning 의 stage 별 `Acceptance:` 도 "RED 스텝을 PASS 로 뒤집는 같은 테스트 명령"으로 정의된다([implementation-planning.md:73](../../../prompts/profiles/implementation-planning.md)). 사람 절차가 아니다.
-- final-verification 에는 사람 검증에 가까운 입력란이 있으나([final-verification-input.template.md:58](../../../templates/reports/final-verification-input.template.md) `Manual verification notes:`, `:70` `## Acceptance Criteria`), 이는 **검증 단계 입력**일 뿐 implementation 산출물로 흘러드는 "구현 직후의 테스트 절차"가 아니다.
-- 결정적으로 [okstra-container-build/SKILL.md](../../../skills/okstra-container-build/SKILL.md) 는 사람이 만져볼 환경을 docker 로 띄워주지만(`:9` "so a human can poke at the running build"), `prompts/`·`templates/` 어디에서도 참조되지 않는 고립 스킬이다. **환경은 띄워주는데, 띄운 다음 무엇을 어떻게 확인할지를 적어둘 자리가 리포트에 없는 단절** 상태다.
-
-## 2. 목표 / 비목표
-
-### 목표
-- implementation 단계가 "Manual User Test" 절차 **초안**을 산출하고, final-verification 단계가 그 초안을 **실제로 수행해 결과를 확정**한다.
-- 관찰 가능한 변화가 있는 task 에 한해 절차를 요구한다(내부 전용 변경은 면제).
-- `okstra-container-build` 와 리포트를 조건부로 연결해 단절을 해소한다.
-
-### 비목표 (YAGNI)
-- 자동 E2E/통합 테스트 프레임워크 도입 — 기존 자동 검증(§5.7.6 / verifier)은 그대로 둔다.
-- 모든 task 에 일괄 강제 — 관찰 불가 변경까지 N/A 스텁을 양산하지 않는다.
-- docker-compose 가 없는 프로젝트에 컨테이너 사용 강요.
-
-## 3. 설계 결정 (확정)
-
-| 결정 | 선택 | 근거 |
-|---|---|---|
-| 위치 | implementation(초안) ↔ final-verification(실행·확정) **양쪽 연계** | 절차 작성 시점(구현 직후)과 실행 시점(검증)이 다름. 단일 소유자 분리: 초안=implementation, 결과=final-verification |
-| 범위 | 사람이 **관찰 가능한 변화**가 있을 때만 절차, 내부 전용이면 `사용자 테스트 불필요 — <사유>` 한 줄 | allowlist 방식으로 빈 섹션 노이즈 최소화 |
-| container 연계 | **조건부** — `docker-compose.yml` 있으면 `/okstra-container-build` (`okstra container up <task-id>`), 없으면 일반 실행 명령 | 단절 해소 + compose 없는 프로젝트 과임 방지 |
-| 강제 | **validator 구조 강제** — 헤딩 존재 + (절차 또는 면제사유) 중 하나, 빈 스텁 거부 | "관찰 가능 여부"는 의미 판단이라 validator 자동 판정 불가 → 구조만 강제, 적절성은 교차검증 워커가 판단. CLAUDE.md "MUST 는 강제 지점 명시" 충족 |
-
-## 4. 섹션 포맷 명세
-
-### 4.1 implementation 초안 — `## 5.7.x Manual User Test (Draft)`
-관찰 가능한 변화가 있으면 항목별로:
-
-```
-- 대상: <어떤 사용자-facing 동작/기능>
-- 환경 기동:
-  - (docker-compose.yml 있음) `/okstra-container-build` (`okstra container up <task-id>`) → published port 접속
-  - (없음) <프로젝트 실행 명령, 예: npm start / 해당 바이너리 실행>
-- 확인 스텝:
-  1. <사람이 하는 동작>
-  2. ...
-- 기대 결과: <관찰되어야 하는 것>
-```
-
-관찰 불가(내부 전용)면 항목 대신 한 줄:
-```
-사용자 테스트 불필요 — <사유, 예: 내부 리포지토리 메서드 리팩토링, 외부 관찰 동작 변화 없음>
-```
-
-절차 내용은 planning 의 `Acceptance:` 와 implementation 의 실제 diff 를 근거로 작성한다.
-
-### 4.2 final-verification 실행 결과 — `## 5.8.x Manual User Test Results`
-implementation 초안의 각 항목을 수행하고:
-
-```
-- 대상: <초안에서 인용>
-- 수행: <실제로 한 동작 / 띄운 환경>
-- 결과: pass | fail | blocked
-- 관찰값: <실제로 본 것 — 초안의 기대 결과와 대조>
-```
-
-초안이 "사용자 테스트 불필요"였으면 그 사유의 타당성만 재확인(한 줄)하고 넘어간다.
-
-## 5. 데이터 흐름
-
-```
-implementation-planning(Acceptance:)
-        │
-        ▼
-implementation ──→ §5.7.x Manual User Test (Draft)  [초안 단일 소유자]
-        │                       │
-        │         (instruction-set 로 carry)
-        ▼                       ▼
-final-verification ──→ §5.8.x Manual User Test Results  [결과 단일 소유자]
-        ▲
-        └── final-verification-input.template.md 의 Manual verification notes 입력란을 이 흐름과 통합
-```
-
-## 6. 영향 파일별 변경
-
-| 파일 | 변경 |
-|---|---|
-| [prompts/profiles/_implementation-deliverable.md](../../../prompts/profiles/_implementation-deliverable.md) | 딜리버러블 항목에 "Manual user test draft" 추가 — §4.1 포맷, 범위 규칙(관찰 가능 시에만), 조건부 container 안내 지시 |
-| [prompts/profiles/final-verification.md](../../../prompts/profiles/final-verification.md) | 초안을 수행·확정하라는 지시 추가 — §4.2 포맷 |
-| [templates/reports/final-report.template.md](../../../templates/reports/final-report.template.md) | §5.7 에 `Manual User Test (Draft)` 하위섹션 신설(Routing Recommendation 직전 배치, 이후 번호 +1), §5.8 에 `Manual User Test Results` 하위섹션 신설(Routing 직전) |
-| [templates/reports/final-verification-input.template.md](../../../templates/reports/final-verification-input.template.md) | `Manual verification notes:`(:58) 를 implementation 초안 인용 흐름과 통합 |
-| [validators/validate-run.py](../../../validators/validate-run.py) | 기존 §5.7/§5.8 deliverable 섹션 scan 리스트(:1145-1163)에 신설 섹션명 추가 + 빈 스텁/면제사유 거부 체크 |
-| [skills/okstra-container-build/SKILL.md](../../../skills/okstra-container-build/SKILL.md) | 리포트↔container 양방향 포인터 한 줄(이 절차 섹션에서 호출됨을 명시) |
-
-> 구현 후 `npm run build` 로 `runtime/` 동기화 필요. 엔드유저 반영은 `okstra install` 재실행.
-
-## 7. enforcement (validator 체크 명세)
-
-`validators/validate-run.py` 에 다음을 추가한다. 의미 판단(관찰 가능 여부)은 하지 않고 **구조만** 본다. 구현은 기존 메커니즘 위에 얹는다 — §5.7/§5.8 deliverable 섹션 제목 substring scan 리스트([validate-run.py:1145-1163](../../../validators/validate-run.py))에 신설 섹션명을 추가하면 헤딩 누락이 기존 "missing required §5.7" 에러([validate-run.py:1688](../../../validators/validate-run.py))로 잡힌다. 빈 스텁/면제사유 누락 거부는 deprecated stub 거부([validate-run.py:759](../../../validators/validate-run.py))와 동형의 체크를 추가한다.
-
-- **implementation 리포트**: `## 5.7.x Manual User Test (Draft)` 헤딩이 존재해야 한다(MUST). 본문은 다음 중 하나여야 하며, 빈 스텁/플레이스홀더는 거부한다:
-  - 최소 1개의 절차 항목(대상 + 확인 스텝 + 기대 결과), 또는
-  - `사용자 테스트 불필요 — ` 로 시작하는 면제 한 줄(사유 비어 있으면 거부).
-- **final-verification 리포트**: `## 5.8.x Manual User Test Results` 헤딩 존재(MUST). 본문은 결과 항목(결과=pass/fail/blocked) 또는 면제 재확인 한 줄.
-- 절차의 **적절성·정확성**(스텝이 실제 변경을 커버하는지)은 validator 가 아니라 교차검증 워커/컨버전스가 판단한다 — validator 는 구조 게이트일 뿐임을 주석으로 명시.
-
-이로써 "Manual User Test 섹션은 implementation/final-verification 리포트에 필수" 라는 MUST 가 [validate-run.py](../../../validators/validate-run.py) 라는 구체적 강제 지점을 갖는다.
-
-## 8. 테스트 계획
-
-- `tests/contract/` 또는 해당 validator 테스트: (a) 절차 항목 있는 리포트 통과, (b) 헤딩 누락 거부, (c) 빈 스텁 거부, (d) 면제 한 줄(사유 있음) 통과, (e) 면제 사유 비면 거부.
-- `tests/report/` 또는 template 렌더 테스트: 신설 §5.7.x / §5.8.x 헤딩이 implementation / final-verification 렌더에 나타나고 다른 taskType 에는 안 나타나는지.
-- `bash validators/validate-workflow.sh` 통과.
-- 완료 게이트: `npm run check` exit 0.
-
-## 9. 미해결 사항
-
-없음. (섹션 정확 번호는 구현 시 §5.7/§5.8 재배치로 확정 — Routing Recommendation 을 항상 마지막으로 유지)

package/docs/superpowers/specs/2026-06-24-okstra-container-build-rename-design.md

@@ -1,110 +0,0 @@
-# okstra-container-build 스킬 rename 설계
-
-- 작성일: 2026-06-24
-- 상태: 설계 합의 완료, 구현 계획 대기
-- 범위: 공개 agent skill 이름을 `okstra-container` 에서 `okstra-container-build` 로 변경
-
-## 1. 배경
-
-현재 컨테이너 기능은 세 표면이 분리되어 있다.
-
-- 공개 스킬 이름과 설치 대상은 `src/lib/skill-catalog.mjs` 의 `USER_SKILL_NAMES` 가 정본이다([skill-catalog.mjs:7](../../../src/lib/skill-catalog.mjs)).
-- 플러그인 보조 채널은 `.claude-plugin/plugin.json` 의 `skills` 배열을 사용한다([plugin.json:4](../../../.claude-plugin/plugin.json)).
-- 실제 CLI 명령은 `okstra container ...` 이며, Node shim 이 Python `okstra_ctl.container` 로 위임한다([container.mjs:3](../../../src/commands/inspect/container.mjs), [container.py:927](../../../scripts/okstra_ctl/container.py)).
-
-사용자 요청은 스킬 이름을 `okstra-container-build` 로 바꾸는 것이다. 따라서 slash-command / skill discovery 표면은 새 이름으로 바꾸되, 안정된 CLI 명령과 런타임 리소스 이름은 유지한다.
-
-## 2. 목표 / 비목표
-
-### 목표
-
-- 설치되는 공개 스킬과 slash command 를 `/okstra-container-build` 로 바꾼다.
-- 신규 설치와 업그레이드 모두에서 옛 `/okstra-container` 가 남지 않게 한다.
-- README, architecture, AI manual, phase prompt 의 사용자-facing 안내를 새 스킬명으로 맞춘다.
-- `okstra container` CLI 와 Python entrypoint 는 유지해 기존 자동화와 테스트 표면을 흔들지 않는다.
-
-### 비목표
-
-- `okstra container` CLI command rename.
-- `okstra-container-<slug>` tmux session prefix rename.
-- docker compose 생성 기능 추가. `build` 는 스킬 이름의 suffix 일 뿐, 기존처럼 프로젝트의 `docker-compose.yml` 을 재사용한다.
-- 과거 changelog / 과거 구현 계획 문서의 역사적 문구 전면 수정.
-
-## 3. 검토한 접근
-
-| 접근 | 판단 | 이유 |
-|---|---|---|
-| A. 공개 스킬명만 rename, CLI/runtime 이름 유지 | 선택 | 사용자 요청을 만족하면서 `okstra container` 자동화, Python argparse, tmux session 추적을 보존한다. |
-| B. CLI 도 `okstra container-build` 로 rename | 제외 | `src/commands/inspect/container.mjs` 와 `scripts/okstra_ctl/container.py` 의 명령 계약까지 깨져 범위가 커진다. |
-| C. 새 스킬을 추가하고 옛 `okstra-container` alias 를 유지 | 제외 | 설치 후 slash command 가 두 개 보인다. 사용자 요청이 rename 이므로 옛 이름은 upgrade 시 prune 해야 한다. |
-
-## 4. 설계 결정
-
-| 결정 | 선택 | 근거 |
-|---|---|---|
-| 스킬 정본 | `USER_SKILL_NAMES` 의 `okstra-container` 를 `okstra-container-build` 로 교체 | installer 와 plugin sync 테스트가 이 목록을 기준으로 맞물린다([install.mjs:631](../../../src/commands/lifecycle/install.mjs), [skill-catalog.test.mjs:14](../../../tests-js/skill-catalog.test.mjs)). |
-| 원천 디렉터리 | `skills/okstra-container/` 를 `skills/okstra-container-build/` 로 이동 | install copy/link mode 모두 `<name>/SKILL.md` 디렉터리명을 사용한다([install.mjs:631](../../../src/commands/lifecycle/install.mjs), [install.mjs:653](../../../src/commands/lifecycle/install.mjs)). |
-| frontmatter | `name: okstra-container-build` | agent skill discovery 는 frontmatter 이름을 사용자 표면으로 노출한다. |
-| CLI | `okstra container <up|status|logs|stop-watcher|down>` 유지 | CLI shim 과 Python parser 는 컨테이너 런타임 API 이름이며 스킬명과 독립적이다([container.mjs:3](../../../src/commands/inspect/container.mjs), [container.py:927](../../../scripts/okstra_ctl/container.py)). |
-| runtime session prefix | `okstra-container-<slug>` 유지 | tmux/docker trace 리소스 이름이며 테스트가 고정한다([ids.py:93](../../../scripts/okstra_ctl/ids.py), [test_container_session_name.py:14](../../../tests/container/test_container_session_name.py)). |
-| upgrade cleanup | 옛 `okstra-container` 를 exact-name prune 대상에 추가 | 설치는 새 스킬을 복사하지만 기존 skill home 의 옛 디렉터리를 자동 삭제하지 않는다([install.mjs:669](../../../src/commands/lifecycle/install.mjs)). |
-
-## 5. 영향 파일
-
-### 소스 / 설치 계약
-
-| 파일 | 변경 |
-|---|---|
-| `skills/okstra-container/SKILL.md` | 디렉터리명을 `skills/okstra-container-build/` 로 변경하고 frontmatter `name` 갱신. 본문에서 slash-command 명칭만 새 이름으로 맞추고 `okstra container ...` CLI 예시는 유지. |
-| `src/lib/skill-catalog.mjs` | `USER_SKILL_NAMES` 에서 `okstra-container-build` 로 교체. `OBSOLETE_INTERNAL_SKILL_NAMES` 는 `OBSOLETE_SKILL_NAMES` 로 재명명하고, 옛 공개 스킬 `okstra-container` 를 같은 exact-name prune 목록에 추가한다. |
-| `.claude-plugin/plugin.json` | `./skills/okstra-container-build` 로 교체. |
-| `src/commands/lifecycle/uninstall.mjs` | fallback skill names 에 `okstra-container-build` 를 포함하고, 옛 `okstra-container` 도 fallback cleanup 대상에 유지한다. |
-| `tools/build.mjs` | 코드 변경 없음. `skills/` sync 로 새 디렉터리가 `runtime/skills/okstra-container-build` 로 반영되는지 build 로 검증. |
-
-### 문서 / 프롬프트
-
-| 파일군 | 변경 |
-|---|---|
-| `README.md`, `README.kr.md` | slash command 표를 `/okstra-container-build` 로 갱신. |
-| `docs/kr/architecture.md`, `docs/project-structure-overview.md` | 공개 스킬 7종 목록과 skill role 표를 새 이름으로 갱신. CLI `container` 설명은 유지하되 "for the okstra-container-build skill" 로 조정. |
-| `docs/for-ai/README.md`, `docs/for-ai/skills/okstra-container.md` | AI manual 파일명을 `okstra-container-build.md` 로 바꾸고 라우팅 표를 새 이름으로 갱신. |
-| `docs/for-ai/skills/okstra-inspect.md` | "container 는 별도 스킬" 링크를 새 manual 로 갱신. |
-| `prompts/profiles/_implementation-deliverable.md`, `prompts/profiles/final-verification.md` | 사람이 실행할 스킬명은 `/okstra-container-build`, 실제 CLI 명령 예시는 `okstra container up ...` 로 표현해 혼동을 줄인다. |
-| `docs/kr/container.md` | CLI 레퍼런스는 제목과 명령을 유지하고, 단일 진입점 bullet 의 스킬명만 `/okstra-container-build` 로 갱신. |
-
-### 그대로 둘 파일군
-
-- `CHANGES.md`, `CHANGELOG.md`: 과거 릴리스 기록이므로 기존 `okstra-container` 항목을 역사로 보존한다. 이번 변경은 새 항목만 추가한다.
-- `docs/superpowers/plans/2026-06-21-okstra-container-local-user-test.md`, `docs/superpowers/specs/2026-06-21-okstra-container-local-user-test-design.md`: 과거 기능 도입 당시 설계/계획 문서라 전체 rewrite 하지 않는다. 현재 문서로 rename 결정을 보완한다.
-- `tests/container/*` 의 `okstra-container-<slug>` 기대값: 런타임 session prefix 검증이므로 유지한다.
-
-## 6. 업그레이드 동작
-
-문제: 현재 install 은 `USER_SKILL_NAMES` 를 설치한 뒤 manifest 를 새 목록으로 쓴다. 하지만 이미 `~/.claude/skills/okstra-container` 또는 `~/.agent/skills/okstra-container` 가 있으면 새 install 만으로 옛 디렉터리가 삭제되지 않는다.
-
-설계:
-
-1. old public skill 이름 `okstra-container` 를 exact-name prune 대상에 넣는다.
-2. `installSkillsCopy()` / `installSkillsLink()` 의 prune 단계에서 old dir 을 제거한다.
-3. wildcard `okstra-*` 삭제는 금지한다. 기존 obsolete cleanup 도 exact-name 방식이다([install.mjs:666](../../../src/commands/lifecycle/install.mjs)).
-4. uninstall fallback 은 manifest 가 없는 오래된 설치도 정리할 수 있게 old/new 이름을 모두 포함한다.
-
-## 7. 테스트 계획
-
-- `node --test tests-js/skill-catalog.test.mjs`: plugin manifest 와 `USER_SKILL_NAMES` 순서 동기화.
-- `node --test tests-js/install-runtime.test.mjs`: 새 스킬이 Claude/Codex skill home 에 설치되고 manifest 에 기록되는지 확인. 추가 회귀 테스트로 old `okstra-container` 디렉터리를 seed 한 뒤 install 이 prune 하는지 검증.
-- `node --test tests-js/doctor-runtime.test.mjs`: 비필수 container skill 이 `REQUIRED_SKILLS` 에 들어가지 않는다는 테스트명을 새 이름으로 갱신.
-- `python3 -m pytest tests/contract/test_docs_runtime_contract.py`: plugin manifest 계약과 docs runtime 계약 갱신.
-- `npm run build`: `runtime/skills/okstra-container-build/SKILL.md` 생성과 `runtime/skills/okstra-container/` 부재 확인.
-- 최종 게이트: `npm run check`.
-
-## 8. 사용자 영향
-
-- 새 설치와 재설치 후 스킬 호출명은 `/okstra-container-build` 가 된다.
-- 기존 `okstra container up/status/logs/stop-watcher/down` CLI 는 그대로 동작한다.
-- 기존 tmux watcher/session 이름과 docker trace 라벨은 유지된다.
-- 이전 `/okstra-container` 는 upgrade install 과정에서 제거된다.
-
-## 9. 미해결 사항
-
-없음.