refactor(specs): migrate SPEC.md to raw/design/specs/ski-NNN-*.md (issue-scoped)

[pko89403]

한 줄 요약

• 루트 SPEC.md 단일 파일 관행을 raw/design/specs/ski-NNN-<slug>.md 이슈 스코프 레이아웃으로 전환합니다. 현재 uncommitted 상태였던 SKI-11 스펙(upstream Graphify public entrypoint 복구)을 첫 번째 파일(ski-011-*.md)로 실제 적용합니다.

배경 / 문제

• 기존 상태: 루트 SPEC.md가 "현재 active spec"을 담는 단일 파일. 새 이슈마다 덮어쓰기.
• 문제 3가지:
  1. 히스토리 파괴 — 이전 SKI-N 스펙이 main에 보존되지 않음 (ADR은 adr-NNN-*.md라 문제 없음).
  2. Graphify source boundary 역전 — SPEC.md는 graphify 입력에서 명시 제외, 반면 raw/design/specs/는 이미 source corpus. spec이 knowledge graph에 투명.
  3. 3-레이어 다이어그램이 이미 raw/design/specs/를 보여줌 (CLAUDE.md:52) — 구조는 pre-authored, 관행만 아직 미전환.
• 증상: 새 브랜치 + worktree 생성 시 메인의 수정된 SPEC.md가 불일치 → 2중 편집 + main에 영구 uncommitted 변경 반복.
• 이번 PR의 목표: ADR 패턴과 동일한 이슈 스코프 convention으로 전환.

PR 대시보드

항목	내용
유형	refactor / docs
영향 범위	harness / docs / tests / specs layout
동작 변경	없음 (harness 주입 로직은 silent-skip이라 runtime 동일)
Breaking Change	없음 (SPEC.md를 외부 tool이 참조하지 않음)
관련 이슈	—
기준 브랜치	main

변경 묶음별 리뷰 가이드

변경 묶음	파일	무엇이 바뀌었나	리뷰 포인트
Harness code + test	scripts/execute.py, tests/test_execute_script.py	GUARDRAIL_FILES tuple에서 "SPEC.md" 제거 + 대응 fixture/assertion 제거	silent-skip 동작 유지, 기존 테스트 3건 assertion 유지
Skill 지시 전환	.agents/skills/{spec,plan,using-agent-skills}/SKILL.md, .agents/skills/spec/agents/openai.yaml	/spec은 raw/design/specs/ski-NNN-<slug>.md 생성, /plan은 해당 경로 읽기, meta-skill bullet 갱신	skill chain이 같은 경로를 가리키는지
Policy + README	.agents/policies/local-adaptation.md (line 80/92/99), README.md/README.ko.md (line 387/345), raw/README.md (line 22)	Output Locations / Language Conventions / Graphify boundary 기술 갱신	raw/design/specs/**가 한국어 유지 대상 + source corpus임 명시
File migration	SPEC.md → raw/design/specs/ski-011-upstream-graphify-entrypoint.md	git mv로 rename 추적. 현재 uncommitted SKI-11 내용 보존. 내부 자기참조 3곳 정리	git log --follow로 rename 감지 확인
Graphify refresh	graphify-out/*	raw/ 변경 감지해 auto-refresh 돈 결과	별도 chore 커밋

Before / After

Before

• 루트 SPEC.md 1개 파일 (현재 active만 보존, 이전 spec은 git history에만)
• GUARDRAIL_FILES가 SPEC.md 포함 → 매 executor preamble에 주입
• /spec 스킬이 루트 경로를 지시

After

• raw/design/specs/ski-NNN-<slug>.md 이슈 단위 파일 누적 (ADR 패턴)
• GUARDRAIL_FILES에서 SPEC 제거 → preamble 주입 없음. 에이전트가 on-demand Read
• /spec 스킬이 새 경로 지시, /plan 스킬이 해당 경로 읽기
• 첫 실적용: ski-011-upstream-graphify-entrypoint.md

검증

항목	결과	근거
테스트	✅	uv run pytest --ignore=mlx_runtime,cli_smoke_mlx,graphify_auto_refresh -q → 141 passed
린트	✅	uv run ruff check . → All checks passed
타입체크	✅	uv run mypy src → no issues (30 files)
SPEC.md 잔재	✅	grep -rn "SPEC\.md" 실제 소스 0 hit (의도된 ski-011 내부 history paragraph 1건만 유지)
루트 SPEC.md 제거	✅	test ! -f SPEC.md pass
Rename 추적	✅	git log --follow raw/design/specs/ski-011-*.md 정상
Graphify corpus	✅	auto-refresh가 raw/ 변경 감지해 code refresh 수행, ski-011이 graph 포함

남은 리스크 / 후속 작업

• Spec frontmatter 스키마 (status / date / issue-id / sources) 추가 — 현재 adr-NNN-*.md엔 있지만 ski-NNN-*.md엔 미정. 후속 convention PR.
• GitHub/Linear 이슈 tracker와 SKI-NNN 번호 동기화 관행 정립 — 현재 파일 sequence 자체로만 번호 매김.
• feature/graphify-upstream-entrypoint worktree의 stale SPEC.md (SKI-10 버전) 처리 — 해당 worktree가 작업 완료 후 rebase 필요.
• 주의: harness의 executor preamble에 spec 내용이 더이상 injection되지 않음. 에이전트가 이슈 스펙을 참조할 필요가 있으면 명시적 /plan 또는 Read tool로 접근 (skill 문서에 이미 반영).
• 리뷰 시 특히 볼 부분: skill 체인 (/spec → /plan)이 같은 경로 규약을 가리키는지, 그리고 raw/README.md의 source corpus 경계 기술이 현실과 일치하는지.