b3os-infra-safety git:20260723.55ddc12A

Immutable. This exact content is served forever at /api/v1/blob/f40dd8220bc5c4e6.

---
name: b3os-infra-safety
description: b3os 플랫폼 자체(설정·소스·registry·배포)를 수정할 때 지킬 안전 규칙. 팀원이 b3os 코드/config/agents.json/team.db/릴리스를 건드리는 작업을 할 때 필독. 브랜치·worktree 격리, 런타임 상태(agents.json·team.db) 보호, 백업, 테스트 FS 격리, 릴리스/배포 가드, 격리 검증. 일반 팀작업이 아니라 b3os 인프라를 고칠 때만 해당. owner=maintainer.
---

# b3os-infra-safety — b3os 인프라 작업 안전 규칙

> b3os **플랫폼 자체**(코드·config·registry·DB·릴리스 스크립트)를 고칠 때 지킨다. 일반 팀 협업·대화가 아니라 **b3os 인프라를 수정**하는 작업 전용. (팀 통신·오너판정·안전게이트 같은 상시 규칙은 TEAM-OS에 남아있다 — 여기는 "b3os를 고치는 법".)

## 언제 이 스킬을 보나

팀원이 b3os의 소스·설정·runtime 상태·릴리스를 건드릴 때: 코드 수정, config 변경, `agents.json`/`team.db` 조작, 테스트/빌드 실행, `make-public-release`/`deploy-public`, 서버 재시작. **이 작업 전에 이 규칙을 적용한다.**

## ① 브랜치·worktree 격리

- git-추적 파일 수정은 **task 브랜치/worktree에서만**. 공유 main 워킹트리에 직접 쓰지 않는다. 한 task = 한 브랜치.
- task 카드는 브랜치가 있으면 그 브랜치를 명시. 코드/문서 리뷰·핸드오프는 브랜치를 명시(없으면 리뷰어가 먼저 물어본다).
- 새/작은 프로젝트는 브랜치 전략 도입 전까지 main에서 작업 가능.

## ② 런타임 상태 보호 (★사고 재발방지 핵심★)

- **`agents.json`·`team.db` 같은 런타임 상태 파일을 worktree↔라이브 트리 사이에 심링크하지 않는다.** 각 worktree는 자기 **실파일**을 갖는다.
  - 이유: 심링크는 읽기·쓰기가 다 원본으로 통한다. worktree가 상태 파일에 쓰면 그 write가 **라이브 원본을 덮어써** 팀 전체를 날릴 수 있다(파일 write라 DB는 남아 "registry=[] · DB=정상"의 조용한 유실).
- 읽기 위주 파일(스킬 등)의 심링크는 안전하지만, **자주 쓰이는 상태 파일은 절대 심링크 금지.**
- 상태 파일에 **`>` 리다이렉트로 직접 쓰지 않는다.** 항상 임시파일 작성 → 검증 → 원자적 `mv`.

## ③ 백업 먼저

- registry(`agents.json`)/DB(`team.db`) 변경, `make-public-release`/`deploy`, 상태를 건드릴 수 있는 테스트 실행 **전에** `agents.json`+`team.db`를 타임스탬프 백업한다. 유실돼도 즉시 복구된다.

## ④ 테스트 FS 격리

- 테스트는 **실 파일시스템을 건드리지 않는다.** registry/DB/워크스페이스/토큰 파일은 `mktemp`/tmp로 격리하고, `TEAM_AGENT_REGISTRY` 등 registry 경로 env를 **tmp로 명시**한다.
- env 격리만으로 부족한 경우(심링크·경로 기본값이 라이브를 가리킴)를 조심한다 — 격리는 "env를 읽는 코드"만 보호한다.

## ⑤ 릴리스·배포 가드

- `make-public-release`/`deploy-public`의 출력(OUT)은 **항상 새 격리 dir**(예: `mktemp -d`)이며 **라이브 repo 루트가 아니어야** 한다.
- 배포 전: 관련 변경 커밋됨 · 테스트/타입체크/acceptance 통과 · 리뷰/게이트 완료 · 롤백/스냅샷 확보 · **시크릿 스크럽 스캔 통과** · 다른 멤버가 동시에 재시작/배포할 수 있으면 코디네이션 핑.

## ⑥ 오너 코디네이션

- 파일/영역당 오너 1명. 다른 오너의 영역을 건드리기 전에 먼저 조율. 공유 파일에 섞인 변경은 조용히 나누거나 덮지 말고 영역 오너가 해소·재리뷰.

## ⑦ 정리

- 브랜치 머지 후 worktree 제거. stale worktree 주기적 prune.

## 코드로 강제되는 것 (문서 규칙에만 안 맡긴다)

핵심 안전은 코드 가드가 강제한다(사람·모델이 규칙을 어겨도 라이브가 안 날아가게):
- registry writer가 **심링크로 트리 밖·라이브 registry에 쓰는 것 거부**(realpath 검사)
- 비어있지 않은 registry에 빈 `[]`를 덮을 때 **백업 + 명시 force 요구**
- 서버가 registry가 갑자기 0으로 떨어지면(DB엔 멤버 있는데) **자동복구**

문서 규칙(위)은 사람이 읽을 때의 보조, **코드 가드가 1차 방어선**이다.