okstra 0.102.1 → 0.102.3

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

@@ -1,203 +0,0 @@
-# Manual User Test Section 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:** implementation 리포트가 사람이 손으로 확인하는 테스트 절차 초안을 산출하고, final-verification 리포트가 그 초안을 수행·확정하도록, 양쪽 산출물에 "Manual User Test" 섹션을 신설한다.
-
-**Architecture:** 기존 §5.7/§5.8 deliverable 섹션과 동형(data-driven Jinja 섹션 + 영어 제목 하드코딩 + i18n 라벨/빈상태 + validate-run.py substring 강제). implementation 이 `implementation.manualUserTest` 초안을, final-verification 이 `finalVerification.manualUserTest` 결과를 채운다.
-
-**Tech Stack:** Jinja 템플릿(final-report.template.md), Python validator(validate-run.py), JSON i18n(en/ko), markdown 프로파일(prompts/), pytest.
-
-## Global Constraints
-
-- 산출물은 한/영 양 언어로 렌더된다 — 섹션 **제목은 영어 하드코딩**(기존 §5.7.x 와 동일), 라벨/빈상태는 `t("manualUserTest.*")` i18n 키로. 영어 렌더에 한글이 들어가면 `tests/report/test_template_no_korean_glyphs.py` 가 fail.
-- validator 강제는 **섹션 제목 substring 존재**만 본다(기존 컨벤션). 절차 내용의 적절성은 교차검증 워커/컨버전스가 판단.
-- 범위 규칙(프로파일 지시): 사람이 **관찰 가능한 변화**가 있을 때만 절차 항목, 내부 전용이면 면제 한 줄(`applicable=false` + `exemptionReason`).
-- container 연계는 **조건부** — `docker-compose.yml` 있으면 `/okstra-container-build` (`okstra container up <task-id>`), 없으면 일반 실행 명령.
-- 수정 후 `npm run build` 로 `runtime/` 동기화, 완료 게이트는 `npm run check` exit 0.
-- `runtime/` 는 빌드 산출물 — 직접 편집 금지. 소스는 `scripts/`,`templates/`,`prompts/`,`validators/`.
-
----
-
-### Task 1: i18n 라벨/빈상태 키 추가
-
-**Files:**
-- Modify: `templates/reports/i18n/en.json`
-- Modify: `templates/reports/i18n/ko.json`
-
-**Interfaces:**
-- Produces: `t("manualUserTest.environmentSetup")`, `.steps`, `.expectedResult`, `.notApplicable`, `.performed`, `.result`, `.observed` — Task 2·3 템플릿이 소비.
-
-- [ ] **Step 1:** `en.json` 의 기존 최상위 그룹(예: `emptyState`) 구조를 Read 로 확인하고, 동일 nesting 으로 `manualUserTest` 그룹 추가:
-  ```json
-  "manualUserTest": {
-    "environmentSetup": "Environment",
-    "steps": "Steps",
-    "expectedResult": "Expected result",
-    "notApplicable": "Manual user test not required",
-    "performed": "Performed",
-    "result": "Result",
-    "observed": "Observed"
-  }
-  ```
-- [ ] **Step 2:** `ko.json` 에 같은 키로 한국어 값 추가:
-  ```json
-  "manualUserTest": {
-    "environmentSetup": "환경 기동",
-    "steps": "확인 스텝",
-    "expectedResult": "기대 결과",
-    "notApplicable": "사용자 테스트 불필요",
-    "performed": "수행",
-    "result": "결과",
-    "observed": "관찰값"
-  }
-  ```
-- [ ] **Step 3:** 키 정합성 테스트 실행. Run: `python3 -m pytest tests/report/test_report_language_i18n.py -q` (en/ko 키 집합 일치 검증이 있으면 통과해야 함). Expected: PASS.
-- [ ] **Step 4:** Commit. `git add templates/reports/i18n/en.json templates/reports/i18n/ko.json && git commit -m "feat(report): add manualUserTest i18n labels"`
-
----
-
-### Task 2: implementation 측 — 템플릿 섹션 + validator 강제 + fixture
-
-**Files:**
-- Modify: `templates/reports/final-report.template.md:485` (§5.7.9 Routing → 5.7.10, 앞에 5.7.9 신설)
-- Modify: `validators/validate-run.py:1146-1156` (`IMPLEMENTATION_REQUIRED_SECTIONS`)
-- Modify: implementation data fixture (Task 의 Step 1 에서 `grep -rl "validationEvidence" tests/ templates/` 로 위치 확정)
-- Test: `tests/report/test_render_final_report.py`, `tests/contract/` validator 테스트
-
-**Interfaces:**
-- Consumes: `t("manualUserTest.*")` (Task 1).
-- Produces: 렌더된 본문에 `Manual User Test` substring; data 필드 `implementation.manualUserTest = {applicable: bool, exemptionReason: str|null, items: [{target, environmentSetup, steps: [str], expectedResult}]}`.
-
-- [ ] **Step 1: 실패 테스트 — 섹션 누락 거부.** validator 테스트에 추가:
-  ```python
-  def test_implementation_report_requires_manual_user_test_section():
-      # "Manual User Test" 헤딩이 없는 implementation 리포트 본문은 거부된다
-      failures = []
-      _check_required_deliverable_sections("implementation", BODY_WITHOUT_MANUAL, failures)
-      assert any("Manual User Test" in f for f in failures)
-  ```
-  (실제 호출부는 validate-run.py 의 섹션 체크 함수명에 맞춤 — Step 에서 `grep -n "IMPLEMENTATION_REQUIRED_SECTIONS" validators/validate-run.py` 로 확인)
-- [ ] **Step 2:** Run 해서 FAIL 확인(아직 "Manual User Test" 가 리스트에 없어 거부 안 됨). Expected: FAIL.
-- [ ] **Step 3: validator 리스트에 추가.** `IMPLEMENTATION_REQUIRED_SECTIONS` 끝(`"Routing Recommendation",` 앞)에 `"Manual User Test",` 추가.
-- [ ] **Step 4:** Run 해서 PASS.
-- [ ] **Step 5: 템플릿 섹션 신설.** `### 5.7.9 Routing Recommendation` 을 `### 5.7.10` 으로 바꾸고, 그 앞에 삽입:
-  ```jinja
-  ### 5.7.9 Manual User Test (Draft)
-
-  {% if implementation.manualUserTest.applicable -%}
-  {% for item in implementation.manualUserTest.items %}
-  - **{{ item.target | mdcell }}**
-    - {{ t("manualUserTest.environmentSetup") }}: {{ item.environmentSetup }}
-    - {{ t("manualUserTest.steps") }}:
-  {% for step in item.steps %}    {{ loop.index }}. {{ step }}
-  {% endfor %}  - {{ t("manualUserTest.expectedResult") }}: {{ item.expectedResult }}
-  {% endfor %}
-  {%- else -%}
-  - {{ t("manualUserTest.notApplicable") }}: {{ implementation.manualUserTest.exemptionReason }}
-  {%- endif %}
-
-  ```
-- [ ] **Step 6: fixture 보강.** implementation 렌더 fixture data 에 `manualUserTest` 필드 추가(applicable=true 항목 1개). 누락 시 Jinja `undefined.applicable` 로 렌더 실패하므로 필수.
-- [ ] **Step 7: 렌더 테스트.** `test_render_final_report.py` 에 implementation 렌더 결과가 `"Manual User Test (Draft)"` 와 항목 내용을 담고, 양 언어 렌더가 통과하는지 단언. Run: `python3 -m pytest tests/report/test_render_final_report.py tests/report/test_template_full_render_both_langs.py tests/report/test_template_no_korean_glyphs.py -q`. Expected: PASS.
-- [ ] **Step 8: Commit.** `git add templates/reports/final-report.template.md validators/validate-run.py tests/ <fixture> && git commit -m "feat(report): add Manual User Test (Draft) section to implementation deliverables"`
-
----
-
-### Task 3: implementation 프로파일 — 초안 작성 지시 + container 조건부 + report-writer 데이터 지시
-
-**Files:**
-- Modify: `prompts/profiles/_implementation-deliverable.md:33` (Routing recommendation 항목 앞에 새 deliverable 항목)
-- Modify: `prompts/lead/report-writer.md` (data 필드 채우기 지시 — `grep -n "validationEvidence" prompts/lead/report-writer.md` 로 인접 위치 확정)
-
-**Interfaces:**
-- Consumes: Task 2 의 `implementation.manualUserTest` 데이터 형태.
-
-- [ ] **Step 1:** `_implementation-deliverable.md` 의 `- **Validation evidence**` 와 `- **Routing recommendation ...**` 사이에 항목 추가:
-  ```markdown
-  - **Manual user test draft**: 사람이 관찰 가능한 변화(UI/API/CLI/산출물 등)가 있으면 각 대상마다 `대상 / 환경 기동 / 확인 스텝 / 기대 결과` 를 §5.7.9 에 적는다. 환경 기동은 프로젝트에 `docker-compose.yml` 이 있으면 `/okstra-container-build` (`okstra container up <task-id>`, published port 접속), 없으면 프로젝트 실행 명령(예: `npm start`). 관찰 가능한 변화가 없으면 항목 대신 `사용자 테스트 불필요 — <사유>` 한 줄만 적는다(`applicable=false`). 절차는 승인 plan 의 `Acceptance:` 와 이 run 의 실제 diff 를 근거로 작성한다.
-  ```
-- [ ] **Step 2:** self-review 체크리스트(`_implementation-deliverable.md:38-48`)에 한 항목 추가: "Manual user test — 관찰 가능한 변화가 있는데 §5.7.9 가 면제 한 줄로 처리되지 않았는지 확인".
-- [ ] **Step 3:** `report-writer.md` 의 deliverable 데이터 작성 지시에 `implementation.manualUserTest` 필드(applicable/exemptionReason/items) 채우는 한 줄 추가.
-- [ ] **Step 4:** 프로파일은 코드가 아니므로 직접 테스트 없음 — `bash validators/validate-workflow.sh` 로 phase contract 깨지지 않는지 확인. Expected: PASS.
-- [ ] **Step 5: Commit.** `git add prompts/profiles/_implementation-deliverable.md prompts/lead/report-writer.md && git commit -m "feat(report): instruct implementation lead to draft manual user test steps"`
-
----
-
-### Task 4: final-verification 측 — 템플릿 결과 섹션 + validator 강제 + fixture
-
-**Files:**
-- Modify: `templates/reports/final-report.template.md:568` (§5.8.7 Routing → 5.8.8, 앞에 5.8.7 신설)
-- Modify: `validators/validate-run.py:1159-1167` (`FINAL_VERIFICATION_REQUIRED_SECTIONS`)
-- Modify: final-verification data fixture
-- Test: 위 렌더/validator 테스트
-
-**Interfaces:**
-- Consumes: `t("manualUserTest.*")`.
-- Produces: 본문에 `Manual User Test` substring; `finalVerification.manualUserTest = {applicable, exemptionReaffirm: str|null, results: [{target, performed, result, observed}]}` (`result` ∈ pass|fail|blocked).
-
-- [ ] **Step 1: 실패 테스트.** final-verification 변형으로 Task 2 Step 1 과 동일하게 "Manual User Test" 누락 거부 테스트 추가. Run → FAIL.
-- [ ] **Step 2:** `FINAL_VERIFICATION_REQUIRED_SECTIONS` 의 `"Routing Recommendation",` 앞에 `"Manual User Test",` 추가. Run → PASS.
-- [ ] **Step 3: 템플릿 섹션.** `### 5.8.7 Routing Recommendation` → `### 5.8.8`, 앞에 삽입:
-  ```jinja
-  ### 5.8.7 Manual User Test Results
-
-  {% if finalVerification.manualUserTest.applicable -%}
-  | {{ t("manualUserTest.performed") }} | {{ t("manualUserTest.result") }} | {{ t("manualUserTest.observed") }} |
-  |---|---|---|
-  {% for row in finalVerification.manualUserTest.results -%}
-  | {{ row.target | mdcell }} — {{ row.performed | mdcell }} | `{{ row.result | mdcell }}` | {{ row.observed | mdcell }} |
-  {% endfor %}
-  {%- else -%}
-  - {{ t("manualUserTest.notApplicable") }}: {{ finalVerification.manualUserTest.exemptionReaffirm }}
-  {%- endif %}
-
-  ```
-- [ ] **Step 4: fixture 보강.** final-verification 렌더 fixture 에 `manualUserTest` 필드(applicable=true, results 1행).
-- [ ] **Step 5: 렌더/양언어 테스트.** Run: `python3 -m pytest tests/report/test_render_final_report.py tests/report/test_final_report_stage_reports_render.py tests/report/test_template_full_render_both_langs.py tests/report/test_template_no_korean_glyphs.py -q`. Expected: PASS.
-- [ ] **Step 6: Commit.** `git add templates/reports/final-report.template.md validators/validate-run.py tests/ <fixture> && git commit -m "feat(report): add Manual User Test Results section to final-verification deliverables"`
-
----
-
-### Task 5: final-verification 프로파일 + 입력 템플릿 통합
-
-**Files:**
-- Modify: `prompts/profiles/final-verification.md` (deliverable/output 섹션 — `grep -n "deliverable\|Expected output\|Routing" prompts/profiles/final-verification.md` 로 위치 확정)
-- Modify: `templates/reports/final-verification-input.template.md:58` (`Manual verification notes:`)
-
-**Interfaces:**
-- Consumes: implementation 의 §5.7.9 초안(Source Implementation Report 경유로 참조).
-
-- [ ] **Step 1:** `final-verification.md` 에 지시 추가: "Source implementation report 의 §5.7.9 Manual User Test (Draft) 각 항목을 실제로 수행하고 §5.8.7 에 `결과(pass/fail/blocked) + 관찰값`을 기록한다. 초안이 면제였으면 사유 타당성만 한 줄로 재확인한다."
-- [ ] **Step 2:** `final-verification-input.template.md:58` 를 다음으로 교체:
-  ```markdown
-  - Manual verification notes (source implementation report §5.7.9 Manual User Test Draft 를 수행한 결과):
-  ```
-- [ ] **Step 3:** `bash validators/validate-workflow.sh` 통과 확인.
-- [ ] **Step 4: Commit.** `git add prompts/profiles/final-verification.md templates/reports/final-verification-input.template.md && git commit -m "feat(report): instruct final-verification to execute manual user test draft"`
-
----
-
-### Task 6: okstra-container-build ↔ 리포트 양방향 포인터
-
-**Files:**
-- Modify: `skills/okstra-container-build/SKILL.md`
-
-- [ ] **Step 1:** SKILL.md 의 `up` 성공 안내(published ports) 부근에, 무엇을 확인할지는 implementation 리포트 §5.7.9 Manual User Test (Draft) 를 따르라는 한 줄 추가. (단절 해소 — 환경 기동 후 절차 출처 명시)
-- [ ] **Step 2:** Commit. `git add skills/okstra-container-build/SKILL.md && git commit -m "docs(container): point to report Manual User Test section for what to verify"`
-
----
-
-### Task 7: 빌드 + 전체 검증
-
-- [ ] **Step 1:** `npm run build` → `runtime/` 동기화. Expected: BUILD_EXIT=0.
-- [ ] **Step 2:** `npm run check` 전체. Expected: exit 0 (Python + JS + validators).
-- [ ] **Step 3:** runtime 반영 확인: `grep -rl "Manual User Test" runtime/templates runtime/validators` 가 매치.
-- [ ] **Step 4: Commit**(빌드 산출물은 gitignore 라 커밋 없음 — 소스 커밋이 이미 1~6 에서 됨). 푸시는 사용자 지시 시에만.
-
-## Self-Review
-
-**1. Spec coverage:** spec §3 결정 4개 → Task 2/4(위치·강제), Task 3/5(범위·초안/실행), Task 6(container 조건부 연계). spec §6 영향파일 6개 → Task 1~6 에 모두 매핑. spec §8 테스트계획 → Task 2/4 의 렌더·validator 테스트, Task 7 의 validate-workflow + npm run check. 갭 없음.
-**2. Placeholder scan:** fixture 파일 경로·일부 프로파일 위치는 "구현 시 grep 로 확정" 으로 명시(데이터 부족 구간) — 그 외 코드/텍스트는 실제 내용 제공.
-**3. Type consistency:** `implementation.manualUserTest`(items) ↔ `finalVerification.manualUserTest`(results) 필드명 Task 2/3/4 간 일치. i18n 키 `manualUserTest.*` Task 1 정의 ↔ Task 2/4 소비 일치.
-**4. 설계 조정:** spec 의 "빈 스텁 거부" 는 기존 validator 컨벤션(제목 substring 강제)에 맞춰 "제목 강제 + 프로파일 내용 규칙 + self-review" 로 단순화(Global Constraints 에 명시).