okstra 0.102.1 → 0.102.3

package/docs/superpowers/plans/2026-06-24-cross-project-precondition.md

@@ -1,542 +0,0 @@
-# Cross-Project Dependencies 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-planning 보고서에서 타 프로젝트(다른 repo·published 패키지) 의존을 1급·렌더되는 구조 필드 `crossProjectDependencies` 로 승격하고, soft "Recommended Next Step" 이 아니라 구체 작업이 명시된 "선행 필수"로 검증기에서 강제한다.
-
-**Architecture:** data.json(SSOT) → Jinja 템플릿 결정론적 렌더 구조를 그대로 따른다. 스키마에 `$defs/CrossProjectDependency` 와 `implementationPlanning.crossProjectDependencies` 배열을 추가(양방향 `direction` 통합), 템플릿 §5.4 에 엔트리별 블록 렌더, `validate-run.py` 에 DM `kind: cross-project` ↔ XP `upstream-precondition` 교차 필드 게이트를 둔다. 기존 미렌더 `## Cross-Repo Carry` 부록은 `downstream-carry` 방향으로 흡수돼 실제 렌더된다.
-
-**Tech Stack:** JSON Schema (Draft) + Jinja2 템플릿 + Python 검증기/테스트(pytest). 빌드는 `npm run build`(tools/build.mjs → runtime/ 동기화), 통합 게이트는 `npm run check`.
-
-## Global Constraints
-
-- `runtime/` 은 빌드 출력 — 직접 수정 금지. 소스(`schemas/`, `templates/`, `prompts/`, `validators/`, `agents/`)만 수정 후 `npm run build`.
-- pre-1.0 — backwards-compat shim 금지. enum/스키마는 자유롭게 확장한다.
-- 사용자 대면 문서·prose 는 한국어, 코드 식별자/경로/CLI 인자는 영어.
-- 완료 선언 전 `npm run check` 가 그대로 exit 0 (test:js 실패 시 test:py 미실행이므로 통합 명령으로 확인).
-- 검증기 동작 변경 = seed/소스 파일에 반영(개인 `.claude/` 아님).
-- 새 식별자(`crossProjectDependencies`, `CrossProjectDependency`, `XP-`, `cross-project`, 헤딩 `Cross-Project Dependencies`, i18n 키) 추가 후 전 사용처를 grep 으로 일관 확인.
-
-**스펙:** [docs/superpowers/specs/2026-06-24-cross-project-precondition-design.md](../specs/2026-06-24-cross-project-precondition-design.md)
-
----
-
-### Task 1: 스키마 — `CrossProjectDependency` def + 필드 + DM enum + 픽스처
-
-**Files:**
-- Modify: `schemas/final-report-v1.0.schema.json` (implementationPlanning.required @ 353-364, properties @ 366-414, DependencyRow enum @ 1369)
-- Modify: `tests/fixtures/final-report-data/implementation-planning-001.data.json` (implementationPlanning 블록)
-- Create: `tests/contract/test_cross_project_precondition.py`
-
-**Interfaces:**
-- Produces: `$defs/CrossProjectDependency` (id `^XP-\d{3,}$`, direction enum `upstream-precondition|downstream-carry`, project/requiredWork/verificationSignal/linkedWork/howToStart 모두 string minLength 1); `implementationPlanning.crossProjectDependencies: array<CrossProjectDependency>` (required, minItems 없음 → `[]` 허용); DependencyRow.kind 에 `cross-project` 추가.
-- Consumes: `okstra_ctl.final_report_schema.load_schema()` / `schema_validate(data, schema)` (스크립트가 PYTHONPATH 에 있음 — conftest).
-
-- [ ] **Step 1: 실패 테스트 작성** — 스키마가 새 필드/enum 을 수용·거부하는지
-
-```python
-# tests/contract/test_cross_project_precondition.py
-"""crossProjectDependencies 스키마 모양 + validate-run 교차 필드 게이트 단위 테스트.
-
-스키마는 각 XP 행의 7필드 비-빈을 보장하고(모양), validate-run 은
-DM `kind: cross-project` 가 있으면 XP `upstream-precondition` 행이 존재하는지(존재)를 본다.
-"""
-from __future__ import annotations
-
-import copy
-import importlib.util
-import json
-
-from _paths import REPO_ROOT
-
-import pytest
-
-from okstra_ctl.final_report_schema import load_schema, schema_validate
-
-FIXTURE = (
-    REPO_ROOT / "tests" / "fixtures" / "final-report-data"
-    / "implementation-planning-001.data.json"
-)
-
-
-@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_cross_project_rows_validates(schema, data):
-    assert schema_validate(data, schema) == []
-
-
-def test_empty_required_work_is_rejected(schema, data):
-    bad = copy.deepcopy(data)
-    bad["implementationPlanning"]["crossProjectDependencies"][0]["requiredWork"] = ""
-    assert schema_validate(bad, schema) != []
-
-
-def test_unknown_direction_is_rejected(schema, data):
-    bad = copy.deepcopy(data)
-    bad["implementationPlanning"]["crossProjectDependencies"][0]["direction"] = "sideways"
-    assert schema_validate(bad, schema) != []
-
-
-def test_dm_cross_project_kind_is_accepted(schema, data):
-    # 픽스처는 이미 kind='cross-project' DM 행을 포함한다(Task 1 Step 4).
-    kinds = [r["kind"] for r in data["implementationPlanning"]["dependencyMigrationRisk"]]
-    assert "cross-project" in kinds
-    assert schema_validate(data, schema) == []
-```
-
-- [ ] **Step 2: 테스트 실패 확인**
-
-Run: `python3 -m pytest tests/contract/test_cross_project_precondition.py -v`
-Expected: FAIL — 픽스처에 `crossProjectDependencies` 키가 없고 스키마에 def 가 없어 `KeyError`/검증 통과 실패.
-
-- [ ] **Step 3: 스키마에 def + 필드 + enum 추가**
-
-`schemas/final-report-v1.0.schema.json`:
-
-(a) DependencyRow enum (line 1369) 에 `cross-project` 추가:
-```json
-          "enum": ["order", "backfill", "flag-precondition", "repo-sequencing", "cross-project", "other"]
-```
-
-(b) `implementationPlanning.required` (line 353-364) 에 `crossProjectDependencies` 추가(`planBodyVerification` 뒤):
-```json
-        "requirementCoverage",
-        "planBodyVerification",
-        "crossProjectDependencies"
-```
-
-(c) `implementationPlanning.properties` 의 `planBodyVerification` 항목(line 413) 뒤에 추가:
-```json
-        "planBodyVerification": { "$ref": "#/$defs/PlanBodyVerification" },
-        "crossProjectDependencies": {
-          "type": "array",
-          "items": { "$ref": "#/$defs/CrossProjectDependency" }
-        }
-```
-
-(d) `$defs` 에 `DependencyRow` (line 1375 `},` 뒤) 신설:
-```json
-    "CrossProjectDependency": {
-      "type": "object",
-      "required": ["id", "direction", "project", "requiredWork", "verificationSignal", "linkedWork", "howToStart"],
-      "additionalProperties": false,
-      "properties": {
-        "id": { "type": "string", "pattern": "^XP-\\d{3,}$" },
-        "direction": { "enum": ["upstream-precondition", "downstream-carry"] },
-        "project": { "type": "string", "minLength": 1 },
-        "requiredWork": { "type": "string", "minLength": 1 },
-        "verificationSignal": { "type": "string", "minLength": 1 },
-        "linkedWork": { "type": "string", "minLength": 1 },
-        "howToStart": { "type": "string", "minLength": 1 }
-      }
-    },
-```
-
-- [ ] **Step 4: 픽스처에 샘플 행 추가**
-
-`tests/fixtures/final-report-data/implementation-planning-001.data.json` 의 `implementationPlanning` 블록에서:
-
-(a) `dependencyMigrationRisk` 배열에 `cross-project` DM 행 1개 추가:
-```json
-    { "id": "DM-002", "kind": "cross-project", "item": "common-api 가 isSlanted 컬럼을 publish 해야 jobs 가 컴파일된다.", "impact": "미publish 면 yarn install/compile 단계에서 resolution 실패.", "mitigation": "common-api 를 별도 okstra run 으로 먼저 진행 — XP-001 참조." }
-```
-
-(b) `implementationPlanning` 객체에 `crossProjectDependencies` 키 추가(upstream 1 + downstream 1):
-```json
-    "crossProjectDependencies": [
-      {
-        "id": "XP-001",
-        "direction": "upstream-precondition",
-        "project": "@fonts-ninja-org/common-api",
-        "requiredWork": "Font.d.ts 에 isSlanted 컬럼 추가 후 npm publish.",
-        "verificationSignal": "npm view @fonts-ninja-org/common-api version 이 ≥ 1.27.46 이고 Font.d.ts 에 isSlanted 가 존재.",
-        "linkedWork": "Stage 2 (yarn install) / Stage 3 (compile) — 신호 충족 전 진행 불가.",
-        "howToStart": "common-api repo 에서 okstra-brief (이 보고서 절대경로 Source Material) → okstra-run 으로 planning→implementation."
-      },
-      {
-        "id": "XP-002",
-        "direction": "downstream-carry",
-        "project": "@fonts-ninja-org/helpers",
-        "requiredWork": "이 run 이 노출한 classifier 결과를 helpers 가 소비하도록 어댑터 추가.",
-        "verificationSignal": "이 run 의 PR 머지 + classifier 엔드포인트 live.",
-        "linkedWork": "helpers 의 후속 okstra run 이 이 run 산출물을 외부 precondition 으로 소비.",
-        "howToStart": "helpers repo 에서 okstra-brief (이 보고서 절대경로 Source Material) → okstra-run."
-      }
-    ]
-```
-
-- [ ] **Step 5: 테스트 통과 확인**
-
-Run: `python3 -m pytest tests/contract/test_cross_project_precondition.py -v`
-Expected: PASS (4 passed — Task 3 의 validate-run 테스트는 아직 이 파일에 없음).
-
-- [ ] **Step 6: 커밋**
-
-```bash
-git add schemas/final-report-v1.0.schema.json tests/fixtures/final-report-data/implementation-planning-001.data.json tests/contract/test_cross_project_precondition.py
-git commit -m "feat(report-schema): add crossProjectDependencies field and cross-project DM kind"
-```
-
----
-
-### Task 2: 템플릿 + i18n — `### Cross-Project Dependencies` 렌더
-
-**Files:**
-- Modify: `templates/reports/final-report.template.md` (§5.4, Dependency/Migration Risk endif @ 218 직후)
-- Modify: `templates/reports/i18n/ko.json`, `templates/reports/i18n/en.json`
-- Modify: `tests/report/test_render_final_report.py` (`_PLANNING_REQUIRED` @ 43, planning 렌더 테스트 @ 95-123)
-
-**Interfaces:**
-- Consumes: `implementationPlanning.crossProjectDependencies` (Task 1), i18n 키 `sectionAside.crossProjectDependencies` / `emptyState.crossProjectDependencies` / `implementationPlanning.crossProjectFields.*` / `implementationPlanning.crossProjectRecognitionNote`.
-- Produces: 렌더 마크다운에 `### Cross-Project Dependencies` 헤딩 + 엔트리별 블록.
-
-- [ ] **Step 1: 실패 테스트 작성** — 렌더 결과에 헤딩·방향 태그·라벨·XP ID 가 있는지
-
-`tests/report/test_render_final_report.py` 의 `_PLANNING_REQUIRED` 튜플(line 43)에 추가:
-```python
-    "Plan Body Verification",
-    "Gate result",
-    "Cross-Project Dependencies",
-```
-
-그리고 새 테스트 함수 추가(파일 끝, 기존 import `_render_fixture`/`render`/`find_default_template`/`_load` 사용):
-```python
-def test_cross_project_dependencies_render():
-    rendered = _render_fixture("implementation-planning-001.data.json")
-    assert "### Cross-Project Dependencies" in rendered
-    assert "XP-001" in rendered
-    assert "[upstream-precondition]" in rendered
-    assert "[downstream-carry]" in rendered
-    assert "@fonts-ninja-org/common-api" in rendered
-
-
-def test_cross_project_dependencies_empty_state():
-    data = _load("implementation-planning-001.data.json")
-    data["implementationPlanning"]["crossProjectDependencies"] = []
-    rendered = render(data, template_path=find_default_template())
-    assert "### Cross-Project Dependencies" in rendered
-    # 빈 배열이면 엔트리 블록은 없고 empty-state 한 줄만.
-    assert "XP-001" not in rendered
-```
-
-- [ ] **Step 2: 테스트 실패 확인**
-
-Run: `python3 -m pytest tests/report/test_render_final_report.py -k cross_project -v`
-Expected: FAIL — 템플릿에 섹션이 없어 헤딩 미존재.
-
-- [ ] **Step 3: i18n 키 추가 (ko.json)**
-
-`templates/reports/i18n/ko.json`:
-- `sectionAside` 객체에: `"crossProjectDependencies": "프로젝트 간 의존성"`
-- `emptyState` 객체에: `"crossProjectDependencies": "- 다른 프로젝트에 대한 선행/후속 의존 없음."`
-- `implementationPlanning` 객체에:
-```json
-    "crossProjectFields": {
-      "requiredWork": "필요 작업",
-      "verificationSignal": "검증 신호",
-      "linkedWork": "연결된 작업",
-      "howToStart": "시작 방법"
-    },
-    "crossProjectRecognitionNote": "참고: 상대 프로젝트의 run 은 구조적으로 독립이다 — done-set·stage 번호·depends-on 이 모두 자기 repo 기준이며, 이 run 의 완료 stage 가 자동으로 done 으로 인식되지 않는다. 이 섹션은 상대 run 의 planning 을 seed 하는 narrative 입력일 뿐이다."
-```
-
-- [ ] **Step 4: i18n 키 추가 (en.json)**
-
-`templates/reports/i18n/en.json`:
-- `sectionAside` 객체에: `"crossProjectDependencies": "Cross-Project Dependencies"` (영문 헤딩 == aside → aside 생략, dependencyRisk 패턴과 동일)
-- `emptyState` 객체에: `"crossProjectDependencies": "- No upstream/downstream dependency on another project."`
-- `implementationPlanning` 객체에:
-```json
-    "crossProjectFields": {
-      "requiredWork": "Required work",
-      "verificationSignal": "Verification signal",
-      "linkedWork": "Linked work",
-      "howToStart": "How to start"
-    },
-    "crossProjectRecognitionNote": "Note: the other project's run is structurally independent — its done-set, stage numbers, and depends-on all resolve against its own repo, and this run's completed stages are NOT auto-recognized as done there. This section is narrative input that seeds the other run's planning only."
-```
-
-- [ ] **Step 5: 템플릿 블록 추가**
-
-`templates/reports/final-report.template.md` 의 `### Dependency / Migration Risk` 블록 `{%- endif %}` (line 218) 직후, `### Validation Checklist` (line 220) **앞**에 삽입:
-```jinja
-### Cross-Project Dependencies{% if t("sectionAside.crossProjectDependencies") != "Cross-Project Dependencies" %} ({{ t("sectionAside.crossProjectDependencies") }}){% endif %}
-
-{% if implementationPlanning.crossProjectDependencies | length == 0 -%}
-{{ t("emptyState.crossProjectDependencies") }}
-{%- else %}
-{% for xp in implementationPlanning.crossProjectDependencies %}
-**{{ xp.id }} — [{{ xp.direction }}] {{ xp.project }}**
-
-- {{ t("implementationPlanning.crossProjectFields.requiredWork") }}: {{ xp.requiredWork }}
-- {{ t("implementationPlanning.crossProjectFields.verificationSignal") }}: {{ xp.verificationSignal }}
-- {{ t("implementationPlanning.crossProjectFields.linkedWork") }}: {{ xp.linkedWork }}
-- {{ t("implementationPlanning.crossProjectFields.howToStart") }}: {{ xp.howToStart }}
-{% endfor %}
-{{ t("implementationPlanning.crossProjectRecognitionNote") }}
-{%- endif %}
-
-```
-
-- [ ] **Step 6: 테스트 통과 확인**
-
-Run: `python3 -m pytest tests/report/test_render_final_report.py -v`
-Expected: PASS (cross_project 2개 + 기존 planning substring 테스트 포함 전부).
-
-- [ ] **Step 7: 커밋**
-
-```bash
-git add templates/reports/final-report.template.md templates/reports/i18n/ko.json templates/reports/i18n/en.json tests/report/test_render_final_report.py
-git commit -m "feat(report): render Cross-Project Dependencies section in implementation-planning"
-```
-
----
-
-### Task 3: 검증기 — DM `cross-project` ↔ XP 교차 필드 게이트 + 헤딩 substring
-
-**Files:**
-- Modify: `validators/validate-run.py` (`PLANNING_REQUIRED_SECTIONS` @ 1132-1143; taskType 분기 @ 1488; 새 함수 `_validate_final_verification_consistency` @ 1530 인근에 형제 함수)
-- Modify: `tests/contract/test_cross_project_precondition.py` (Task 1 파일에 validate-run 테스트 추가)
-
-**Interfaces:**
-- Consumes: `data["implementationPlanning"]["dependencyMigrationRisk"]` / `["crossProjectDependencies"]` (Task 1 모양).
-- Produces: `vr._validate_implementation_planning_cross_project(data, failures)` — DM `kind=='cross-project'` 가 있으면 XP `direction=='upstream-precondition'` 행 ≥ 1 을 강제, 아니면 `failures` 에 메시지 append.
-
-- [ ] **Step 1: 실패 테스트 작성** — Task 1 의 `test_cross_project_precondition.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(dm_rows, xp_rows):
-    return {
-        "header": {"taskType": "implementation-planning"},
-        "implementationPlanning": {
-            "dependencyMigrationRisk": dm_rows,
-            "crossProjectDependencies": xp_rows,
-        },
-    }
-
-
-def test_cross_project_dm_without_upstream_xp_fails(vr):
-    failures: list[str] = []
-    data = _planning_data(
-        [{"id": "DM-001", "kind": "cross-project", "item": "x", "impact": "y", "mitigation": "z"}],
-        [],
-    )
-    vr._validate_implementation_planning_cross_project(data, failures)
-    assert failures != []
-
-
-def test_cross_project_dm_with_upstream_xp_passes(vr):
-    failures: list[str] = []
-    data = _planning_data(
-        [{"id": "DM-001", "kind": "cross-project", "item": "x", "impact": "y", "mitigation": "z"}],
-        [{"id": "XP-001", "direction": "upstream-precondition", "project": "p",
-          "requiredWork": "w", "verificationSignal": "s", "linkedWork": "l", "howToStart": "h"}],
-    )
-    vr._validate_implementation_planning_cross_project(data, failures)
-    assert failures == []
-
-
-def test_no_cross_project_dm_is_noop(vr):
-    failures: list[str] = []
-    data = _planning_data(
-        [{"id": "DM-001", "kind": "order", "item": "x", "impact": "y", "mitigation": "z"}],
-        [],
-    )
-    vr._validate_implementation_planning_cross_project(data, failures)
-    assert failures == []
-```
-
-- [ ] **Step 2: 테스트 실패 확인**
-
-Run: `python3 -m pytest tests/contract/test_cross_project_precondition.py -k "dm or noop" -v`
-Expected: FAIL — `AttributeError: module 'validate_run' has no attribute '_validate_implementation_planning_cross_project'`.
-
-- [ ] **Step 3: 검증 함수 추가** — `validators/validate-run.py` 의 `_validate_final_verification_consistency` 정의(line 1530) **앞**에 삽입
-
-```python
-def _validate_implementation_planning_cross_project(data: dict, failures: list[str]) -> None:
-    """타 프로젝트 의존을 DM 행(`kind == 'cross-project'`)으로 선언했다면
-    `crossProjectDependencies` 에 `direction == 'upstream-precondition'` 행이
-    반드시 있어야 한다 — 실제 선행 필수 의존이 soft `recommendedNextSteps`
-    추천으로 새어나가지 못하게 강제한다. 각 XP 행의 필드 비-빈은 스키마가
-    보장하고, 이 검사는 cross-project DM 신호가 있을 때 XP 행이 *존재*하는지를 본다.
-    """
-    ip = data.get("implementationPlanning")
-    if not isinstance(ip, dict):
-        return
-    dm_rows = ip.get("dependencyMigrationRisk") or []
-    has_cross_project_dm = any(
-        isinstance(r, dict) and r.get("kind") == "cross-project" for r in dm_rows
-    )
-    if not has_cross_project_dm:
-        return
-    xp_rows = ip.get("crossProjectDependencies") or []
-    has_upstream = any(
-        isinstance(r, dict) and r.get("direction") == "upstream-precondition"
-        for r in xp_rows
-    )
-    if not has_upstream:
-        failures.append(
-            "final-report data.json: a dependencyMigrationRisk row has "
-            "kind='cross-project' but crossProjectDependencies carries no "
-            "direction='upstream-precondition' entry. Record the cross-project "
-            "dependency as a mandatory precondition (concrete requiredWork / "
-            "verificationSignal / howToStart) — not a soft Recommended Next Step."
-        )
-```
-
-- [ ] **Step 4: taskType 분기에서 호출** — line 1488 의 final-verification 분기 옆에 추가
-
-기존:
-```python
-    if (data.get("header") or {}).get("taskType") == "final-verification":
-        _validate_final_verification_consistency(data, failures)
-```
-로 바꾼다:
-```python
-    task_type = (data.get("header") or {}).get("taskType")
-    if task_type == "final-verification":
-        _validate_final_verification_consistency(data, failures)
-    elif task_type == "implementation-planning":
-        _validate_implementation_planning_cross_project(data, failures)
-```
-
-- [ ] **Step 5: 헤딩 substring 게이트 추가** — `PLANNING_REQUIRED_SECTIONS` (line 1132-1143)
-
-```python
-    "Requirement Coverage",
-    "Plan Body Verification",
-    "Cross-Project Dependencies",
-)
-```
-
-- [ ] **Step 6: 테스트 통과 확인**
-
-Run: `python3 -m pytest tests/contract/test_cross_project_precondition.py -v`
-Expected: PASS (7 passed — 스키마 4 + validate-run 3).
-
-- [ ] **Step 7: 커밋**
-
-```bash
-git add validators/validate-run.py tests/contract/test_cross_project_precondition.py
-git commit -m "feat(validate-run): gate cross-project DM rows on upstream-precondition entry"
-```
-
----
-
-### Task 4: 프로파일 prose + report-writer 동기화 (doc-only)
-
-**Files:**
-- Modify: `prompts/profiles/implementation-planning.md` (Cross-Repo Carry 부록 @ 94-98; 섹션 헤딩 contract @ 57; deliverable shape @ 61-116; self-review @ 122-130)
-- Modify: `prompts/lead/report-writer.md` (Recommended Next Steps 정책 @ 284 인근)
-
-**TDD exemption:** prose-only — 런타임 동작이 없는 문서 변경. 검증은 `bash validators/validate-workflow.sh` (phase contract) + Task 5 의 `npm run check`.
-
-- [ ] **Step 1: Cross-Repo Carry 부록 재작성 (양방향 통합)**
-
-`prompts/profiles/implementation-planning.md` 의 `**Cross-repo carry packet ...**` 불릿(94-98)을, freeform 부록이 아니라 **구조 필드 `crossProjectDependencies` 채우기**를 지시하도록 교체. 핵심 문구(한국어):
-- "타 프로젝트(다른 repo / 다른 top-level 배포 모듈 / published 패키지)에 대한 의존은 `crossProjectDependencies` 배열에 `XP-NNN` 행으로 기록한다."
-- `direction: upstream-precondition` = 이 run 이 상대의 선행 작업을 기다림(선행 필수). `requiredWork` = 상대가 만들어야 할 구체 작업, `verificationSignal` = 이 run 이 진행 전 관측할 신호(PR 머지 / 엔드포인트 live / 버전 publish), `linkedWork` = 신호 충족 전 막히는 이 계획의 stage/step, `howToStart` = 상대 repo 에서 `okstra-brief`(이 보고서 절대경로 Source Material) → `okstra-run`.
-- `direction: downstream-carry` = 이 run 이 상대가 쓸 것을 만들어 줌(기존 carry). `requiredWork` = 상대가 후속 구현할 B-portion, `verificationSignal` = 상대가 확인할(이 run 이 인도한) 신호, `howToStart` 동일.
-- 기존 "Recognition caveat" 문구는 렌더 노트(i18n `crossProjectRecognitionNote`)로 이전됐음을 명시하고, "이 run 은 상대 repo 트리·`.okstra/` 에 쓰지 않는다"는 한계 유지.
-- cross-repo dependency 는 `depends-on` 으로 표현 불가(그 게이트는 한 repo git graph 내부만 해소 — `_resolve_stage_base_commit`)라는 기존 경고 유지.
-
-- [ ] **Step 2: 섹션 헤딩 contract 갱신** — line 57 의 필수 substring 목록에 `Cross-Project Dependencies` 추가
-
-```
-... `Dependency`, `Cross-Project Dependencies`, `Validation Checklist`, `Rollback`, `Requirement Coverage`.
-```
-
-- [ ] **Step 3: deliverable shape 항목 추가** — `dependency / migration risk assessment` 불릿(line 100) 인근에 추가
-
-문구(한국어): "**Cross-Project Dependencies (조건부 필수):** 계획이 다른 프로젝트/repo/published 패키지의 작업에 의존하면 (a) `dependencyMigrationRisk` 에 `kind: cross-project` DM 행을, (b) `crossProjectDependencies` 에 매칭 `XP-NNN` 행을 둔다. upstream-precondition 행은 `requiredWork`·`verificationSignal`·`howToStart` 가 구체적이어야 하며(`validate-run.py` 가 DM `cross-project` ↔ upstream XP 1:1 을, 스키마가 필드 비-빈을 강제), 단일 프로젝트 계획은 빈 배열."
-
-- [ ] **Step 4: self-review 패스 + recommendedNextSteps 정책**
-
-(a) self-review(line 122-130)에 점검 항목 추가: "타 repo/패키지 의존을 빠뜨리지 않았는가; DM `cross-project` 행이 있으면 매칭 `upstream-precondition` XP 행이 있고 `requiredWork` 가 추상 표현이 아닌 구체 작업인가; cross-repo 작업을 한 task 의 stage 로 욱여넣지 않고 별도 run + XP 행으로 분리했는가."
-
-(b) recommendedNextSteps 정책 한 줄 추가: "cross-project 선행/후속의 substance 는 `crossProjectDependencies` 에 두고, `§3 Recommended Next Steps` 에는 그 섹션을 가리키는 포인터만 둔다(이중 기록 금지)."
-
-- [ ] **Step 5: report-writer.md 동기화** — line 284 `Recommended Next Steps` 항목에 한 줄 추가
-
-문구(한국어): "cross-project 의존은 `crossProjectDependencies`(§5.4 Cross-Project Dependencies)가 authoritative — `recommendedNextSteps` 에는 substance 를 복제하지 말고 그 섹션을 가리키는 포인터 한 줄만 둔다."
-
-- [ ] **Step 6: phase contract 검증**
-
-Run: `bash validators/validate-workflow.sh`
-Expected: exit 0 (phase contract 통과).
-
-- [ ] **Step 7: 커밋**
-
-```bash
-git add prompts/profiles/implementation-planning.md prompts/lead/report-writer.md
-git commit -m "docs(profile): elevate cross-project dependency to mandatory precondition in implementation-planning"
-```
-
----
-
-### Task 5: 빌드 + 통합 게이트 검증
-
-**Files:** (수정 없음 — 빌드/검증만)
-
-- [ ] **Step 1: 런타임 동기화**
-
-Run: `npm run build`
-Expected: exit 0 — 소스가 `runtime/` 으로 rsync (runtime/ 은 gitignore 라 커밋 대상 아님).
-
-- [ ] **Step 2: 새 식별자 일관성 grep**
-
-Run: `grep -rn "crossProjectDependencies\|CrossProjectDependency\|Cross-Project Dependencies\|cross-project" schemas/ templates/ validators/ prompts/ tests/ | grep -v runtime/`
-Expected: schema·template·i18n·validator·profile·test 에 일관되게 등장, orphan(정의만 있고 사용 없음 / 사용만 있고 정의 없음) 없음.
-
-- [ ] **Step 3: 통합 게이트**
-
-Run: `npm run check`
-Expected: exit 0 — JS 테스트 + pytest 전체 통과. (실패 시 해당 도메인만 재현: `python3 -m pytest tests/report tests/contract -v`.)
-
-- [ ] **Step 4: 회귀 확인 — 다른 planning 데이터 구성처**
-
-Run: `grep -rln "implementationPlanning" tests/ | grep -v runtime/`
-Expected: `crossProjectDependencies` 를 required 로 올렸으므로 다른 planning data.json 을 직접 만드는 테스트가 있으면 `[]` 라도 넣어야 함 — Step 3 에서 실패로 드러나면 해당 fixture/빌더에 `"crossProjectDependencies": []` 추가 후 재실행.
-
-- [ ] **Step 5: 최종 커밋 (회귀 수정이 있었을 때만)**
-
-```bash
-git add -A
-git commit -m "test: backfill crossProjectDependencies in planning fixtures"
-```
-
----
-
-## Self-Review
-
-**1. Spec coverage:**
-- 스펙 §3.1 데이터 모델 → Task 1. §3.2 렌더 → Task 2. §3.3 강제(모양/존재/헤딩) → Task 1(스키마 모양) + Task 3(교차 필드·헤딩). §3.4 프로파일 prose → Task 4. §3.5 excerpt 빌드 → `schema_excerpt.py` 가 `$ref` transitive closure 로 자동 포함(코드 변경 불필요, Task 5 grep 으로 확인). §6 검증 계획 → 각 Task 의 테스트 + Task 5. 갭 없음.
-
-**2. Placeholder scan:** TBD/TODO/"적절히 처리" 없음. 모든 코드 step 은 실제 JSON/Jinja/Python 블록 포함.
-
-**3. Type consistency:** `crossProjectDependencies`(필드), `CrossProjectDependency`(def), `XP-NNN`(id), `cross-project`(DM kind), `upstream-precondition`/`downstream-carry`(direction), i18n 키 `crossProjectFields.{requiredWork,verificationSignal,linkedWork,howToStart}` / `crossProjectRecognitionNote` / `sectionAside.crossProjectDependencies` / `emptyState.crossProjectDependencies` — Task 1~3 전반에서 동일 표기. `_validate_implementation_planning_cross_project` 함수명 Task 3 Step 1/3/4 일치. 헤딩 `### Cross-Project Dependencies` 템플릿·테스트·검증기 substring 일치.