seokang-sk 0.7.2 → 0.9.0

package/README.MD

@@ -201,6 +201,7 @@ sk status
 |  |- sk-plan              # 기획/설계 응답 워크플로
 |  |- sk-counseling-feedback # 상담 녹음 로컬 전사·난이도·HTML 피드백
 |  |- sk-db                # DB 변경 워크플로
+|  |- sk-local-db          # 터미널 입력 없는 격리 local DB 셋업·snapshot 워크플로
 |  |- sk-design-system     # 디자인 시스템 점검/구축
 |  |- sk-docs              # 변경 문서 작성
 |  |- sk-git               # git add/commit/push 워크플로
@@ -263,12 +264,15 @@ Windows Git Bash에서는 사용자 경로에 맞춰 `cd /c/Users/<user>/.agents
 - `sk identity status`: 선택적 GitHub operator 진단 정보 확인
 - `sk guard implementation --db-impact`: 이전 버전 호환용 안내. DB 코드 작성은 허용하고 실행은 금지
 - `sk guard db-execution`: local test/CI/일반 build 전에 production DB 자동 실행 경로를 strict 검사. `$sk-deploy`는 내부 deploy-packaging mode로 실행되지 않는 DB test source를 허용하고 실제 test/migration 실행만 차단
+- `sk db local setup|status`: Mac/Windows 공용 Docker local DB 생성과 상태 확인
+- `sk db local copy-production|restore|apply|reset`: OWNER의 sanitized snapshot과 명시 승인된 동일-workspace plain snapshot 생성·복원, managed local DB migration 검증, policy 변경 후 명시적 초기화
 - `sk guard git --action push --branch <name> --repo <name>`: OWNER main push와 NON_OWNER 작업 branch/PR 경계 확인
 - `sk guard stage pre-add|pre-commit <path ...>`: intended commit path와 Git index 일치 검사
 - `sk guard secrets --worktree` / `--staged` / `--outbound --remote origin`: add, commit, push 직전 secret hard-fail
 - `sk guard deploy --environment <name> --artifact <type> --action <action> --db-impact-status <status>`: 배포 credential 및 DB 무실행 경계 안내
 - 구현/commit/작업 branch는 identity 확인이나 cache를 요구하지 않는다. OWNER의 canonical `main`/`master` 직접 push는 GitHub ACL을 사용하고, 배포는 사용자 유형이 아니라 local credential과 원격 권한으로 실행한다. NON_OWNER Git 작업은 개인 fork PR까지만 진행한다.
 - [상세 CLI 가이드](docs/setup/sk-cli-guide.md)를 기준 문서로 사용
+- [Local DB 신규 개발자 온보딩](docs/setup/local-db-onboarding.md)을 프로젝트 DB 셋업 기준으로 사용
 
 ---
 
@@ -424,7 +428,7 @@ PR 처리는 예약 Inbox 자동화 없이 `$sk-git`에서 끝냅니다. OWNER
 
 모든 배포 스크립트는 build/upload/restart/publish 전에 DB execution boundary를 확인합니다. OWNER/NON_OWNER/root/seokang 같은 사용자 유형은 판정하지 않으며, local config의 SSH/npm/API/CDN credential로 실제 명령을 실행한 결과만 사용합니다.
 
-별도 테스트/개발/로컬 DB는 없습니다. DB 코드·SQL·migration 파일은 작성하고 PR로 검토할 수 있지만 Codex, local test, CI, deploy, start/restart script는 migration/DDL/DML/backfill/seed를 실행하지 않습니다. 실제 반영은 OWNER 사용자가 별도 IDE/DB 도구에서 수동 실행합니다.
+개발 DB는 `sk db local`이 검증한 프로젝트별 Docker container만 사용합니다. OWNER는 SELECT-only production credential로 raw dump를 port/volume 없는 tmpfs sanitizer에 스트리밍하고, project mask/verification을 통과한 snapshot만 다른 개발자에게 전달합니다. Raw data와 production credential은 공유하지 않습니다. CI, deploy, start/restart script는 migration/DDL/DML/backfill/seed를 실행하지 않으며 production 반영은 OWNER가 별도 IDE/DB 도구에서 수동 실행합니다.
 
 이 로컬 guard는 실수 방지층입니다. GitHub Free private 저장소의 실제 Git 차단은 `selink-lab` 원본 Read 권한과 개인 private fork/PR로 구성합니다. 배포는 local config에 credential이 설정된 환경에서만 가능하며 fork PR Actions에는 write token, secrets, variables를 전달하지 않습니다.
 

package/docs/playbooks/backend-implementation.md

@@ -47,11 +47,12 @@
   - 복잡한 분기 이유
   - 위험한 query 의도
 
-## 3-1. Production-Only DB Boundary
+## 3-1. Production / Managed Local DB Boundary
 
-- SeoKang 환경에는 별도 테스트/개발/로컬 DB가 없으므로 모든 DB 연결 target을 production으로 간주한다.
-- repository/query/SQL/migration 코드는 작성할 수 있지만 local test, CI, runtime verification에서 실제 DB에 실행하지 않는다.
+- `sk db local` managed container 증거가 없는 모든 DB target은 production 또는 미검증 target으로 간주한다.
+- repository/query/SQL/migration 코드는 작성할 수 있다. CI, startup, deploy에서는 DB에 실행하지 않는다.
 - DB 영향 검증은 compile/typecheck, mock 단위 테스트, SQL 정적 lint/comment 검토로 제한한다.
+- 개발자가 명시적으로 준비한 managed local DB에서는 sanitized snapshot 또는 위험 고지 후 승인된 OWNER 동일-workspace plain snapshot을 복원하고 repo migration SQL을 `sk db local apply`로 검증할 수 있다. 임의 Testcontainers/host/container는 사용하지 않는다.
 - local compile/test/build 전에는 `sk guard db-execution`을 통과하고, CI에서도 test/build보다 먼저 같은 검사를 실행한다.
 - Flyway/Liquibase, ORM schema sync, seed/backfill, startup migration을 실행하지 않는다.
 - 실제 schema/data 변경은 `$sk-db` 산출물을 OWNER 사용자가 별도 IDE/DB 도구에서 수동 실행한다.

package/docs/policies/core-safety.md

@@ -29,13 +29,14 @@
 - 직접 허용 범위는 read-only 증거 확보 목적의 `SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`으로 한정한다.
 - 직접 조회 전 필수 조건:
   - read-only 권한 또는 동등한 안전장치 확인
-  - SeoKang 환경에는 별도 로컬/개발/테스트 DB가 없으므로 연결 대상을 production으로 간주
+  - `sk db local` managed container 증거가 없으면 연결 대상을 production으로 간주
   - `LIMIT`, 선택적 `WHERE`, timeout 우선
   - 민감정보 최소 조회, 필요 시 마스킹/샘플링
 - 금지 범위:
   - `INSERT`, `UPDATE`, `DELETE`, `ALTER`, `CREATE`, `DROP`, `TRUNCATE`
   - `FOR UPDATE`, `LOCK`, transaction control, multi-statement, write-capable procedure/function 호출
 - 조건을 만족하지 못하면 직접 조회를 중단하고 사용자 실행 경로로 전환한다.
+- 예외적으로 production-derived local snapshot 요청은 제8절의 `sk db local copy-production` 전용 경로를 사용한다. 이 경로도 SELECT-only credential만 허용하며 production mutation 권한을 만들지 않는다.
 
 ## 3. DB Connection Profile Convention
 
@@ -81,10 +82,15 @@
 
 - DB 관련 코드, repository/query, SQL, migration, DDL/DML, verification, rollback 파일은 OWNER/NON_OWNER/UNKNOWN 구분 없이 작성·검토·commit·개인 fork PR까지 진행할 수 있다.
 - DB 영향 구현을 시작하기 위한 GitHub identity/cache/actor gate는 사용하지 않는다. `sk guard implementation --db-impact`는 이전 설치 호환용 안내 명령일 뿐 권한 판정이 아니다.
-- SeoKang 환경에는 테스트/개발/로컬 DB가 따로 없고, 연결 가능한 모든 DB는 production으로 간주한다.
+- 임의 host/container/Testcontainers는 production 또는 미검증 target으로 간주한다. Local write 예외는 `sk db local`이 생성하고 local Docker context, managed label, workspace/policy hash, image, `_local` DB명, loopback port를 모두 확인한 container 하나뿐이다.
 - Codex, 로컬 테스트, CI, deploy, start/restart script는 schema/data 변경을 절대 실행하지 않는다.
 - 금지되는 자동 실행에는 migration CLI, seed/backfill, SQL client write 실행, Flyway/Liquibase startup migration, Hibernate DDL create/update, ORM synchronize가 포함된다.
-- DB 영향 코드 검증은 DB 연결 없이 compile/typecheck, mock 단위 테스트, SQL 정적 lint/comment 검토로 제한한다. Testcontainers나 임시 DB를 새로 가정하지 않는다.
+- 기본 DB 영향 코드 검증은 DB 연결 없이 compile/typecheck, mock 단위 테스트, SQL 정적 lint/comment 검토로 제한한다. 일반 Testcontainers나 임의 Docker DB를 새로 가정하지 않는다.
+- 개발자가 명시적으로 `sk db local setup/restore/apply/reset`를 호출한 경우에만 managed local DB를 생성·복원·초기화하거나 repo SQL을 적용할 수 있다. `reset`은 `--replace`와 exact identity 검증을 요구하며, state가 없는 기존 object를 자동 삭제하지 않는다. 이 경로는 CI/test lifecycle/application startup/deploy에 연결하지 않는다.
+- Production-derived test data는 OWNER의 SELECT-only login-path로 dump를 스트리밍해 network/port/persistent volume이 없는 tmpfs sanitizer에서 마스킹·검증한다. Raw dump는 파일로 저장하지 않고, sanitizer는 성공/실패/중단 뒤 제거하며, 정수 `0` verification과 checksum manifest를 통과한 sanitized snapshot만 다른 개발자에게 전달한다. Restore도 current mask/verification을 tmpfs에서 다시 통과한 후 persistent local volume으로 전송한다.
+- 다른 개발자는 production credential을 받지 않는다. Snapshot과 manifest는 Git 밖의 승인된 비공개 경로로 전달한다.
+- 사용자가 raw production data의 로컬 영구 저장 위험을 고지받은 뒤 명시적으로 승인한 OWNER PC에는 sanitized 기본 policy의 `plainSnapshot.enabled=true` opt-in을 허용한다. 생성·복원 모두 GitHub numeric-ID OWNER 확인과 `--allow-raw-production-data`가 필요하며, manifest는 `sanitized:false`, `containsProductionData:true`, `shareable:false`를 기록한다.
+- Plain snapshot은 workspace 전용 `0700` 경로의 `0600` 파일로만 만들고 생성한 동일 workspace에서만 복원한다. Git, Notion, 자동 탐색, 다른 개발자 전달은 금지하며 일반 `$sk-local-db`의 기본 동작과 공유용 snapshot은 계속 sanitized 흐름을 사용한다.
 - local test와 test를 포함할 수 있는 일반 build 전, 그리고 CI workflow의 첫 검증 단계에서 strict `sk guard db-execution`을 통과해야 한다. CI에 이 단계가 없거나 DB credential marker가 있으면 실행하지 않는다.
 - `$sk-deploy`의 고정 no-test packaging은 deploy helper가 `check_db_execution_boundary.mjs --mode deploy-packaging`으로 검사한다. 이 모드에서는 DB 연결 test source의 존재만 허용하되 packaging/lifecycle이 test를 실행하거나 migration/DDL/DML/startup schema mutation 경로가 있으면 hard-fail한다.
 - fork PR workflow에는 production DB connection string, SSH/npm/API/CDN credential, write token, Actions secrets/variables를 전달하지 않는다.

package/docs/setup/README.md

@@ -7,6 +7,8 @@
 
 ## 포함 문서
 
+- `local-db-onboarding.md`
+  - Mac/Windows 공용 local DB, production-derived sanitized snapshot, 신규 개발자 온보딩 순서
 - `sk-cli-guide.md`
   - `sk setup`, `sk sync-agents`, `sk init`, `sk check`, `sk status` 사용 흐름
 - `fork-contributor-guide.md`

package/docs/setup/fork-contributor-guide.md

@@ -97,7 +97,7 @@ $sk-bugfix 문제가 발생한 부분을 고쳐줘
 $sk-git
 ```
 
-DB 관련 코드, repository/query, SQL, migration, verification, rollback 파일까지 작성해 PR로 전달할 수 있다. 단 모든 DB target은 production이므로 Codex/local test/CI에서 실행하지 않는다.
+DB 관련 코드, repository/query, SQL, migration, verification, rollback 파일까지 작성해 PR로 전달할 수 있다. 임의 DB target은 production 또는 미검증 target이므로 CI/startup/deploy에서 실행하지 않는다. Local 검증은 OWNER가 전달한 sanitized snapshot을 복원한 `sk db local` managed container에서만 수행하며 production credential은 받지 않는다.
 `$sk-deploy`는 사용자 유형을 판정하지 않는다. 친구 PC의 local config에 SSH/npm/배포 credential이 없으므로 실제 mutation은 원격 시스템에서 거부되며, 필요한 배포는 credential이 설정된 환경에서 실행한다.
 
 `$sk-git`은 아래를 확인해야 한다.

package/docs/setup/local-db-onboarding.md

@@ -0,0 +1,210 @@
+# Local DB Onboarding (Mac + Windows Git Bash)
+
+## 목적
+
+- 개발자는 production DB에 연결하지 않고 프로젝트별 Docker local DB에서 실행·검증한다.
+- 테스트 데이터는 OWNER가 production을 read-only로 복제한 뒤 마스킹·검증한 snapshot으로 공급한다.
+- production credential과 raw production data는 다른 개발자에게 전달하지 않는다.
+- production migration은 계속 OWNER가 별도 DB 도구에서 수동 실행한다.
+
+## 사용자 기본 사용법
+
+사용자 인터페이스는 `$sk-local-db`다. 사용자는 터미널 명령을 복사하지 않고 Codex에 결과만 요청한다.
+
+- `$sk-local-db 친구 컴퓨터 로컬 DB 처음 셋업해줘`
+- `$sk-local-db 최신 sanitized snapshot 발급해줘`
+- `$sk-local-db 전달받은 snapshot으로 업데이트해줘`
+- `$sk-local-db V1_81을 로컬 DB에만 적용하고 앱 확인해줘`
+- `$sk-local-db 지금 로컬 DB 상태 확인해줘`
+
+스킬이 OS/runtime/policy/snapshot/manifest/app.env를 확인하고 아래 CLI를 내부적으로 실행한다. 이후의 CLI 예시는 구현·장애 진단 reference이며, 사용자가 직접 터미널에 입력하는 기본 절차가 아니다.
+
+Plain `$sk-local-db`의 기본 동작은 다음과 같다.
+
+- Managed local DB가 없으면 runtime 확인부터 setup과 가능한 snapshot restore까지 수행한다.
+- 이미 있으면 OWNER PC에서는 SELECT-only production copy를 새로 마스킹·검증해 local DB를 교체한다.
+- Production source가 없는 개발자 PC에서는 전달된 최신 snapshot과 manifest를 찾아 검증·복원한다.
+- Snapshot을 찾을 수 없을 때는 터미널 명령이 아니라 파일 첨부 또는 비공개 전달 위치만 요청한다.
+
+Managed identity가 검증된 local DB는 production이 아니다. Codex는 개발 요청 범위에서 local schema/data의 조회와 `INSERT`, `UPDATE`, `DELETE`, DDL, fixture, local migration을 직접 실행할 수 있다. Local write는 production 반영 권한으로 이어지지 않는다.
+
+## 구조
+
+```text
+production DB (read-only login-path)
+  -> port/volume 없는 tmpfs sanitizer
+  -> project mask SQL
+  -> verification SQL 결과 0
+  -> sanitized .sql.gz + checksum manifest
+  -> 개발자별 sk-managed Docker local DB (127.0.0.1 only)
+```
+
+Raw production dump는 파일로 저장하지 않는다. Sanitizer는 network, 외부 port, persistent volume 없이 실행하며 성공·실패 후 항상 삭제한다. Restore도 snapshot을 tmpfs sanitizer에서 마스킹·검증한 다음에만 개발자 volume으로 전송한다.
+
+### OWNER 전용 plain snapshot 예외
+
+사용자가 로그인 ID, password hash, session/token, 고객 개인정보와 자유입력 원문이 로컬 파일과 DB에 영구 저장되는 위험을 고지받고 명시 승인한 경우에만 `plainSnapshot.enabled=true` policy와 명시 flag로 plain snapshot을 선택할 수 있다. 이 모드는 공유용 sanitized snapshot을 대체하지 않는다.
+
+- 생성·복원 모두 GitHub numeric-ID OWNER와 `--allow-raw-production-data`를 요구한다.
+- manifest는 `sanitized:false`, `containsProductionData:true`, `shareable:false`, 생성 workspace hash를 기록한다.
+- snapshot은 workspace 전용 `0700` 디렉터리의 `0600` 파일로만 생성하며 동일 workspace에서만 복원한다.
+- Git, Notion, 자동 snapshot 탐색, 다른 개발자 전달을 금지한다.
+- 논리 dump는 table schema와 row를 보존하지만 DB user/grant, trigger, routine, event는 포함하지 않는다.
+
+## 프로젝트 관리자가 최초 1회 준비할 것
+
+Sanitized snapshot을 지원하는 각 DB 프로젝트는 아래 3개 파일을 versioned source로 관리한다. Plain opt-in을 함께 지원해도 이 기본 3파일은 유지한다.
+
+1. `db/local/local-db-policy.json`
+2. `db/local/mask-production-copy.sql`
+3. `db/local/verify-production-copy.sql`
+
+정책 예시(`slk-api`, 2026-08-29 production read-only 확인 기준):
+
+```json
+{
+  "schemaVersion": 1,
+  "project": "slk-api",
+  "containerImage": "mariadb:10.11.11",
+  "localDatabase": "selink_local",
+  "localPort": 3308,
+  "appUser": "slk_local",
+  "jdbcScheme": "mariadb",
+  "clientBinary": "mariadb",
+  "dumpBinary": "mariadb-dump",
+  "snapshotMode": "sanitized",
+  "plainSnapshot": {
+    "enabled": true
+  },
+  "sanitizerTmpfsSize": "2g",
+  "source": {
+    "database": "selink",
+    "loginPath": "codex-db-slk-server",
+    "engineVersionPrefix": "10.11.11-MariaDB",
+    "clientBinary": "mysql",
+    "dumpBinary": "mysqldump"
+  },
+  "masking": {
+    "sql": "db/local/mask-production-copy.sql",
+    "verificationSql": "db/local/verify-production-copy.sql"
+  }
+}
+```
+
+OWNER 전용 plain 모드는 sanitized 기본 policy에 `plainSnapshot.enabled=true`를 추가한다. `--allow-raw-production-data`가 있는 생성·복원만 plain으로 선택하며, flag가 없으면 기존 sanitized 경로를 사용한다. Plain mode는 위험 고지 후 명시 승인된 현재 workspace에서만 사용한다.
+
+정책에는 host, port, username, password를 넣지 않는다. Production source 연결은 OWNER PC의 read-only MySQL login-path만 사용한다. `localDatabase`는 production 오인 방지를 위해 `_local`로 끝나야 한다.
+
+### 마스킹 SQL 계약
+
+- 실제 프로젝트 schema를 기준으로 결정적 가명값을 만든다. 같은 고객을 여러 테이블에서 참조하면 동일한 가명 key를 사용해 join/unique/FK 동작을 보존한다.
+- Snapshot restore 시 현재 mask SQL을 tmpfs에서 한 번 더 적용하므로, 가명화된 값에 다시 실행해도 결과가 바뀌지 않는 idempotent SQL로 작성한다.
+- password/token/session/요청 IP, 이름·전화번호·주소, 상담 자유입력, 문의 본문, 메모, 첨부 파일명·storage key처럼 개인·민감정보가 될 수 있는 필드를 제거하거나 가명화한다.
+- `CREATE USER`, `GRANT`, `INTO OUTFILE`, `LOAD DATA`, `DROP DATABASE`처럼 local data masking 범위를 벗어난 명령은 넣지 않는다.
+- `slk-api`의 현재 metadata 기준 우선 검토 대상에는 `auth_user`, `office_customer`, `office_order_history`, `office_expo_contract_record`, `office_customer_inquiry*`, `office_session`, `frame_session`, `office_vendor_contact`, attachment/history 계열이 포함된다. 이 목록만으로 충분하다고 간주하지 말고 schema 변경 때 다시 감사한다.
+
+### 검증 SQL 계약
+
+- read-only `SELECT`만 사용한다.
+- 민감 원문 잔존 건수와 정책 위반 건수를 합산해 **정수 `0` 하나만** 출력한다.
+- 결과가 비어 있거나 여러 값이 나오거나 `0`이 아니면 snapshot 생성은 실패한다.
+
+## OWNER: sanitized snapshot 만들기(Codex 내부 reference)
+
+사전 조건:
+
+- 프로젝트 main이 최신 상태다.
+- Docker Desktop이 실행 중이다.
+- `mysql`/`mysqldump`와 production read-only login-path가 준비돼 있다.
+- Docker context가 local `unix://` 또는 Windows `npipe://`다. SSH/TCP remote context는 차단된다.
+- 전체 dump는 production I/O가 있으므로 저부하 시간대에 실행한다. `--single-transaction` 일관성은 transactional table에 한정된다.
+
+```bash
+sk db local copy-production \
+  --output /private/team-share/slk-api-local-20260829.sql.gz
+```
+
+생성 결과는 `.sql.gz`와 같은 이름의 `.manifest.json` 두 파일이다. 둘을 함께 승인된 비공개 전달 경로로 공유한다. Git, PR, 공개 링크에는 올리지 않는다. 친구에게 production DB login-path나 credential은 전달하지 않는다.
+
+## 신규 개발자 온보딩 순서(Codex 내부 reference)
+
+### 1. 공용 도구 설치
+
+Mac은 Docker Desktop과 Node.js 20 이상, Windows는 Docker Desktop과 Git Bash 및 Node.js 20 이상을 준비한다. Windows 명령은 PowerShell이 아니라 Git Bash를 공통 기준으로 한다.
+
+```bash
+npm install -g seokang-sk
+sk setup
+sk check
+```
+
+### 2. 제품 저장소를 최신 main으로 준비
+
+```bash
+cd /path/to/slk-api
+sk init
+```
+
+친구는 `$sk-git` 흐름으로 `upstream/main`을 `--ff-only` 동기화한다. Local DB policy나 최신 migration이 없으면 DB 작업을 시작하지 말고 먼저 main 동기화를 해결한다.
+
+### 3. 개발자별 local DB 생성
+
+```bash
+sk db local setup
+sk db local status
+```
+
+실행 상태와 앱 연결값 파일 위치가 출력된다. 실제 password는 채팅이나 Git에 복사하지 않고 출력된 user-local `app.env`에서만 읽는다.
+
+### 4. OWNER가 전달한 snapshot 복원
+
+```bash
+sk db local restore \
+  --snapshot /private/team-share/slk-api-local-20260829.sql.gz \
+  --replace
+```
+
+`--replace`는 현재 프로젝트의 label·workspace·policy hash·image·loopback binding이 모두 일치하는 managed local DB만 교체한다. Snapshot checksum, `sanitized:true`, 현재 policy hash가 하나라도 다르면 중단한다.
+
+### 5. 애플리케이션 local profile 연결
+
+`sk db local setup/status`가 알려준 `app.env`의 `DB_URL`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USERNAME`, `DB_PASSWORD`를 IDE의 local run configuration에 연결한다. 기존 managed DB를 재사용하는 `setup`도 이 계약으로 `app.env`를 다시 쓴다. Versioned `application*.properties`에 실제 credential을 쓰거나 production URL fallback을 추가하지 않는다.
+
+### 6. 새 migration을 local에 적용
+
+Production에는 적용하지 않은 다음 migration을 개발 중이면 프로젝트 내부 SQL 파일만 명시적으로 local DB에 적용한다.
+
+```bash
+sk db local apply --file db/schema/V1_81__example.sql
+```
+
+이 명령은 `sk` label, workspace hash, policy hash, image, `_local` DB명, loopback port를 검증한 container에만 실행된다. CI, application startup, deploy에서는 호출하지 않는다. Production 반영은 `$sk-db`가 만든 migration/verification/rollback 세트를 OWNER가 별도 DB 도구에서 수동 실행한다.
+
+### 7. 앱 실행과 확인
+
+```bash
+sk db local status
+```
+
+- 앱이 `127.0.0.1:<policy port>/<database>_local`에 연결되는지 확인한다.
+- 최신 migration이 필요한 기능은 local apply 후 재검증한다.
+- 작업 종료 시 DB를 보존하려면 그대로 두고, container만 멈추려면 `sk db local stop`을 사용한다.
+
+## 다음 프로젝트 추가 순서
+
+새 DB 프로젝트를 추가할 때는 CLI 코드를 복사하지 않는다.
+
+1. Production engine/version과 source schema를 read-only로 확인한다.
+2. 프로젝트에 `db/local/local-db-policy.json`을 추가한다.
+3. Schema 전체를 감사해 project-specific mask SQL과 verification SQL을 작성한다.
+4. OWNER가 `copy-production`을 1회 실행하고 manifest/checksum을 확인한다.
+5. 별도 개발자 PC에서 `setup → restore → app local profile → status`를 끝까지 검증한다.
+6. Schema/PII 컬럼이 바뀌면 mask/verification policy를 같은 PR에서 갱신한다. Policy hash가 바뀌므로 이전 snapshot은 자동 거부되고 각 개발자는 `reset --replace` 후 새 snapshot을 restore해야 한다.
+
+## 실패/복구
+
+- `policy hash mismatch`: 최신 main을 pull하고 OWNER가 새 snapshot을 만든 뒤, 개발자는 `sk db local reset --replace`로 기존 managed local volume을 명시적으로 초기화하고 새 snapshot을 restore한다.
+- `SELECT-only credential 증명 실패`: production copy를 중단하고 read-only login-path 권한을 수정한다.
+- `verification != 0`: 마스킹 SQL/검증 SQL을 고치기 전에는 snapshot을 공유하지 않는다.
+- `remote Docker context`: local Docker Desktop context로 전환한다.
+- local migration 실패: production에는 영향이 없다. 검증된 snapshot을 `restore --replace`로 다시 복원한다.

package/docs/setup/sk-cli-guide.md

@@ -274,7 +274,19 @@ schema/migration/DML/repository/ORM/query/transaction/persistence 코드와 SQL
 sk guard implementation --db-impact
 ```
 
-별도 테스트/개발/로컬 DB는 없으며 모든 DB target은 production으로 간주한다. Codex, local test, CI, deploy, start/restart script는 migration/DDL/DML/backfill/seed를 실행하지 않는다. 검증은 compile/typecheck, mock 단위 테스트, SQL 정적 검사로 제한하고 실제 반영은 OWNER 사용자가 IDE/DB 도구에서 수동 실행한다.
+`sk db local` managed container 증거가 없는 DB target은 production 또는 미검증 target으로 간주한다. CI, deploy, start/restart script는 migration/DDL/DML/backfill/seed를 실행하지 않는다. Production 반영은 OWNER 사용자가 IDE/DB 도구에서 수동 실행한다.
+
+개발자별 DB는 Mac/Windows Git Bash 공통 Docker 흐름으로 준비한다.
+
+```bash
+sk db local setup
+sk db local restore --snapshot /private/path/project-local.sql.gz --replace
+sk db local status
+sk db local apply --file db/schema/V1_81__example.sql
+sk db local reset --replace
+```
+
+`reset --replace`는 policy/mask/verification 변경 후 기존 managed local volume을 명시적으로 삭제하고 새 계약으로 재생성한다. OWNER의 production data copy, project policy, masking/verification, 신규 개발자 전체 순서는 [Local DB Onboarding](local-db-onboarding.md)을 따른다. 친구에게 production DB credential을 전달하지 않고 sanitized snapshot과 checksum manifest만 비공개 경로로 공유한다.
 
 local test/build 전과 CI의 첫 검증 단계에는 아래 명령을 둔다. 이 검사는 DB 연결 test, Testcontainers, migration CLI, startup schema sync, CI DB credential을 탐지하면 종료 코드 `2`로 중단한다.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seokang-sk",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "SeoKang Codex 공용 설정과 스킬을 설치하는 CLI",
   "license": "MIT",
   "homepage": "https://github.com/selink-lab/seokang-codex-setting",
@@ -22,7 +22,7 @@
     "sk": "scripts/sk.mjs"
   },
   "scripts": {
-    "check:harness": "npm run check:harness:defaults -- . && npm run check:harness:ddl-comments -- . && npm run check:harness:docs -- . && npm run check:harness:style && npm run check:harness:models && npm run check:harness:ui-router && npm run check:harness:automation && npm run check:harness:db-execution && npm run check:harness:operator-guard && npm run check:harness:deploy-guard && npm run check:harness:fork-workflow && npm run check:harness:work-start && npm run check:harness:git-stage && npm run check:harness:git-secrets && npm run check:harness:npm-release && npm run check:harness:cli-smoke",
+    "check:harness": "npm run check:harness:defaults -- . && npm run check:harness:ddl-comments -- . && npm run check:harness:docs -- . && npm run check:harness:style && npm run check:harness:models && npm run check:harness:ui-router && npm run check:harness:automation && npm run check:harness:db-execution && npm run check:harness:local-db && npm run check:harness:local-db-skill && npm run check:harness:operator-guard && npm run check:harness:deploy-guard && npm run check:harness:fork-workflow && npm run check:harness:work-start && npm run check:harness:git-stage && npm run check:harness:git-secrets && npm run check:harness:npm-release && npm run check:harness:cli-smoke",
     "check:harness:defaults": "node scripts/check_no_unauthorized_defaults.mjs",
     "check:harness:ddl-comments": "node scripts/check_ddl_comments.mjs",
     "check:harness:docs": "node scripts/check_docs_integrity.mjs",
@@ -31,6 +31,8 @@
     "check:harness:ui-router": "node scripts/check_ui_runtime_router.mjs",
     "check:harness:automation": "node scripts/check_automation_safety.mjs",
     "check:harness:db-execution": "node scripts/check_db_execution_boundary_smoke.mjs",
+    "check:harness:local-db": "node scripts/check_local_db_workflow.mjs",
+    "check:harness:local-db-skill": "node scripts/check_local_db_skill.mjs",
     "check:harness:operator-guard": "node scripts/check_operator_guard.mjs",
     "check:harness:deploy-guard": "node scripts/check_deploy_actor_guard.mjs",
     "check:harness:fork-workflow": "node scripts/check_fork_contribution.mjs",

package/scripts/check_automation_safety.mjs

@@ -94,6 +94,8 @@ const STATIC_CHECKS = [
       'MAIN_SHA_CHANGED',
       'POST_MERGE_STATE_UNVERIFIED',
       'POST_MERGE_MAIN_UNCHANGED',
+      'inspectPullRequestStable',
+      'SK_PR_MERGE_RETRY_DELAYS_MS',
       'mergeStateStatus',
       'requiresUpToDateBranch',
       "ghJson(['api', 'user'",
@@ -110,7 +112,10 @@ const STATIC_CHECKS = [
       'STRICT_BASE_NOT_ENFORCED',
       'TRUSTED_CHECK_NOT_REQUIRED',
       'ADMIN_BYPASS_NOT_BLOCKED',
-      'MERGE_STATE_NOT_CLEAN',
+      'classifyMergeReadiness',
+      'MERGEABILITY_CALCULATION_PENDING',
+      'PR_CONFLICT_RESOLUTION_REQUIRED',
+      'PR_BASE_UPDATE_REQUIRED',
       'PR_NOT_OPEN',
       'HEAD_REPOSITORY_NOT_ALLOWED',
       'MAIN_SHA_MISSING',

package/scripts/check_db_execution_boundary.mjs

@@ -9,6 +9,8 @@ const EXEMPT_HARNESS_FILES = new Set([
   path.join(SCRIPT_DIR, 'check_db_execution_boundary.mjs'),
   path.join(SCRIPT_DIR, 'check_db_execution_boundary_smoke.mjs'),
   path.join(SCRIPT_DIR, 'check_deploy_actor_guard.mjs'),
+  // Exact canonical runtime exception: this file can mutate only a label-verified local Docker DB.
+  path.join(SCRIPT_DIR, 'local_db.mjs'),
 ]);
 
 const SKIP_DIRS = new Set([

package/scripts/check_docs_integrity.mjs

@@ -40,8 +40,8 @@ const REQUIRED_POLICY_FILES = [
         fragments: ['Runtime Delegation', '명시적 위임 지시', '사용자의 별도 요청을 기다리지 않는다', '반드시 실제 위임한다', '둘 이상의 레이어', '병렬 write 충돌', '작업 이력의 provenance'],
       },
       {
-        label: 'production-only DB execution policy',
-        fragments: ['DB Authoring / Production Execution Boundary', 'sk guard implementation --db-impact', '연결 가능한 모든 DB는 production', 'Codex, 로컬 테스트, CI, deploy, start/restart script', 'scripts/check_db_execution_boundary.mjs', 'Testcontainers', 'OWNER 사용자가'],
+        label: 'production and managed-local DB execution policy',
+        fragments: ['DB Authoring / Production Execution Boundary', 'sk guard implementation --db-impact', '`sk db local`이 생성', 'tmpfs sanitizer', 'sanitized snapshot', 'Codex, 로컬 테스트, CI, deploy, start/restart script', 'scripts/check_db_execution_boundary.mjs', 'Testcontainers', 'OWNER 사용자가'],
       },
       {
         label: 'git deploy capability policy',
@@ -75,7 +75,7 @@ const REQUIRED_POLICY_FILES = [
       },
       {
         label: 'feature DB execution boundary',
-        fragments: ['DB Authoring / Execution Boundary', 'GitHub actor 상태와 무관', '모든 DB target은 production', 'compile/typecheck', 'OWNER 사용자가'],
+        fragments: ['DB Authoring / Execution Boundary', 'GitHub actor 상태와 무관', '`sk db local` managed container', 'compile/typecheck', 'OWNER 사용자가'],
       },
       {
         label: 'feature npm publish decision check',
@@ -92,7 +92,7 @@ const REQUIRED_POLICY_FILES = [
     checks: [
       {
         label: 'bugfix DB execution boundary',
-        fragments: ['DB Authoring / Execution Boundary', 'GitHub actor 상태와 무관', '모든 DB target은 production', 'mock 단위 테스트', '수동 실행'],
+        fragments: ['DB Authoring / Execution Boundary', 'GitHub actor 상태와 무관', '`sk db local` managed container', 'sanitized snapshot', '수동 실행'],
       },
     ],
   },
@@ -103,6 +103,10 @@ const REQUIRED_POLICY_FILES = [
         label: 'db migration execution boundary',
         fragments: ['Mode: Migration', 'GitHub identity/cache/OWNER 판정 없이', 'local test, CI, deploy/startup script', 'SQL 정적 lint/comment', '수동 실행용'],
       },
+      {
+        label: 'db local snapshot boundary',
+        fragments: ['Mode: Local DB', 'tmpfs sanitizer', '정수 `0`', 'sk db local apply', 'production credential'],
+      },
     ],
   },
   {
@@ -114,6 +118,15 @@ const REQUIRED_POLICY_FILES = [
       },
     ],
   },
+  {
+    relativePath: path.join('docs', 'setup', 'local-db-onboarding.md'),
+    checks: [
+      {
+        label: 'local DB onboarding sequence',
+        fragments: ['Mac + Windows Git Bash', 'tmpfs sanitizer', 'local-db-policy.json', 'sk db local setup', 'sk db local restore', 'sk db local apply', 'production credential', '다음 프로젝트 추가 순서'],
+      },
+    ],
+  },
   {
     relativePath: path.join('skills', 'sk-git', 'SKILL.md'),
     checks: [
@@ -139,7 +152,7 @@ const REQUIRED_POLICY_FILES = [
       },
       {
         label: 'git owner merge and contributor sync',
-        fragments: ['Executable Git Workflow Preflight Receipt', 'sk git preflight', 'receipt', 'NON_OWNER Upstream Sync', 'git_fork_sync.mjs', 'OWNER Current-Repository PR Merge', 'git_pr_merge.mjs', 'plain `$sk-git`', '--match-head-commit'],
+        fragments: ['Executable Git Workflow Preflight Receipt', 'sk git preflight', 'receipt', 'NON_OWNER Upstream Sync', 'git_fork_sync.mjs', 'OWNER Current-Repository PR Merge', 'git_pr_merge.mjs', 'plain `$sk-git`', '--match-head-commit', 'MERGEABILITY_CALCULATION_PENDING', 'resolution-required', 'local-sync-pending'],
       },
       {
         label: 'git secret hard-fail',
@@ -152,7 +165,7 @@ const REQUIRED_POLICY_FILES = [
     checks: [
       {
         label: 'deploy DB execution boundary',
-        fragments: ['DB Execution Boundary', '테스트/개발/로컬 DB가 따로 없고', 'scripts/check_db_execution_boundary.mjs', 'start/restart script', '별도 IDE/DB 도구에서 수동 실행'],
+        fragments: ['DB Execution Boundary', '`sk db local` managed container', 'scripts/check_db_execution_boundary.mjs', 'start/restart script', '별도 IDE/DB 도구에서 수동 실행'],
       },
       {
         label: 'deploy npm publish decision gate',

package/scripts/check_fork_contribution.mjs

@@ -121,7 +121,9 @@ requireFragments('friend guide', guide, [
   '$sk-git',
   'gh pr create',
   'DB 관련 코드',
-  '모든 DB target은 production',
+  'sanitized snapshot',
+  '`sk db local` managed container',
+  'production credential은 받지 않는다',
   '사용자 유형을 판정하지 않는다',
   '접근 없음',
   'Read 전용',

package/scripts/check_git_pr_merge.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import assert from 'node:assert/strict';
-import { classifyRisk, detectStateChanges, evaluateChecks, evaluatePullRequest } from './git_pr_merge_core.mjs';
+import { classifyMergeReadiness, classifyRisk, detectStateChanges, evaluateChecks, evaluatePullRequest } from './git_pr_merge_core.mjs';
 
 const policy = { allowedAuthors: ['91kwangmin'], requiredCheckNames: ['pr-safe'], trustedRepository: 'selink-lab/slk-api' };
 const repositoryState = {
@@ -92,7 +92,26 @@ assert.equal(evaluatePullRequest(pr({ state: 'MERGED', mergedAt: '2026-08-29T00:
 assert.equal(evaluatePullRequest(pr({ headRepositoryOwner: { login: 'outsider' } }), policy, repositoryState).eligible, false);
 assert.equal(evaluatePullRequest(pr({ isCrossRepository: false }), policy, repositoryState).eligible, false);
 assert.equal(evaluatePullRequest(pr({ statusCheckRollup: [] }), policy, repositoryState).eligible, false);
-assert.equal(evaluatePullRequest(pr({ mergeable: 'CONFLICTING' }), policy, repositoryState).eligible, false);
+assert.deepEqual(classifyMergeReadiness(pr()), {
+  status: 'ready', reason: null, mergeable: 'MERGEABLE', mergeStateStatus: 'CLEAN',
+});
+assert.equal(classifyMergeReadiness(pr({ mergeable: 'UNKNOWN', mergeStateStatus: 'UNKNOWN' })).status, 'pending');
+assert.equal(classifyMergeReadiness(pr({ mergeable: 'CONFLICTING', mergeStateStatus: 'DIRTY' })).status, 'resolution-required');
+assert.equal(classifyMergeReadiness(pr({ mergeable: 'MERGEABLE', mergeStateStatus: 'BEHIND' })).status, 'update-required');
+assert.equal(classifyMergeReadiness(pr({ mergeable: 'UNKNOWN', mergeStateStatus: 'BLOCKED' })).reason, 'MERGE_POLICY_BLOCKED');
+assert.equal(classifyMergeReadiness(pr({ mergeable: 'UNKNOWN', mergeStateStatus: 'UNSTABLE' })).reason, 'MERGE_CHECKS_UNSTABLE');
+assert.equal(classifyMergeReadiness(pr({ mergeable: 'CONFLICTING', mergeStateStatus: 'UNKNOWN' })).reason, 'PR_CONFLICT_RESOLUTION_REQUIRED');
+assert.equal(classifyMergeReadiness(pr({ mergeable: 'UNKNOWN', mergeStateStatus: 'DIRTY' })).reason, 'PR_CONFLICT_RESOLUTION_REQUIRED');
+assert.equal(classifyMergeReadiness(pr({ mergeable: 'UNKNOWN', mergeStateStatus: 'BEHIND' })).reason, 'PR_BASE_UPDATE_REQUIRED');
+assert.equal(classifyMergeReadiness(pr({ mergeable: 'MERGEABLE', mergeStateStatus: 'HAS_HOOKS' })).status, 'ready');
+assert.equal(classifyMergeReadiness(pr({ mergeStateStatus: 'BLOCKED' })).reason, 'MERGE_POLICY_BLOCKED');
+assert.equal(classifyMergeReadiness(pr({ mergeStateStatus: 'UNSTABLE' })).reason, 'MERGE_CHECKS_UNSTABLE');
+const pendingMergeability = evaluatePullRequest(pr({ mergeable: 'UNKNOWN', mergeStateStatus: 'UNKNOWN' }), policy, repositoryState);
+assert.ok(pendingMergeability.reasons.includes('MERGEABILITY_CALCULATION_PENDING'));
+assert.ok(!pendingMergeability.reasons.includes('NOT_MERGEABLE'));
+const conflicting = evaluatePullRequest(pr({ mergeable: 'CONFLICTING', mergeStateStatus: 'DIRTY' }), policy, repositoryState);
+assert.equal(conflicting.eligible, false);
+assert.ok(conflicting.reasons.includes('PR_CONFLICT_RESOLUTION_REQUIRED'));
 assert.equal(evaluatePullRequest(pr({ isDraft: true }), policy, repositoryState).eligible, false);
 assert.equal(evaluatePullRequest(pr({ reviewDecision: 'CHANGES_REQUESTED' }), policy, repositoryState).eligible, false);
 assert.equal(evaluatePullRequest(pr({ mergeStateStatus: 'BEHIND' }), policy, repositoryState).eligible, false);