okstra 0.38.1 → 0.40.0

package/docs/superpowers/plans/2026-06-02-requirements-discovery-fanout.md

@@ -0,0 +1,728 @@
+# requirements-discovery 도메인 fan-out 구현 계획
+
+> **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:** requirements-discovery 가 혼합 요청을 도메인별 packet 으로 분해해 fan-out 하고, 그 packet 들을 okstra-run 이 다시 소비하는 루프를 okstra-run 내부에서 완결한다.
+
+**Architecture:** requirements-discovery 가 다항목/다도메인 요청을 N개 packet(`.okstra/tasks/<g>/<id>/runs/requirements-discovery/fan-out/unit-*.md`)으로 직접 생산한다. 각 packet 은 `--task-brief <경로>` 로 okstra-run 에 그대로 투입돼 새 task-key 가 된다. 검증은 improvement-discovery 패턴(SSOT 모듈 + 전용 validator + validate-run 훅)을 mirror 한다. okstra-brief 는 개입하지 않는다.
+
+**Tech Stack:** Python 3 (pytest), 마크다운 템플릿/프로필, bash e2e.
+
+설계 근거: [docs/superpowers/specs/2026-06-02-requirements-discovery-fanout-design.md](../specs/2026-06-02-requirements-discovery-fanout-design.md)
+
+---
+
+## File Structure
+
+- `scripts/okstra_ctl/work_categories.py` (신설) — 5-enum domain SSOT.
+- `scripts/okstra_ctl/fanout.py` (신설) — depends-on DAG 위상정렬 + 순환검출.
+- `validators/validate_fanout.py` (신설) — packet + index 계약 검증.
+- `validators/validate-run.py` (수정) — requirements-discovery 일 때 fan-out 훅 호출.
+- `templates/reports/fan-out-unit.template.md` (신설) — packet 템플릿.
+- `prompts/profiles/requirements-discovery.md` (수정) — fan-out 계약 선언 + Non-goals.
+- `prompts/profiles/requirements-discovery.md` / `skills/okstra-context-loader/SKILL.md` / `skills/okstra-inspect/SKILL.md` (수정) — `ops-change` → `ops` 교정.
+- `tests/test_work_categories.py`, `tests/test_fanout.py`, `tests/test_validate_fanout.py` (신설).
+- `tests-e2e/scenario-<id>-requirements-discovery-fanout.sh` (신설).
+- `docs/kr/architecture.md`, `CHANGES.md` (수정).
+
+---
+
+## Task 1: work-category(domain) SSOT 모듈
+
+**Files:**
+- Create: `scripts/okstra_ctl/work_categories.py`
+- Test: `tests/test_work_categories.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+```python
+# tests/test_work_categories.py
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from okstra_ctl.work_categories import WORK_CATEGORIES, is_valid_category  # noqa: E402
+
+
+def test_enum_is_exactly_five_canonical_categories():
+    assert WORK_CATEGORIES == ("bugfix", "feature", "refactor", "ops", "improvement")
+
+
+def test_is_valid_category():
+    assert is_valid_category("bugfix")
+    assert not is_valid_category("ops-change")   # 비표준 철자 거부
+    assert not is_valid_category("")
+
+
+def test_ssot_no_ops_change_in_code_or_profile():
+    """SSOT 도입 후 코드/프로필에 'ops-change' 가 남아있으면 fail (drift 가드)."""
+    targets = [
+        REPO_ROOT / "prompts" / "profiles" / "requirements-discovery.md",
+        REPO_ROOT / "scripts" / "okstra_ctl" / "work_categories.py",
+    ]
+    for t in targets:
+        assert "ops-change" not in t.read_text(encoding="utf-8"), f"{t} still has ops-change"
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_work_categories.py -q`
+Expected: FAIL — `ModuleNotFoundError: okstra_ctl.work_categories`
+
+- [ ] **Step 3: 모듈 구현**
+
+```python
+# scripts/okstra_ctl/work_categories.py
+"""requirements-discovery work-category(domain) SSOT.
+
+profile / validators / wizard 는 이 모듈에서 enum 을 import 해야 한다. 다른 곳에서
+재정의하면 single-reference-point 위반이며 tests/test_work_categories.py 가 거부한다.
+
+다섯째 값은 `ops` 가 canonical 이다(`--work-category` CLI help 및 workflow.PHASE_RULES
+와 일치). 구버전 문서 철자 `ops-change` 는 폐기된다.
+"""
+from __future__ import annotations
+
+WORK_CATEGORIES: tuple[str, ...] = (
+    "bugfix",
+    "feature",
+    "refactor",
+    "ops",
+    "improvement",
+)
+
+
+def is_valid_category(value: str) -> bool:
+    return value in WORK_CATEGORIES
+```
+
+- [ ] **Step 4: `ops-change` → `ops` 교정** (test_ssot_no_ops_change 통과시키기)
+
+`prompts/profiles/requirements-discovery.md:17` 수정:
+- 기존: `  - classify the work as bugfix, feature, improvement, refactor, or ops-change`
+- 변경: `  - classify the work as bugfix, feature, improvement, refactor, or ops`
+
+`skills/okstra-context-loader/SKILL.md:47` 및 `skills/okstra-inspect/SKILL.md:54` 의
+`workCategory` 표 행에서 `ops-change` → `ops` 로 교정 (표시 문자열).
+
+- [ ] **Step 5: 통과 확인**
+
+Run: `python3 -m pytest tests/test_work_categories.py -q`
+Expected: PASS (3 passed)
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/work_categories.py tests/test_work_categories.py \
+  prompts/profiles/requirements-discovery.md skills/okstra-context-loader/SKILL.md skills/okstra-inspect/SKILL.md
+git commit -m "feat(work-categories): domain 5-enum SSOT + ops-change→ops 교정"
+```
+
+---
+
+## Task 2: depends-on DAG 위상정렬 + 순환검출 헬퍼
+
+**Files:**
+- Create: `scripts/okstra_ctl/fanout.py`
+- Test: `tests/test_fanout.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+```python
+# tests/test_fanout.py
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from okstra_ctl.fanout import topological_order, CycleError  # noqa: E402
+
+
+def test_linear_chain():
+    assert topological_order({"a": [], "b": ["a"], "c": ["b"]}) == ["a", "b", "c"]
+
+
+def test_independent_units_are_id_sorted():
+    assert topological_order({"b": [], "a": []}) == ["a", "b"]
+
+
+def test_cycle_raises():
+    with pytest.raises(CycleError):
+        topological_order({"a": ["b"], "b": ["a"]})
+
+
+def test_unknown_dependency_raises():
+    with pytest.raises(ValueError):
+        topological_order({"a": ["nope"]})
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_fanout.py -q`
+Expected: FAIL — `ModuleNotFoundError: okstra_ctl.fanout`
+
+- [ ] **Step 3: 구현**
+
+```python
+# scripts/okstra_ctl/fanout.py
+"""fan-out unit 의존 그래프: 위상정렬 + 순환검출 (Kahn, id 사전순 결정적)."""
+from __future__ import annotations
+
+
+class CycleError(ValueError):
+    """depends-on 그래프에 순환이 있을 때."""
+
+
+def topological_order(units: dict[str, list[str]]) -> list[str]:
+    """unit-id 를 착수 가능한 순서(의존 먼저)로 반환.
+
+    units: unit-id -> 그 unit 이 의존하는 unit-id 목록.
+    순환이면 CycleError, 알 수 없는 의존이면 ValueError.
+    """
+    indeg = {u: 0 for u in units}
+    for u, deps in units.items():
+        for d in deps:
+            if d not in units:
+                raise ValueError(f"unit {u!r} depends on unknown unit {d!r}")
+            indeg[u] += 1
+    queue = sorted(u for u, n in indeg.items() if n == 0)
+    order: list[str] = []
+    while queue:
+        u = queue.pop(0)
+        order.append(u)
+        for v, deps in units.items():
+            if u in deps:
+                indeg[v] -= 1
+                if indeg[v] == 0:
+                    queue.append(v)
+        queue.sort()
+    if len(order) != len(units):
+        remaining = sorted(set(units) - set(order))
+        raise CycleError(f"dependency cycle among units: {remaining}")
+    return order
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_fanout.py -q`
+Expected: PASS (4 passed)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/fanout.py tests/test_fanout.py
+git commit -m "feat(fanout): depends-on DAG 위상정렬 + 순환검출 헬퍼"
+```
+
+---
+
+## Task 3: packet 템플릿 + validate_fanout 검증기
+
+packet/index 포맷은 **validate_fanout 테스트가 계약의 SSOT** 다. 템플릿은 그 포맷을 따른다.
+
+**Files:**
+- Create: `templates/reports/fan-out-unit.template.md`
+- Create: `validators/validate_fanout.py`
+- Test: `tests/test_validate_fanout.py`
+
+packet frontmatter 계약 (inline flow list 로 파싱 단순화):
+
+```
+---
+unit-id: unit-001            # 파일명 stem 과 동일
+domain: bugfix               # WORK_CATEGORIES 중 하나
+depends-on: [unit-002]       # 같은 fan-out 내 unit-id 들의 inline 리스트 ([] 가능)
+recommended-next-phase: error-analysis   # error-analysis | implementation-planning
+---
+```
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+```python
+# tests/test_validate_fanout.py
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "validators"))
+
+from validate_fanout import validate_fanout  # noqa: E402
+
+
+def _write_unit(d: Path, uid: str, domain: str, deps: str, nxt: str = "error-analysis"):
+    (d / f"{uid}.md").write_text(
+        f"---\nunit-id: {uid}\ndomain: {domain}\ndepends-on: {deps}\n"
+        f"recommended-next-phase: {nxt}\n---\n\n# {uid}\n본문\n",
+        encoding="utf-8",
+    )
+
+
+def _write_index(d: Path, order: list[str]):
+    lines = ["# Fan-out Index", "> generated — do not hand-edit", ""]
+    lines += [f"{i+1}. {uid}" for i, uid in enumerate(order)]
+    (d / "index.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def test_valid_fanout_passes(tmp_path: Path):
+    fo = tmp_path / "fan-out"; fo.mkdir()
+    _write_unit(fo, "unit-001", "bugfix", "[]")
+    _write_unit(fo, "unit-002", "feature", "[unit-001]")
+    _write_index(fo, ["unit-001", "unit-002"])
+    res = validate_fanout(tmp_path)
+    assert res.ok, res.errors
+
+
+def test_bad_domain_fails(tmp_path: Path):
+    fo = tmp_path / "fan-out"; fo.mkdir()
+    _write_unit(fo, "unit-001", "ops-change", "[]")
+    _write_index(fo, ["unit-001"])
+    res = validate_fanout(tmp_path)
+    assert not res.ok
+    assert any("domain" in e for e in res.errors)
+
+
+def test_cycle_fails(tmp_path: Path):
+    fo = tmp_path / "fan-out"; fo.mkdir()
+    _write_unit(fo, "unit-001", "bugfix", "[unit-002]")
+    _write_unit(fo, "unit-002", "feature", "[unit-001]")
+    _write_index(fo, ["unit-001", "unit-002"])
+    res = validate_fanout(tmp_path)
+    assert not res.ok
+    assert any("cycle" in e.lower() for e in res.errors)
+
+
+def test_index_mismatch_fails(tmp_path: Path):
+    fo = tmp_path / "fan-out"; fo.mkdir()
+    _write_unit(fo, "unit-001", "bugfix", "[]")
+    _write_index(fo, ["unit-001", "unit-999"])   # 존재하지 않는 unit 나열
+    res = validate_fanout(tmp_path)
+    assert not res.ok
+    assert any("index" in e.lower() for e in res.errors)
+
+
+def test_no_fanout_dir_is_ok(tmp_path: Path):
+    # fan-out 안 한 단일 요청: 디렉토리 없으면 통과(검증 대상 아님).
+    res = validate_fanout(tmp_path)
+    assert res.ok
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_validate_fanout.py -q`
+Expected: FAIL — `ModuleNotFoundError: validate_fanout`
+
+- [ ] **Step 3: validate_fanout.py 구현**
+
+```python
+# validators/validate_fanout.py
+"""Validator for requirements-discovery fan-out packets + index.
+
+Called by validators/validate-run.py when task_type == "requirements-discovery"
+and a `fan-out/` directory exists under the run dir.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent.parent / "scripts"
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from okstra_ctl.work_categories import WORK_CATEGORIES  # noqa: E402
+from okstra_ctl.fanout import topological_order, CycleError  # noqa: E402
+
+_NEXT_PHASES = ("error-analysis", "implementation-planning")
+_UNIT_RE = re.compile(r"unit-\d{3}")
+
+
+@dataclass
+class ValidationResult:
+    ok: bool
+    errors: list[str] = field(default_factory=list)
+
+
+def _frontmatter(text: str) -> dict[str, str]:
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    fm: dict[str, str] = {}
+    for line in text[3:end].splitlines():
+        if ":" in line:
+            k, _, v = line.partition(":")
+            fm[k.strip()] = v.strip()
+    return fm
+
+
+def _parse_deps(raw: str) -> list[str]:
+    return _UNIT_RE.findall(raw or "")
+
+
+def validate_fanout(run_dir: Path) -> ValidationResult:
+    run_dir = Path(run_dir)
+    fo = run_dir / "fan-out"
+    if not fo.is_dir():
+        return ValidationResult(ok=True)
+
+    errors: list[str] = []
+    units: dict[str, list[str]] = {}
+    for pkt in sorted(fo.glob("unit-*.md")):
+        fm = _frontmatter(pkt.read_text(encoding="utf-8"))
+        uid = fm.get("unit-id", "")
+        if uid != pkt.stem:
+            errors.append(f"{pkt.name}: unit-id {uid!r} != filename stem {pkt.stem!r}")
+        if fm.get("domain") not in WORK_CATEGORIES:
+            errors.append(f"{pkt.name}: domain {fm.get('domain')!r} not in {WORK_CATEGORIES}")
+        if fm.get("recommended-next-phase") not in _NEXT_PHASES:
+            errors.append(f"{pkt.name}: recommended-next-phase not in {_NEXT_PHASES}")
+        units[pkt.stem] = _parse_deps(fm.get("depends-on", ""))
+
+    if not units:
+        errors.append("fan-out/: directory exists but no unit-*.md packets found")
+        return ValidationResult(ok=False, errors=errors)
+
+    order: list[str] = []
+    try:
+        order = topological_order(units)
+    except CycleError as exc:
+        errors.append(f"depends-on cycle: {exc}")
+    except ValueError as exc:
+        errors.append(f"depends-on unresolved: {exc}")
+
+    index = fo / "index.md"
+    if not index.is_file():
+        errors.append("fan-out/index.md missing")
+    else:
+        listed = _UNIT_RE.findall(index.read_text(encoding="utf-8"))
+        if set(listed) != set(units):
+            errors.append(
+                f"index.md units {sorted(set(listed))} != packets {sorted(units)}"
+            )
+        elif order and listed != order:
+            errors.append(f"index.md order {listed} is not the topological order {order}")
+
+    return ValidationResult(ok=not errors, errors=errors)
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_validate_fanout.py -q`
+Expected: PASS (5 passed)
+
+- [ ] **Step 5: packet 템플릿 작성**
+
+```markdown
+<!-- templates/reports/fan-out-unit.template.md -->
+---
+unit-id: {{UNIT_ID}}
+domain: {{DOMAIN}}
+depends-on: {{DEPENDS_ON}}
+recommended-next-phase: {{NEXT_PHASE}}
+---
+
+# Fan-out Unit: {{UNIT_ID}} ({{DOMAIN}})
+
+> requirements-discovery fan-out 산출 packet. `okstra-run --task-brief <이 파일 경로>`
+> 로 새 task-key 를 시작한다. 이 파일은 그 run 의 입력 packet 이다.
+
+## Scope
+
+<!-- 이 단위가 다루는 작업 항목 1개를 자족적으로 서술. 다른 단위와 섞지 말 것. -->
+
+## Evidence
+
+<!-- path:line 근거. requirements-discovery 가 file inspection 으로 확인한 위치. -->
+
+## Depends-on rationale
+
+<!-- depends-on 에 적은 각 unit 에 왜 의존하는지 1줄씩. 없으면 _(none)_ -->
+```
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add validators/validate_fanout.py tests/test_validate_fanout.py templates/reports/fan-out-unit.template.md
+git commit -m "feat(fanout): packet 템플릿 + validate_fanout 검증기"
+```
+
+---
+
+## Task 4: validate-run.py 에 fan-out 훅 연결
+
+**Files:**
+- Modify: `validators/validate-run.py` (improvement 디스패치부 `_validate_improvement_discovery` ~line 1254, 호출부 ~line 1628 참고)
+- Test: `tests/test_validate_fanout.py` (훅 호출 통합 테스트 1개 추가)
+
+- [ ] **Step 1: 통합 테스트 추가 (실패)**
+
+`tests/test_validate_fanout.py` 끝에 추가:
+
+```python
+def test_validate_run_invokes_fanout_hook(tmp_path: Path):
+    """validate-run 의 디스패치 함수가 requirements-discovery 에서 fan-out 을 검증한다."""
+    sys.path.insert(0, str(REPO_ROOT / "validators"))
+    import importlib.util
+    spec = importlib.util.spec_from_file_location(
+        "validate_run_mod", REPO_ROOT / "validators" / "validate-run.py"
+    )
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    run_dir = tmp_path / "runs" / "requirements-discovery"
+    fo = run_dir / "fan-out"; fo.mkdir(parents=True)
+    _write_unit(fo, "unit-001", "ops-change", "[]")   # 잘못된 domain
+    _write_index(fo, ["unit-001"])
+
+    failures: list[str] = []
+    mod._validate_requirements_discovery_fanout(run_dir, failures)
+    assert any("requirements-discovery" in f and "domain" in f for f in failures)
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_validate_fanout.py::test_validate_run_invokes_fanout_hook -q`
+Expected: FAIL — `AttributeError: module has no attribute '_validate_requirements_discovery_fanout'`
+
+- [ ] **Step 3: 디스패치 함수 추가**
+
+`validators/validate-run.py` 의 `_validate_improvement_discovery` 함수 바로 아래에 추가
+(스타일은 sibling 그대로):
+
+```python
+def _validate_requirements_discovery_fanout(run_dir, failures) -> None:
+    """requirements-discovery run 에 fan-out/ 이 있으면 packet+index 를 검증해
+    실패를 ``requirements-discovery: `` 접두로 folding 한다. fan-out 이 없으면 no-op.
+    """
+    from pathlib import Path as _Path
+    if not (_Path(run_dir) / "fan-out").is_dir():
+        return
+    try:
+        from validate_fanout import validate_fanout  # noqa: E402
+    except Exception as exc:  # pragma: no cover - import guard
+        failures.append(
+            f"requirements-discovery: validate_fanout import failed — {exc}"
+        )
+        return
+    result = validate_fanout(_Path(run_dir))
+    if not result.ok:
+        for err in result.errors:
+            failures.append(f"requirements-discovery: {err}")
+```
+
+- [ ] **Step 4: 호출부 연결**
+
+`_validate_improvement_discovery(...)` 호출 라인(현재 1636) 바로 다음, `validate_report_views(report_path, failures)`(현재 1637) 앞에 추가. `run_dir` 은 improvement 분기와 동일하게 `report_path.parent.parent`(= `runs/<task-type>/`)로 계산한다:
+
+```python
+    if task_type == "requirements-discovery":
+        run_dir = report_path.parent.parent
+        _validate_requirements_discovery_fanout(run_dir, failures)
+```
+
+(`report_path` 는 `runs/requirements-discovery/reports/final-report-*.md` 이므로 `parent.parent` 가 `runs/requirements-discovery/`, 그 아래 `fan-out/` 을 검증한다.)
+
+- [ ] **Step 5: 통과 확인 + 전체 validator 테스트**
+
+Run: `python3 -m pytest tests/test_validate_fanout.py -q`
+Expected: PASS (6 passed)
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add validators/validate-run.py tests/test_validate_fanout.py
+git commit -m "feat(validate-run): requirements-discovery fan-out 검증 훅 연결"
+```
+
+---
+
+## Task 5: requirements-discovery 프로필에 fan-out 계약 선언
+
+**Files:**
+- Modify: `prompts/profiles/requirements-discovery.md`
+
+- [ ] **Step 1: fan-out 책임 섹션 추가**
+
+`- Primary focus areas:` 블록 다음에 새 항목 추가:
+
+```markdown
+- Fan-out (multi-item / multi-domain requests only):
+  - 단일 항목/단일 도메인 요청은 fan-out 하지 않는다(현행 단일 라우팅 보존).
+  - 요청이 2개 이상 도메인에 걸치거나 독립 착수 가능한 작업 항목이 2개 이상이면,
+    각 항목을 `runs/requirements-discovery/fan-out/unit-<NNN>.md` packet 으로 발행한다.
+    packet 은 `templates/reports/fan-out-unit.template.md` 형식을 따르며 frontmatter
+    `domain`(work-category 5-enum), `depends-on`(같은 fan-out 내 unit-id 의 inline 리스트),
+    `recommended-next-phase`(error-analysis | implementation-planning)를 채운다.
+  - `runs/requirements-discovery/fan-out/index.md` 에 packet 을 depends-on 위상순서로
+    나열한다(생성 뷰; 직접 편집 금지 명시). depends-on 그래프는 DAG 여야 한다 — 순환이면
+    리포트에 경고하고 해당 의존을 끊는다.
+  - 최종 리포트에는 분해 결과를 중복하지 말고 "fan-out: N packets → fan-out/index.md" 한 줄
+    포인터만 둔다. packet 실행은 별도다: 사용자가 `okstra-run --task-brief <packet 경로>` 로
+    각 단위를 새 task-key 로 시작한다(이 phase 는 다운스트림 run 을 직접 시작하지 않는다).
+```
+
+- [ ] **Step 2: Non-goals 갱신**
+
+`- Non-goals:` 블록의 첫 항목 아래에 in-scope 명시 1줄 추가:
+
+```markdown
+  - 작업 단위 분해(fan-out)는 이 phase 의 in-scope 다 — 단, 각 단위의 *해법 설계*·소스
+    편집·plan 작성은 여전히 non-goal 이며 다운스트림 phase 가 담당한다
+```
+
+- [ ] **Step 3: 빌드로 runtime 동기화 + 워크플로 validator**
+
+Run: `npm run build && bash validators/validate-workflow.sh`
+Expected: build 0/오류 없음, validator PASS
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add prompts/profiles/requirements-discovery.md
+git commit -m "feat(requirements-discovery): fan-out 분해 계약 선언 + Non-goals 갱신"
+```
+
+---
+
+## Task 6: 문서 (architecture.md, CHANGES.md)
+
+**Files:**
+- Modify: `docs/kr/architecture.md`
+- Modify: `CHANGES.md`
+
+- [ ] **Step 1: architecture.md 에 fan-out 흐름 추가**
+
+requirements-discovery 를 다루는 절(또는 phase 흐름 표 인근)에 추가:
+
+```markdown
+#### requirements-discovery fan-out
+
+혼합/다항목 요청은 requirements-discovery 가 도메인(work-category 5-enum)별 packet 으로
+분해해 `runs/requirements-discovery/fan-out/unit-*.md` 에 발행한다. 각 packet 은
+`okstra-run --task-brief <경로>` 로 새 task-key 가 된다. 순서는 `index.md` 의 depends-on
+위상정렬이 담고, task 화 이후의 통합 일정은 okstra-schedule 이 맡는다. okstra-brief 는
+이 경로에 개입하지 않는다. 검증: `validators/validate_fanout.py`(validate-run 훅).
+```
+
+- [ ] **Step 2: CHANGES.md 항목 추가**
+
+`## 2026-06-02` 섹션에 추가(없으면 상단에 신설):
+
+```markdown
+### feat(requirements-discovery): 혼합 요청 도메인 fan-out
+
+- requirements-discovery 가 버그/개선/구현이 섞인 요청을 work-category(5-enum)별 packet 으로
+  분해해 `runs/requirements-discovery/fan-out/` 에 발행하고, 각 packet 을
+  `okstra-run --task-brief <경로>` 로 독립 task-key 로 fan-out 할 수 있게 함. 순서는 packet 의
+  `depends-on` 위상정렬(`index.md`)이 담는다. 단일 요청은 현행 단일 라우팅 그대로.
+- work-category 다섯째 값을 `ops` 로 SSOT 화하고 일부 문서의 `ops-change` 철자를 교정.
+- 사용자 영향: 다음 release + `npx -y okstra@latest install` 후 적용. 혼합 요청 시
+  requirements-discovery 가 packet 들을 만들어 주며, 각각을 `okstra-run` 으로 따로 시작하면 된다.
+  단일 요청 동작은 변화 없음.
+```
+
+- [ ] **Step 3: 커밋**
+
+```bash
+git add docs/kr/architecture.md CHANGES.md
+git commit -m "docs(fanout): architecture + CHANGES 항목"
+```
+
+---
+
+## Task 7: e2e 시나리오
+
+**Files:**
+- Create: `tests-e2e/scenario-<NN>-requirements-discovery-fanout.sh` (`ls tests-e2e/` 로 다음 번호 확인)
+
+- [ ] **Step 1: 시나리오 작성**
+
+기존 시나리오(`tests-e2e/scenario-01-record-start-reconcile.sh`)의 골격(`mktemp -d` OKSTRA_HOME,
+`trap` 정리)을 따른다. 검증 핵심:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+OKSTRA_HOME="$(mktemp -d)"; export OKSTRA_HOME
+trap 'rm -rf "$OKSTRA_HOME"' EXIT
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# fan-out 산출물을 모사한 run 디렉토리를 만들고 validate_fanout 가 통과/거부하는지 확인.
+WORK="$(mktemp -d)"; trap 'rm -rf "$OKSTRA_HOME" "$WORK"' EXIT
+FO="$WORK/runs/requirements-discovery/fan-out"; mkdir -p "$FO"
+cat > "$FO/unit-001.md" <<'EOF'
+---
+unit-id: unit-001
+domain: bugfix
+depends-on: []
+recommended-next-phase: error-analysis
+---
+# unit-001
+EOF
+cat > "$FO/unit-002.md" <<'EOF'
+---
+unit-id: unit-002
+domain: feature
+depends-on: [unit-001]
+recommended-next-phase: implementation-planning
+---
+# unit-002
+EOF
+printf '# Fan-out Index\n> generated\n1. unit-001\n2. unit-002\n' > "$FO/index.md"
+
+python3 - "$WORK" <<'PY'
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path("validators").resolve()))
+from validate_fanout import validate_fanout
+res = validate_fanout(Path(sys.argv[1]) / "runs" / "requirements-discovery")
+assert res.ok, res.errors
+print("fan-out validation OK")
+PY
+echo "PASS: scenario requirements-discovery-fanout"
+```
+
+- [ ] **Step 2: 실행 확인**
+
+Run: `bash tests-e2e/scenario-<NN>-requirements-discovery-fanout.sh`
+Expected: `PASS: scenario requirements-discovery-fanout`
+
+- [ ] **Step 3: 커밋**
+
+```bash
+git add tests-e2e/scenario-<NN>-requirements-discovery-fanout.sh
+git commit -m "test(e2e): requirements-discovery fan-out 검증 시나리오"
+```
+
+---
+
+## Task 8: 전체 회귀 + 빌드
+
+- [ ] **Step 1: 전체 유닛 스위트**
+
+Run: `python3 -m pytest tests/ -q`
+Expected: 기존 + 신규 모두 PASS (회귀 0)
+
+- [ ] **Step 2: 빌드 + 워크플로 validator**
+
+Run: `npm run build && bash validators/validate-workflow.sh`
+Expected: build 성공, validator PASS
+
+- [ ] **Step 3: CLI smoke**
+
+Run: `node bin/okstra --version`
+Expected: 버전 출력
+
+- [ ] **Step 4: 최종 커밋 (남은 것 있으면)**
+
+```bash
+git status --short    # 깨끗해야 함
+```