okstra 0.102.2 → 0.102.4

package/docs/superpowers/plans/2026-06-23-implementation-step-commit-granularity.md

@@ -1,274 +0,0 @@
-# implementation 커밋·step 입도 완화 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` executor 의 test/impl 분리 커밋을 한 커밋으로 병합(A)하고, planning step 의 입도 정의를 격상하며 step 캡을 6→8 로 올린다(B).
-
-**Architecture:** okstra 의 phase 동작은 `prompts/profiles/*.md`(LLM 자연어 계약)와 `validators/*.py`(기계 강제)로 나뉜다. 캡의 enforcement SSOT 는 validator 한 곳, 프로파일·문서의 `≤ 8` 문구는 그 미러다. 커밋 정책은 자연어 프로파일에만 존재한다.
-
-**Tech Stack:** Python 3 (validator + pytest), Markdown 프로파일/문서, Node 빌드(`npm run build` → `runtime/` 동기화, `npm run check` CI).
-
-설계 출처: [`docs/superpowers/specs/2026-06-23-implementation-step-commit-granularity-design.md`](../specs/2026-06-23-implementation-step-commit-granularity-design.md).
-
-## Global Constraints
-
-- **최소 변경**: planning 의 `RED:` / `GREEN:` step 토큰, validator S10c/S10d, TDD discipline 자체는 변경 금지.
-- **enforcement SSOT**: step 캡 숫자는 validator 모듈 상수 `HARD_STEP_CAP = 8` 한 곳에만 코드로 정의. 프로파일·문서는 자연어 미러.
-- **pre-1.0**: 호환 셔임 없음. 단 이번 변경은 기존 산출 plan(≤6 step)을 깨지 않음(캡 완화는 단조 확장).
-- **`runtime/` 직접 수정 금지** — build output. 소스(`prompts/`, `validators/`)만 수정.
-- **커밋 메시지**: Conventional Commits, AI 트레일러 금지. 동시 세션 환경이므로 amend 금지 — 항상 새 커밋.
-- **완료 게이트**: 마지막에 `npm run check` exit 0 확인(test:js 실패 시 test:py 안 돎).
-
----
-
-### Task 1: B — step 캡 상수화 + 경계 검증 (validator)
-
-**Files:**
-- Modify: `validators/validate-implementation-plan-stages.py` (상수 추가 + S5 검사)
-- Modify: `tests/contract/test_validate_implementation_plan_stages.py` (8-step 통과 회귀 테스트 추가)
-- Modify: `tests/fixtures/plans/invalid_step_overflow.md` (7-step → 9-step)
-
-**Interfaces:**
-- Produces: 모듈 상수 `HARD_STEP_CAP = 8` — Task 2 의 프로파일·문서 `≤ 8` 문구가 이 값을 미러.
-- Consumes: 기존 헬퍼 `_one_stage_plan(slice_line, accept_line, steps, ...)`(steps = `(action, expected)` 리스트, step-count 셀 자동), `_run_validator_path(plan_path)`, `tmp_path` fixture.
-
-- [ ] **Step 1: 8-step 통과 회귀 테스트 추가 (먼저 실패하는 테스트)**
-
-`tests/contract/test_validate_implementation_plan_stages.py` 의 `test_step_overflow_rejected`(현재 line 80 부근) 바로 아래에 추가:
-
-```python
-def test_eight_steps_allowed(tmp_path):
-    """캡 상향(6→8): 8 step 단일 stage 는 S5 를 발화하지 않는다."""
-    steps = [("RED: 실패 테스트 작성", "FAIL")] + [
-        (f"GREEN: 구현 {i}", "PASS") for i in range(2, 9)
-    ]  # 총 8 step
-    body = _one_stage_plan(
-        "Slice value: bar 가 동작한다",
-        "Acceptance: pytest -k bar PASS",
-        steps,
-    )
-    plan = tmp_path / "eight_steps.md"
-    plan.write_text(body, encoding="utf-8")
-    r = _run_validator_path(plan)
-    assert r.returncode == 0, r.stderr
-```
-
-- [ ] **Step 2: 새 테스트 실행 → 실패 확인 (RED)**
-
-Run: `python3 -m pytest tests/contract/test_validate_implementation_plan_stages.py::test_eight_steps_allowed -v`
-Expected: FAIL — 현재 validator 는 `steps > 6` 이라 8-step 이 S5 로 거부되어 `returncode == 1`.
-
-- [ ] **Step 3: validator 에 `HARD_STEP_CAP = 8` 도입 + S5 교체 (GREEN)**
-
-`validators/validate-implementation-plan-stages.py` 상수 영역(현재 line 23 `REQUIRED_SUBSECTIONS` 위)에 추가:
-
-```python
-HARD_STEP_CAP = 8
-```
-
-`_check_each_stage_section` 의 S5 블록(현재 line 167-171)을 교체:
-
-```python
-        # S5: effective step count
-        steps = _count_effective_steps(section)
-        if steps > HARD_STEP_CAP:
-            errs.append(ValidationError("S5", s.stage_number,
-                f"effective step count {steps} exceeds {HARD_STEP_CAP}"))
-```
-
-`_check_slice_tdd` docstring(현재 line 199-210) 중 step 설명이 숫자 `6` 을 언급하면 `8` 로 정합(현재 docstring 에 `6` 직접 언급 없음 — 있으면만 수정).
-
-- [ ] **Step 4: 새 테스트 통과 확인 (GREEN)**
-
-Run: `python3 -m pytest tests/contract/test_validate_implementation_plan_stages.py::test_eight_steps_allowed -v`
-Expected: PASS
-
-- [ ] **Step 5: 기존 overflow fixture 를 9-step 으로 확장**
-
-캡이 8 이 되어 7-step fixture 는 더 이상 S5 를 발화하지 않으므로 `test_step_overflow_rejected` 가 깨진다. `tests/fixtures/plans/invalid_step_overflow.md` 의 Stage Map step-count 셀과 Stepwise 표를 9-step 으로:
-
-Stage Map 행(현재 `| 1 | overloaded stage | (none) | 7 | src/foo.ts |`)의 `7` → `9`:
-
-```
-| 1 | overloaded stage | (none) | 9 | src/foo.ts |
-```
-
-Stepwise 표 마지막(현재 `| 7 | step seven | g.ts | cmd | OK |`) 뒤에 2행 추가:
-
-```
-| 8 | step eight | h.ts | cmd | OK |
-| 9 | step nine | i.ts | cmd | OK |
-```
-
-- [ ] **Step 6: 전체 validator 테스트 통과 확인**
-
-Run: `python3 -m pytest tests/contract/test_validate_implementation_plan_stages.py -v`
-Expected: PASS (전체). 특히 `test_step_overflow_rejected`(9>8 로 S5 발화)와 `test_eight_steps_allowed` 둘 다 PASS.
-
-- [ ] **Step 7: 커밋**
-
-```bash
-git add validators/validate-implementation-plan-stages.py tests/contract/test_validate_implementation_plan_stages.py tests/fixtures/plans/invalid_step_overflow.md
-git commit -m "feat(validate): step 캡 6→8 상향 및 HARD_STEP_CAP 상수화"
-```
-
----
-
-### Task 2: B — step 입도 declaration 미러 (프로파일·문서)
-
-**Files:**
-- Modify: `prompts/profiles/implementation-planning.md` (line 60, 81, 88, 89, 130)
-- Modify: `docs/kr/architecture.md` (line 341)
-- Modify: `docs/project-structure-overview.md` (line 276)
-
-**Interfaces:**
-- Consumes: Task 1 의 `HARD_STEP_CAP = 8` — 아래 문구의 `8` 은 그 값의 자연어 미러.
-
-문서 변경이라 단위 테스트 없음 — 각 변경 후 grep 으로 잔여 구표현이 없는지 확인한다.
-
-- [ ] **Step 1: `implementation-planning.md` step 정의·캡 격상**
-
-line 81 의 substring 교체:
-- `**Effective row count ≤ 6** (excluding header / divider / blank). Each step is one action completable in 2–5 minutes;`
-  → `**Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change (시간 하한 없음; 함께 바뀌는 여러 파일을 포함할 수 있다);`
-
-line 60 의 `the per-stage effective step count (≤6)` → `(≤8)`.
-
-line 88 의 `(b) effective steps would exceed 6` → `(b) effective steps would exceed 8`.
-
-line 89 의 `overrides the ≤6-step merging allowance` → `overrides the ≤8-step merging allowance`.
-
-line 130 의 `reject the draft if any stage exceeds 6` → `reject the draft if any stage exceeds 8`.
-
-- [ ] **Step 2: 문서 2곳 미러**
-
-`docs/kr/architecture.md` line 341 의 `각 stage 의 effective step ≤ 6` → `각 stage 의 effective step ≤ 8`.
-
-`docs/project-structure-overview.md` line 276 의 `stage 당 step ≤ 6 등` → `stage 당 step ≤ 8 등`.
-
-- [ ] **Step 3: 잔여 구표현 grep 검증**
-
-Run:
-```bash
-grep -rn "≤ *6\|≤6-step\|exceed 6\|exceeds 6\|2.5 min\|2–5 min\|completable in 2" prompts/profiles/implementation-planning.md docs/kr/architecture.md docs/project-structure-overview.md
-```
-Expected: 출력 없음(exit 1). 남는 게 있으면 해당 줄을 추가 수정.
-
-- [ ] **Step 4: 커밋**
-
-```bash
-git add prompts/profiles/implementation-planning.md docs/kr/architecture.md docs/project-structure-overview.md
-git commit -m "docs(planning): step 입도 정의 격상 및 캡 ≤8 미러"
-```
-
----
-
-### Task 3: A — executor 커밋 병합 정책
-
-**Files:**
-- Modify: `prompts/profiles/_implementation-executor.md` (line 29, 30-31, 74)
-- Modify: `prompts/profiles/_implementation-deliverable.md` (line 14, 20, 38)
-
-문서 변경이라 단위 테스트 없음 — grep 으로 구정책 문구 잔여를 확인한다.
-
-- [ ] **Step 1: TDD loop 의 커밋 순서 변경 (`_implementation-executor.md` line 31)**
-
-현재:
-```
-  - Order of operations per plan step: (1) write/extend the test that captures the step's acceptance criterion and confirm it fails for the right reason, (2) commit the failing test (`test(<scope>): ...`), (3) implement the minimum change to make it pass, (4) commit the implementation (`feat|fix(<scope>): ...`), (5) refactor without changing behaviour and commit separately if any cleanup is made (`refactor(<scope>): ...`). The failing-then-passing transition between steps (2) and (4) is the `TDD evidence` required by the final report.
-```
-교체:
-```
-  - Order of operations per plan step: (1) write/extend the test that captures the step's acceptance criterion and confirm it fails for the right reason, (2) implement the minimum change to make it pass, (3) commit the test and its implementation together in a single commit (`feat|fix(<scope>): ...`) — do NOT commit the failing test separately, (4) refactor without changing behaviour and commit separately if any cleanup is made (`refactor(<scope>): ...`). The failing-then-passing transition is preserved as `TDD evidence` in the final report (failing output captured before the merged commit, passing output after), not as two separate commits.
-```
-
-- [ ] **Step 2: 커밋 매핑 단위 변경 (`_implementation-executor.md` line 74)**
-
-현재:
-```
-  - One commit MUST correspond to one plan step (or one cohesive sub-step). Do NOT bundle unrelated steps into a single commit, and do NOT split a single step across commits unless the plan explicitly sequenced it that way.
-```
-교체:
-```
-  - One commit corresponds to one TDD cycle — a `RED:` step and its `GREEN:` step(s) are merged into a single `feat|fix` commit; an optional `REFACTOR:` step MAY be a separate `refactor` commit. Never split a test and its implementation into separate commits. Do NOT bundle unrelated cycles into a single commit.
-```
-
-- [ ] **Step 3: head-less 문구 정합 (`_implementation-executor.md` line 29)**
-
-line 29 의 `RED → GREEN → refactor → per-step commits → ` → `RED → GREEN → refactor → per-cycle commit → `.
-
-- [ ] **Step 4: deliverable TDD evidence 문구 (`_implementation-deliverable.md` line 20)**
-
-현재:
-```
-- **TDD evidence (when applicable)**: for steps that should be TDD-ordered, show the failing-test output BEFORE the implementation commit and the passing-test output AFTER, with commit SHAs framing the transition.
-```
-교체:
-```
-- **TDD evidence (when applicable)**: for steps that should be TDD-ordered, show the failing-test output captured BEFORE the merged commit and the passing-test output after, citing the single `feat|fix` commit SHA (test and implementation share one commit).
-```
-
-- [ ] **Step 5: deliverable Commit list / Plan coverage 정합 (`_implementation-deliverable.md` line 14, 38)**
-
-line 14 의 `each commit's SHA (or short SHA), message, and the plan step it satisfies` → `each commit's SHA (or short SHA), message, and the plan step(s) / TDD cycle it satisfies`.
-
-line 38 의 Plan coverage 항목 끝에 한 문장 추가: `A RED step and its GREEN step pointing to the same merged commit SHA is NOT a coverage gap — one SHA may be shared by both.`
-
-- [ ] **Step 6: 구정책 문구 잔여 grep 검증**
-
-Run:
-```bash
-grep -rn "commit the failing test\|framing the transition\|per-step commits\|One commit MUST correspond to one plan step" prompts/profiles/_implementation-executor.md prompts/profiles/_implementation-deliverable.md
-```
-Expected: 출력 없음(exit 1).
-
-- [ ] **Step 7: 커밋**
-
-```bash
-git add prompts/profiles/_implementation-executor.md prompts/profiles/_implementation-deliverable.md
-git commit -m "feat(executor): test/impl 단일 커밋 병합, refactor 별도 허용"
-```
-
----
-
-### Task 4: 마무리 — CHANGES 기록 + CI 게이트
-
-**Files:**
-- Modify: `CHANGES.md`
-
-- [ ] **Step 1: CHANGES.md 항목 추가**
-
-`CHANGES.md` 최상단 항목 형식을 따라(기존 항목 위) 한국어 항목 추가. 핵심 줄:
-```markdown
-### implementation 커밋·step 입도 완화
-
-- `implementation` executor 가 실패 테스트와 구현을 한 `feat|fix` 커밋으로 병합한다(refactor 는 별도 커밋 허용). 커밋 매핑 단위가 plan step → TDD 사이클로 바뀐다.
-- `implementation-planning` step 정의가 "2–5분 micro-action"에서 "완결적·응집 변경 단위"로 격상되고, stage 당 step 캡이 6 → 8 로 상향된다(`HARD_STEP_CAP`).
-- **사용자 영향:** 다음 release 후 `npx -y okstra@latest install` 1회로 전파. 신규 planning run 부터 step 이 굵어지고 implementation 커밋이 더 적게 묶인다. 기존 산출 plan(≤6 step)은 그대로 통과 — breaking 아님.
-```
-(기존 `CHANGES.md` 의 실제 헤딩/항목 스타일을 Read 로 확인해 형식을 맞출 것.)
-
-- [ ] **Step 2: 빌드 동기화 확인**
-
-Run: `npm run build`
-Expected: exit 0. `runtime/` 에 변경된 프로파일·validator 가 동기화됨(커밋하지 않음 — gitignored build output).
-
-- [ ] **Step 3: CI 게이트 통과 확인**
-
-Run: `npm run check`
-Expected: exit 0. (실패 시 해당 스위트 출력으로 원인 파악 후 수정 — 완료 선언 전 반드시 exit 0.)
-
-- [ ] **Step 4: 커밋**
-
-```bash
-git add CHANGES.md
-git commit -m "docs(changes): implementation 커밋·step 입도 완화 항목 추가"
-```
-
----
-
-## Self-Review
-
-- **Spec coverage:** A(커밋 병합) → Task 3. B(캡 상수화) → Task 1, B(declaration 미러) → Task 2. 테스트 영향(fixture 9-step + 8-step 회귀) → Task 1. CHANGES → Task 4. 비-목표(TDD/토큰/S10 유지)는 Global Constraints 로 고정. 누락 없음.
-- **Placeholder scan:** 모든 코드/문구 변경에 before→after 또는 정확한 코드 블록 제시. `CHANGES.md` 형식만 구현 시 Read 확인으로 위임(헤딩 스타일 보존 목적, 내용은 명시).
-- **Type/identifier consistency:** `HARD_STEP_CAP`(Task 1 정의) ↔ Task 2 의 `≤ 8` 미러 일치. `RED:`/`GREEN:`/`REFACTOR:` 토큰은 변경하지 않음(Global Constraints)으로 Task 3 의 새 커밋 문구와 정합.