Migration Kit

xlsx/csv -> PostgreSQL 마이그레이션을 대상으로, Blue Team이 spec을 만들고 Red Team이 이를 독립 검수해 go / review-needed / blocked를 판정하는 CLI-first MVP다.

이 저장소로 할 수 있는 일

• 소스 파일 csv/xlsx를 읽어 target schema 기준의 매핑 spec 초안을 만든다
• spec을 검증하고 승인 상태로 고정한다
• 실제 적재 없이 dry-run으로 loadable/reject를 분류한다
• Red Team 기준의 reconcile로 최종 verdict와 sign-off report를 만든다
• 필요하면 통과 행만 export-load로 적재 artifact로 내보낸다

언제 이 도구를 써야 하나

• 데이터 이행 전에 spec과 품질 이슈를 먼저 검토하고 싶을 때
• 적재 SQL보다 무엇이 왜 막히는지를 먼저 설명해야 할 때
• Blue Team 작성과 Red Team 검수를 분리해서 증적을 남겨야 할 때

Status

• MVP 로드맵 구현과 roadmap wrap-up 완료
• 선택된 next product cut closeout 완료
• 현재 남은 일은 소규모 optional backlog 정리
• 최신 기준 검증: make check -> 61 passed

Core Surface

• 사용자 명령:
  • smk init
  • smk draft-spec
  • smk validate-spec
  • smk approve-spec
  • smk dry-run
  • smk export-load
  • smk reconcile
• 내부 개발 하네스:
  • smk workflow-init
  • smk workflow-advance
  • smk workflow-status

Implemented Baseline

• source: csv, xlsx 단일 시트
• target metadata: schema yaml, optional code table/hints
• draft adapter:
  • heuristic-bootstrap
  • openai-chat-completions:<model-name>
  • openai-responses:<model-name>
  • alias: heuristic, local-heuristic, openai-chat
• deterministic fail-closed:
  • unknown field / transform / transform params
  • spec approval missing
  • source parsing failure
  • unknown draft adapter
  • export artifact summary mismatch
• PII-safe defaults:
  • evidence/report/reject artifacts masking 우선

먼저 읽을 문서

1. Getting Started
2. CLI Contract
3. MVP Spec
4. Test Plan

Regression Baseline

• members: go
• members-review-needed: review-needed
• members-zero-loadable: no blocker but zero loadable rows -> blocked
• members-export-integrity: tampered export -> fail-closed
• applications: blocked
• policy baseline:
  • delivery-loop.yaml
  • variation-loop.yaml

빠른 시작

1. 개발 환경 준비

make setup-dev

2. 프로젝트 뼈대 생성

./.venv/bin/smk init ./demo

3. 초안 spec 생성

./.venv/bin/smk --project-dir ./demo draft-spec --source fixtures/members.csv --schema schemas/target-schema.yaml --out specs/draft-spec.yaml

4. spec 검증과 승인

./.venv/bin/smk --project-dir ./demo validate-spec --spec specs/mapping-spec.yaml
./.venv/bin/smk --project-dir ./demo approve-spec --spec specs/mapping-spec.yaml --approver lead01 --note "reviewed"

5. dry-run과 reconcile

./.venv/bin/smk --project-dir ./demo dry-run --source fixtures/members.csv --spec specs/mapping-spec.yaml --out-dir runs/demo-01
./.venv/bin/smk --project-dir ./demo reconcile --run runs/demo-01 --out reports/sign-off-demo-01.md

6. 필요 시 export-load

./.venv/bin/smk --project-dir ./demo export-load --run runs/demo-01 --format csv --out artifacts/load-demo-01.csv

7. 반복 검증

make check

권장 사용 순서

1. smk init으로 작업 디렉터리와 샘플 계약 파일을 만든다.
2. target schema와 source 파일 위치를 프로젝트 기준으로 맞춘다.
3. smk draft-spec으로 초안을 만들거나 수동으로 spec을 작성한다.
4. smk validate-spec으로 구조 오류와 unsupported transform을 먼저 막는다.
5. smk approve-spec으로 검토 완료 상태를 고정한다.
6. smk dry-run으로 reject와 loadable row를 분류한다.
7. smk reconcile로 최종 verdict와 근거를 확인한다.
8. go가 아니면 spec, code table, source 정리를 수정하고 같은 흐름을 다시 반복한다.
9. go 또는 적절한 승인 이후에만 smk export-load를 사용한다.

명령 결과를 어떻게 읽어야 하나

• draft-spec:
  • 초안 spec과 evidence summary를 만든다
  • LLM/adapter는 초안 보조만 하고 최종 출력은 deterministic post-processing을 거친다
• validate-spec:
  • spec 문법, target field 참조, transform 허용 여부를 검증한다
• dry-run:
  • dry-run-summary.json, rejects.csv, load-preview.csv를 만든다
• reconcile:
  • go / review-needed / blocked verdict와 sign-off report를 만든다
  • field_issue_summary, recommended_next_action, export integrity 결과를 함께 본다
• export-load:
  • loadable row만 artifact로 만든다
  • checksum과 row count가 summary에 남는다

산출물 위치

• schemas/: target schema 예시와 계약 파일
• specs/: mapping spec
• runs/: dry-run 결과물
• artifacts/: export-load 결과물
• reports/: validation report, sign-off report
• fixtures/: 회귀용 시나리오 샘플

LLM 사용 경계

• 허용:
  • field mapping 초안 제안
  • code mapping 초안 제안
  • ambiguous field 설명
• 금지:
  • approval 없는 spec 확정
  • verdict 자동 생성
  • fail-closed 규칙 우회
• 정리:
  • LLM은 draft-spec 보조 계층까지만 사용하고, 실제 검증/판정/무결성 확인은 deterministic engine이 담당한다

Verification

• local:
  • first-time setup: make setup-dev
  • repeatable local check: make check
• scripts:
  • bootstrap-dev.sh
  • check.sh
• CI:
  • ci.yml

Reference Docs

• getting started:
  • Getting Started
• current status:
  • Roadmap
  • Context Memory
  • Next Product Cut
  • Adapter/Provider Backlog
  • OpenAI-Compatible Provider Guide
• product contracts:
  • MVP Spec
  • CLI Contract
  • Implementation Plan
  • Test Plan
• internal workflow:
  • Development Workflow