okstra 0.101.1 → 0.102.1

package/docs/superpowers/plans/2026-06-24-decision-drafts-render-gap.md

@@ -0,0 +1,568 @@
+# Decision Drafts 렌더 갭 해소 구현 계획
+
+> **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-planning 의 `Decision Drafts` 부록을 cross-project 와 동일하게 구조 필드(`decisionDrafts`/`skippedAdrCandidates`)로 승격해 결정론적 렌더 파이프라인에 실제로 출력시키고, line 116 의 materialization step MUST 를 validator 로 강제한다.
+
+**Architecture:** `data.json`(SSOT) → Jinja 템플릿 결정론 렌더. 스키마에 `$defs/DecisionDraft`·`$defs/SkippedAdrCandidate` 추가 → `implementationPlanning` 배열 2개 → 템플릿 §5.4 `### Decision Drafts` 블록 → i18n → validate-run 헤딩 contract + 자기완결 교차 필드 검사 → 프로파일/report-writer prose 정합 → 빌드 동기화. cross-project 직전 사례([2026-06-24-cross-project-precondition.md](2026-06-24-cross-project-precondition.md))와 동일 패턴.
+
+**Tech Stack:** JSON Schema(Draft 2020-12 스타일, `okstra_ctl.final_report_schema`), Jinja2 템플릿, Python `validate-run.py`, pytest, Node `tools/build.mjs`.
+
+## Global Constraints
+
+- `runtime/` 직접 수정 금지 — 소스(`schemas/`, `templates/`, `prompts/`, `validators/`, `agents/`) 수정 후 `npm run build` 로 동기화 (CLAUDE.md).
+- 완료 게이트: `npm run check` 가 그대로 exit 0 (test:js 실패 시 test:py 안 돔 — 통합 게이트로 확인).
+- 동시 세션 환경 — `git commit --amend` 금지, 항상 새 커밋([project_concurrent_sessions_no_amend]). main 직접 커밋이 이 레포 관례.
+- 사용자-대면 prose(스펙/플랜/프로파일 한국어 본문)는 한국어, 코드 식별자/경로/CLI 인자는 영어.
+- i18n: `en.json` 과 `ko.json` 의 키는 **정확히 동일**해야 하며 같은 커밋에 추가([en.json:4](../../../templates/reports/i18n/en.json:4)).
+- 헤딩 substring `Decision Drafts` 는 **세 곳**에 동시 존재해야 정합: 프로파일 line 57, `validate-run.py` `PLANNING_REQUIRED_SECTIONS`, 테스트 `_PLANNING_REQUIRED`.
+
+---
+
+### Task 1: 스키마 데이터 모델 + 픽스처
+
+**Files:**
+- Modify: `schemas/final-report-v1.0.schema.json` (`$defs` 2개 신설, `implementationPlanning` properties+required)
+- Modify: `tests/fixtures/final-report-data/implementation-planning-001.data.json` (빈 배열 2개 추가)
+- Create: `tests/contract/test_decision_drafts.py` (스키마 모양 테스트)
+
+**Interfaces:**
+- Produces: `$defs/DecisionDraft` (필드 `number`/`slug`/`status`/`context`/`decision`/`consequences`/`alternativesConsidered`), `$defs/SkippedAdrCandidate` (`topic`/`reason`), `implementationPlanning.decisionDrafts[]`, `implementationPlanning.skippedAdrCandidates[]`. Task 2(렌더)·Task 3(validator)·Task 4(prose)가 이 필드명을 그대로 참조.
+
+- [ ] **Step 1: 실패 테스트 작성** — `tests/contract/test_decision_drafts.py`
+
+```python
+"""decisionDrafts / skippedAdrCandidates 스키마 모양 + validate-run 교차 필드 게이트 단위 테스트.
+
+스키마는 각 draft 의 7필드 비-빈 + status enum 을 보장하고(모양),
+validate-run 은 decisionDrafts 가 비어있지 않으면 어느 stage stepwise 가
+`.okstra/decisions/` materialization step 을 포함하는지(존재)를 본다.
+"""
+from __future__ import annotations
+
+import copy
+import importlib.util
+import json
+import sys
+
+from _paths import REPO_ROOT
+
+import pytest
+
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from okstra_ctl.final_report_schema import load_schema, validate as schema_validate  # noqa: E402
+
+FIXTURE = (
+    REPO_ROOT / "tests" / "fixtures" / "final-report-data"
+    / "implementation-planning-001.data.json"
+)
+
+_SAMPLE_DRAFT = {
+    "number": "0007",
+    "slug": "classifier-table-naming",
+    "status": "Proposed",
+    "context": "classifier 스키마의 5개 테이블 명명 규칙을 정해야 한다.",
+    "decision": "snake_case + 도메인 접두어(classifier_) 를 사용한다.",
+    "consequences": "기존 마이그레이션과 일관되며 조인 가독성이 오른다.",
+    "alternativesConsidered": "camelCase(기각: 식별자 대소문자 이슈), 접두어 없음(기각: 충돌 위험).",
+}
+_SAMPLE_SKIPPED = {"topic": "ORM 도입 여부", "reason": "되돌리기 어렵지 않음 — 기준 ① 미달."}
+
+
+@pytest.fixture(scope="module")
+def schema():
+    return load_schema()
+
+
+@pytest.fixture()
+def data():
+    return json.loads(FIXTURE.read_text(encoding="utf-8"))
+
+
+def test_fixture_with_empty_decision_arrays_validates(schema, data):
+    assert schema_validate(data, schema) == []
+
+
+def test_valid_draft_and_skipped_validate(schema, data):
+    d = copy.deepcopy(data)
+    d["implementationPlanning"]["decisionDrafts"] = [copy.deepcopy(_SAMPLE_DRAFT)]
+    d["implementationPlanning"]["skippedAdrCandidates"] = [copy.deepcopy(_SAMPLE_SKIPPED)]
+    assert schema_validate(d, schema) == []
+
+
+def test_empty_context_is_rejected(schema, data):
+    d = copy.deepcopy(data)
+    bad = copy.deepcopy(_SAMPLE_DRAFT)
+    bad["context"] = ""
+    d["implementationPlanning"]["decisionDrafts"] = [bad]
+    assert schema_validate(d, schema) != []
+
+
+def test_bad_slug_is_rejected(schema, data):
+    d = copy.deepcopy(data)
+    bad = copy.deepcopy(_SAMPLE_DRAFT)
+    bad["slug"] = "Classifier Table Naming"  # 공백/대문자 — kebab 위반
+    d["implementationPlanning"]["decisionDrafts"] = [bad]
+    assert schema_validate(d, schema) != []
+
+
+def test_non_proposed_status_is_rejected(schema, data):
+    d = copy.deepcopy(data)
+    bad = copy.deepcopy(_SAMPLE_DRAFT)
+    bad["status"] = "Accepted"
+    d["implementationPlanning"]["decisionDrafts"] = [bad]
+    assert schema_validate(d, schema) != []
+
+
+def test_short_number_is_rejected(schema, data):
+    d = copy.deepcopy(data)
+    bad = copy.deepcopy(_SAMPLE_DRAFT)
+    bad["number"] = "7"  # zero-pad ≥4 위반
+    d["implementationPlanning"]["decisionDrafts"] = [bad]
+    assert schema_validate(d, schema) != []
+
+
+def test_empty_skipped_topic_is_rejected(schema, data):
+    d = copy.deepcopy(data)
+    bad = copy.deepcopy(_SAMPLE_SKIPPED)
+    bad["topic"] = ""
+    d["implementationPlanning"]["skippedAdrCandidates"] = [bad]
+    assert schema_validate(d, schema) != []
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/contract/test_decision_drafts.py -v`
+Expected: FAIL — `test_valid_draft_and_skipped_validate` 등이 실패. 현재 `implementationPlanning` 은 `additionalProperties: false` 라 `decisionDrafts`/`skippedAdrCandidates` 키 자체가 거부되고, `test_fixture_with_empty_decision_arrays_validates` 도 픽스처에 키가 없어 (required 추가 전이므로) 통과하거나 무관 — 핵심은 inject 테스트가 FAIL 하는 것.
+
+- [ ] **Step 3: 스키마에 `$defs` 2개 추가** — `schemas/final-report-v1.0.schema.json` `CrossProjectDependency` 정의([:1382](../../../schemas/final-report-v1.0.schema.json:1382)) **바로 뒤**(`ValidationCheckRow` 앞)에 삽입:
+
+```json
+    "DecisionDraft": {
+      "type": "object",
+      "required": ["number", "slug", "status", "context", "decision", "consequences", "alternativesConsidered"],
+      "additionalProperties": false,
+      "properties": {
+        "number": { "type": "string", "pattern": "^\\d{4,}$" },
+        "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "status": { "enum": ["Proposed"] },
+        "context": { "type": "string", "minLength": 1 },
+        "decision": { "type": "string", "minLength": 1 },
+        "consequences": { "type": "string", "minLength": 1 },
+        "alternativesConsidered": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "SkippedAdrCandidate": {
+      "type": "object",
+      "required": ["topic", "reason"],
+      "additionalProperties": false,
+      "properties": {
+        "topic": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
+```
+
+- [ ] **Step 4: `implementationPlanning` 에 properties + required 추가** — `schemas/final-report-v1.0.schema.json`
+
+`required` 배열([:353-365](../../../schemas/final-report-v1.0.schema.json:353))의 `"crossProjectDependencies"` 다음에 두 항목 추가:
+
+```json
+        "planBodyVerification",
+        "crossProjectDependencies",
+        "decisionDrafts",
+        "skippedAdrCandidates"
+```
+
+`properties` 의 `crossProjectDependencies` 블록([:415-418](../../../schemas/final-report-v1.0.schema.json:415)) 다음에 추가:
+
+```json
+        "crossProjectDependencies": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/CrossProjectDependency" }
+        },
+        "decisionDrafts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DecisionDraft" }
+        },
+        "skippedAdrCandidates": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SkippedAdrCandidate" }
+        }
+```
+
+- [ ] **Step 5: 픽스처에 빈 배열 2개 추가** — `tests/fixtures/final-report-data/implementation-planning-001.data.json`
+
+`implementationPlanning.crossProjectDependencies` 배열 다음에 추가(required 충족, 가장 단순):
+
+```json
+    "crossProjectDependencies": [ ...기존 그대로... ],
+    "decisionDrafts": [],
+    "skippedAdrCandidates": []
+```
+
+- [ ] **Step 6: 테스트 통과 확인 (신규 + 회귀)**
+
+Run: `python3 -m pytest tests/contract/test_decision_drafts.py tests/report/test_schema_excerpt.py tests/contract/test_cross_project_precondition.py -v`
+Expected: PASS — 신규 모양 테스트 7개 통과; `test_excerpt_validates_real_fixture_data`(픽스처가 full schema 검증)·`test_no_dangling_refs`(새 `$defs` 가 `$ref` 클로저로 자동 포함) 통과.
+
+- [ ] **Step 7: 커밋**
+
+```bash
+git add schemas/final-report-v1.0.schema.json tests/fixtures/final-report-data/implementation-planning-001.data.json tests/contract/test_decision_drafts.py
+git commit -m "feat(report-schema): add DecisionDraft + skippedAdrCandidates fields"
+```
+
+---
+
+### Task 2: 템플릿 렌더 + i18n
+
+**Files:**
+- Modify: `templates/reports/final-report.template.md` (§5.4 에 `### Decision Drafts` 블록)
+- Modify: `templates/reports/i18n/en.json`, `templates/reports/i18n/ko.json` (키 추가)
+- Modify: `tests/report/test_render_final_report.py` (테스트 2개 추가 + `_PLANNING_REQUIRED` 갱신)
+
+**Interfaces:**
+- Consumes: Task 1 의 `implementationPlanning.decisionDrafts[]`(필드 number/slug/status/context/decision/consequences/alternativesConsidered), `skippedAdrCandidates[]`(topic/reason).
+- Produces: 렌더된 `### Decision Drafts` 섹션 헤딩(substring) — Task 3 의 `PLANNING_REQUIRED_SECTIONS` 가 의존.
+
+- [ ] **Step 1: 실패 테스트 작성** — `tests/report/test_render_final_report.py` 끝부분(`test_cross_project_dependencies_empty_state` 인근)에 추가:
+
+```python
+_SAMPLE_DRAFT = {
+    "number": "0007",
+    "slug": "classifier-table-naming",
+    "status": "Proposed",
+    "context": "테이블 명명 규칙을 정해야 한다.",
+    "decision": "snake_case + classifier_ 접두어.",
+    "consequences": "조인 가독성이 오른다.",
+    "alternativesConsidered": "camelCase(기각), 접두어 없음(기각).",
+}
+_SAMPLE_SKIPPED = {"topic": "ORM 도입", "reason": "되돌리기 어렵지 않음 — 기준 ① 미달."}
+
+
+def test_decision_drafts_render():
+    data = _load("implementation-planning-001.data.json")
+    data["implementationPlanning"]["decisionDrafts"] = [dict(_SAMPLE_DRAFT)]
+    data["implementationPlanning"]["skippedAdrCandidates"] = [dict(_SAMPLE_SKIPPED)]
+    rendered = render(data, template_path=find_default_template())
+    assert "### Decision Drafts" in rendered
+    assert "#### 0007-classifier-table-naming" in rendered
+    assert "Proposed" in rendered
+    assert "skipped adr-candidate: ORM 도입 — reason:" in rendered
+
+
+def test_decision_drafts_empty_state():
+    rendered = _render_fixture("implementation-planning-001.data.json")  # 픽스처는 빈 배열
+    assert "### Decision Drafts" in rendered
+    section = rendered[
+        rendered.index("### Decision Drafts"):
+        rendered.index("## 5.5 Stage Map")
+    ]
+    assert "####" not in section  # draft 서브섹션 없음
+    assert "skipped adr-candidate:" not in section
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/report/test_render_final_report.py::test_decision_drafts_render tests/report/test_render_final_report.py::test_decision_drafts_empty_state -v`
+Expected: FAIL — 템플릿에 `### Decision Drafts` 블록이 없어 헤딩 부재 + `t()` 키 미정의.
+
+- [ ] **Step 3: 템플릿 블록 추가** — `templates/reports/final-report.template.md` 의 `### Requirement Coverage` 표 끝([:258](../../../templates/reports/final-report.template.md:258))과 `## 5.5 Stage Map`([:260](../../../templates/reports/final-report.template.md:260)) **사이**에 삽입:
+
+```jinja
+### Decision Drafts{% if t("sectionAside.decisionDrafts") != "Decision Drafts" %} ({{ t("sectionAside.decisionDrafts") }}){% endif %}
+
+{% if (implementationPlanning.decisionDrafts | length == 0) and (implementationPlanning.skippedAdrCandidates | length == 0) -%}
+{{ t("emptyState.decisionDrafts") }}
+{%- else %}
+{% for d in implementationPlanning.decisionDrafts %}
+#### {{ d.number }}-{{ d.slug }}
+
+- **{{ t("implementationPlanning.decisionDraftFields.status") }}:** {{ d.status }}
+- **{{ t("implementationPlanning.decisionDraftFields.context") }}:** {{ d.context }}
+- **{{ t("implementationPlanning.decisionDraftFields.decision") }}:** {{ d.decision }}
+- **{{ t("implementationPlanning.decisionDraftFields.consequences") }}:** {{ d.consequences }}
+- **{{ t("implementationPlanning.decisionDraftFields.alternativesConsidered") }}:** {{ d.alternativesConsidered }}
+{% endfor %}
+{% for s in implementationPlanning.skippedAdrCandidates %}
+- skipped adr-candidate: {{ s.topic }} — reason: {{ s.reason }}
+{% endfor %}
+{%- endif %}
+
+```
+
+- [ ] **Step 4: i18n 키 추가 (en.json)** — `templates/reports/i18n/en.json`
+
+`emptyState`([:6](../../../templates/reports/i18n/en.json:6))에 추가: `"decisionDrafts": "- No decision drafts or skipped ADR candidates."`
+`sectionAside`([:32](../../../templates/reports/i18n/en.json:32))에 추가: `"decisionDrafts": "Decision Drafts"`
+`implementationPlanning`([:91](../../../templates/reports/i18n/en.json:91))의 `crossProjectRecognitionNote` 다음에 추가:
+
+```json
+    "decisionDraftFields": {
+      "status": "Status",
+      "context": "Context",
+      "decision": "Decision",
+      "consequences": "Consequences",
+      "alternativesConsidered": "Alternatives Considered"
+    }
+```
+
+- [ ] **Step 5: i18n 키 추가 (ko.json — en.json 과 동일 키)** — `templates/reports/i18n/ko.json`
+
+`emptyState` 에 추가: `"decisionDrafts": "- 결정 기록 초안이나 스킵된 ADR 후보 없음."`
+`sectionAside` 에 추가: `"decisionDrafts": "결정 기록 초안"`
+`implementationPlanning` 의 `crossProjectRecognitionNote` 다음에 추가:
+
+```json
+    "decisionDraftFields": {
+      "status": "상태",
+      "context": "맥락",
+      "decision": "결정",
+      "consequences": "결과",
+      "alternativesConsidered": "검토한 대안"
+    }
+```
+
+- [ ] **Step 6: `_PLANNING_REQUIRED` 에 헤딩 추가** — `tests/report/test_render_final_report.py:43`
+
+`_PLANNING_REQUIRED` 튜플([:43-56](../../../tests/report/test_render_final_report.py:43))의 `"Cross-Project Dependencies",` 다음에 `"Decision Drafts",` 추가.
+
+- [ ] **Step 7: 렌더 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/report/test_render_final_report.py -v`
+Expected: PASS — 신규 2개 + `test_implementation_planning_fixture_contains_all_required_substrings`(이제 `Decision Drafts` 포함, 빈 배열 픽스처가 empty-state 로 헤딩 렌더) 통과.
+
+- [ ] **Step 8: 커밋**
+
+```bash
+git add templates/reports/final-report.template.md templates/reports/i18n/en.json templates/reports/i18n/ko.json tests/report/test_render_final_report.py
+git commit -m "feat(report): render Decision Drafts section in implementation-planning"
+```
+
+---
+
+### Task 3: validator 자기완결 trigger + 헤딩 contract
+
+**Files:**
+- Modify: `validators/validate-run.py` (`PLANNING_REQUIRED_SECTIONS` + 신규 함수 + dispatch)
+- Modify: `tests/contract/test_decision_drafts.py` (validator 테스트 추가)
+
+**Interfaces:**
+- Consumes: Task 1 의 `decisionDrafts[]`, `implementationPlanning.stages[].stepwiseExecution[].{files,action}`.
+- Produces: `_validate_implementation_planning_decision_drafts(data: dict, failures: list[str]) -> None`.
+
+- [ ] **Step 1: validator 실패 테스트 추가** — `tests/contract/test_decision_drafts.py` 끝에 추가:
+
+```python
+VALIDATOR_PATH = REPO_ROOT / "validators" / "validate-run.py"
+
+
+def _load_validator():
+    spec = importlib.util.spec_from_file_location("validate_run", VALIDATOR_PATH)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+@pytest.fixture(scope="module")
+def vr():
+    return _load_validator()
+
+
+def _planning_data(drafts, stages):
+    return {
+        "header": {"taskType": "implementation-planning"},
+        "implementationPlanning": {"decisionDrafts": drafts, "stages": stages},
+    }
+
+
+def test_drafts_without_materialization_step_fails(vr):
+    failures: list[str] = []
+    data = _planning_data(
+        [dict(_SAMPLE_DRAFT)],
+        [{"stepwiseExecution": [
+            {"step": 1, "action": "GREEN: add classifier table", "files": "migrations/x.sql"},
+        ]}],
+    )
+    vr._validate_implementation_planning_decision_drafts(data, failures)
+    assert failures != []
+
+
+def test_drafts_with_materialization_step_passes(vr):
+    failures: list[str] = []
+    data = _planning_data(
+        [dict(_SAMPLE_DRAFT)],
+        [{"stepwiseExecution": [
+            {"step": 1, "action": "GREEN: add classifier table", "files": "migrations/x.sql"},
+            {"step": 2,
+             "action": "create decision record from §5.4 Decision Drafts 0007-classifier-table-naming",
+             "files": ".okstra/decisions/0007-classifier-table-naming.md"},
+        ]}],
+    )
+    vr._validate_implementation_planning_decision_drafts(data, failures)
+    assert failures == []
+
+
+def test_empty_drafts_is_noop(vr):
+    failures: list[str] = []
+    data = _planning_data([], [{"stepwiseExecution": [{"step": 1, "action": "x", "files": "y"}]}])
+    vr._validate_implementation_planning_decision_drafts(data, failures)
+    assert failures == []
+```
+
+`_SAMPLE_DRAFT` 는 Task 1 에서 이미 이 파일 상단에 정의됨 — 재사용.
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/contract/test_decision_drafts.py -k "materialization or noop" -v`
+Expected: FAIL — `AttributeError: module 'validate_run' has no attribute '_validate_implementation_planning_decision_drafts'`.
+
+- [ ] **Step 3: validator 함수 추가** — `validators/validate-run.py` 의 `_validate_implementation_planning_cross_project` 함수([:1534-1562](../../../validators/validate-run.py:1534)) **바로 뒤**에 삽입:
+
+```python
+def _validate_implementation_planning_decision_drafts(data: dict, failures: list[str]) -> None:
+    """`decisionDrafts` 가 비어있지 않으면 어느 stage 의 stepwiseExecution step 이
+    `.okstra/decisions/` 파일을 생성하는 materialization step 을 포함해야 한다.
+    프로파일 Decision-record evaluation 의 "approved plan stepwise MUST include
+    Create .okstra/decisions/<NNNN>-<slug>.md" 를 실제 강제한다. draft 존재 자체가
+    trigger 이므로 self-contained 하다.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    if not (ip.get("decisionDrafts") or []):
+        return
+    has_materialization = any(
+        ".okstra/decisions/" in (step.get("files") or "")
+        or ".okstra/decisions/" in (step.get("action") or "")
+        for stage in (ip.get("stages") or [])
+        if isinstance(stage, dict)
+        for step in (stage.get("stepwiseExecution") or [])
+        if isinstance(step, dict)
+    )
+    if not has_materialization:
+        failures.append(
+            "final-report data.json: implementationPlanning.decisionDrafts is "
+            "non-empty but no stage's stepwiseExecution creates a "
+            "`.okstra/decisions/<NNNN>-<slug>.md` file. The approved plan must "
+            "materialize each decision draft via a stepwise step (profile "
+            "Decision-record evaluation)."
+        )
+```
+
+- [ ] **Step 4: dispatch 배선** — `validators/validate-run.py:1492-1493`
+
+```python
+    elif task_type == "implementation-planning":
+        _validate_implementation_planning_cross_project(data, failures)
+        _validate_implementation_planning_decision_drafts(data, failures)
+```
+
+- [ ] **Step 5: 헤딩 contract 추가** — `validators/validate-run.py:1132`
+
+`PLANNING_REQUIRED_SECTIONS` 튜플([:1132-1144](../../../validators/validate-run.py:1132))의 `"Cross-Project Dependencies",` 다음에 `"Decision Drafts",` 추가.
+
+- [ ] **Step 6: validator 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/contract/test_decision_drafts.py -v`
+Expected: PASS — 모양 7개 + validator 3개 모두 통과.
+
+- [ ] **Step 7: 커밋**
+
+```bash
+git add validators/validate-run.py tests/contract/test_decision_drafts.py
+git commit -m "feat(validate-run): gate decisionDrafts on materialization step + heading"
+```
+
+---
+
+### Task 4: 프로파일 / report-writer prose 정합
+
+**Files:**
+- Modify: `prompts/profiles/implementation-planning.md` (heading contract line 57; Decision-record evaluation 111-116; self-review)
+- Modify: `agents/workers/report-writer-worker.md` (populate 안내 1줄)
+
+**Interfaces:**
+- Consumes: Task 1-3 의 필드명·검증 규칙. prose 만 변경, 코드 무변경.
+
+- [ ] **Step 1: heading contract 갱신** — `prompts/profiles/implementation-planning.md:57`
+
+`Cross-Project Dependencies`, 다음(혹은 `Requirement Coverage` 인근)에 `Decision Drafts` 를 필수 substring 목록에 추가. 즉 `... \`Cross-Project Dependencies\`, \`Decision Drafts\`, \`Validation Checklist\`, ...` 형태.
+
+- [ ] **Step 2: Decision-record evaluation 블록 재작성** — `prompts/profiles/implementation-planning.md:115-116`
+
+기존 두 단락(line 115 "If **all three** hold, attach a decision draft as a report appendix section ..." + line 116 "The drafts are NOT written by this phase. ...")을 다음으로 교체:
+
+```markdown
+    If **all three** hold, record a decision draft as a `decisionDrafts[]` row (rendered in §5.4 `### Decision Drafts`, one `#### <number>-<slug>` subsection each). Each row carries `number` (= `(max existing in <PROJECT_ROOT>/.okstra/decisions/ + 1)` zero-padded to ≥4 digits), `slug` (kebab-case), `status: Proposed`, and the `context` / `decision` / `consequences` / `alternativesConsidered` fields (`alternativesConsidered` names the rejected alternatives and why). If any of the three criteria is missing, do NOT raise a draft — instead record a `skippedAdrCandidates[]` row (`topic` + `reason: <criterion that failed>`, rendered as a `skipped adr-candidate: … — reason: …` line under the same section) so the next reader knows the candidate was evaluated and intentionally dropped.
+    The decision files are NOT written by this phase. The approved plan's stepwise execution order MUST include the step `Create <PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md from the §5.4 Decision Drafts subsection <number>-<slug>` (materializing the structured fields into the file's `## Status / ## Context / ## Decision / ## Consequences / ## Alternatives Considered` shape) so the `implementation` run commits the file inside okstra's subtree. `validators/validate-run.py` enforces this: a non-empty `decisionDrafts` whose stages carry no stepwise step referencing `.okstra/decisions/` is `contract-violated`.
+```
+
+- [ ] **Step 3: self-review 패스에 점검 추가** — `prompts/profiles/implementation-planning.md` self-review([:123-132](../../../prompts/profiles/implementation-planning.md:123))의 마지막 항목(9. Cross-project) 다음에 추가:
+
+```markdown
+  10. **Decision-draft materialization check** — `decisionDrafts` 가 비어있지 않으면, 매칭 materialization step(`.okstra/decisions/<NNNN>-<slug>.md` 생성)이 어느 stage 의 stepwise 에 존재하는지, draft 개수와 materialization step 이 1:1 로 대응하는지 reviewer 로서 확인한다. validator 는 step 의 *존재*만 보므로 `<NNNN>-<slug>` 정확성·개수 대응은 self-review 가 책임진다.
+```
+
+- [ ] **Step 4: report-writer populate 안내 추가** — `agents/workers/report-writer-worker.md`
+
+implementation-planning requirementCoverage 안내([:103](../../../agents/workers/report-writer-worker.md:103)) 다음에 한 줄 추가:
+
+```markdown
+- For `implementation-planning`, also populate `implementationPlanning.decisionDrafts` (one row per decision meeting all three decision-record criteria; `[]` otherwise) and `implementationPlanning.skippedAdrCandidates` (evaluated-but-dropped adr-candidates; `[]` otherwise). The schema excerpt enumerates the row shape; the renderer emits §5.4 `### Decision Drafts`.
+```
+
+- [ ] **Step 5: phase contract validator 확인**
+
+Run: `bash validators/validate-workflow.sh`
+Expected: exit 0 — 프로파일/템플릿 헤딩 contract 정합.
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add prompts/profiles/implementation-planning.md agents/workers/report-writer-worker.md
+git commit -m "docs(profile): align Decision Drafts prose with structured fields"
+```
+
+---
+
+### Task 5: 빌드 동기화 + 완료 게이트
+
+**Files:** 없음(빌드 출력 `runtime/` 은 gitignored — 커밋 대상 아님)
+
+- [ ] **Step 1: runtime 동기화**
+
+Run: `npm run build`
+Expected: exit 0 — 소스 6개 디렉터리가 `runtime/` 으로 rsync.
+
+- [ ] **Step 2: 완료 게이트 — 전체 스위트**
+
+Run: `npm run check`
+Expected: exit 0 — test:js 후 test:py 전부 통과. 실패 시 해당 Task 로 돌아가 수정.
+
+- [ ] **Step 3: 빌드 산출물 정합 스모크**
+
+Run: `node bin/okstra doctor`
+Expected: 런타임/스킬 진단 정상.
+
+---
+
+## Self-Review
+
+**1. Spec coverage** (스펙 §3 각 항목 → Task):
+- §3.1 데이터 모델(`$defs` 2개, properties+required) → Task 1 Step 3-4 ✓
+- §3.2 렌더(템플릿 §5.4 블록) + i18n → Task 2 Step 3-5 ✓
+- §3.3(a) 모양 강제(스키마) → Task 1 ✓ / §3.3(b) 자기완결 trigger → Task 3 Step 3-4 ✓ / §3.3(c) 헤딩 contract → Task 2 Step 6 + Task 3 Step 5 + Task 4 Step 1 (세 곳) ✓
+- §3.4 프로파일 prose → Task 4 Step 1-3 ✓
+- §3.5 report-writer 정합 → Task 4 Step 4 ✓
+- §3.6 excerpt/빌드 → Task 1 Step 6(`test_no_dangling_refs` 자동 커버) + Task 5 Step 1 ✓
+- §6 검증 계획(render/validator/excerpt/픽스처 + `npm run check`) → Task 1·2·3 테스트 + Task 5 ✓
+- §7 한계(완전성·1:1 정확성 watertight 불가) → Task 4 Step 3 self-review prose 로 보강 ✓
+
+**2. Placeholder scan:** 모든 step 에 실제 코드/명령/기대출력 명시. "TBD"/"적절히"/"유사하게" 없음. ✓
+
+**3. Type consistency:** 필드명 `number`/`slug`/`status`/`context`/`decision`/`consequences`/`alternativesConsidered`(draft), `topic`/`reason`(skipped), 함수 `_validate_implementation_planning_decision_drafts`, i18n 키 `decisionDraftFields.{status,context,decision,consequences,alternativesConsidered}` — Task 1→2→3→4 전체에서 동일하게 사용. 헤딩 substring `Decision Drafts` 는 세 곳(테스트/validator/프로파일) 일치. ✓