기여 작업 흐름과 커밋 규칙

원칙

기여 작업은 Skill OS에서 시작한다. 저장소의 공식 규칙은 start.dartlabSkillOs를 통해 찾고, 변경 범위에 맞는 operation.* skill을 확인한 뒤 작업한다.

코드 변경은 기존 구조와 책임 경계를 우선한다. 새 abstraction은 중복이나 복잡도를 실제로 줄일 때만 추가하고, unrelated 정리 작업은 같은 변경에 섞지 않는다.

코드 규칙

• 식별자와 파일명은 기존 DartLab 규칙을 따른다. Python 함수·메서드·변수·파일명은 camelCase, 클래스는 PascalCase, 모듈 상수는 ALL_CAPS를 기본으로 한다.
• 공개 API, 대표 반환 형태, 오류·제한 동작은 Skill OS와 capability/docstring이 어긋나지 않게 유지한다.
• 계층 경계는 operation.architecture를 따른다. L2 엔진 간 직접 import, L1.5 sibling cross import, 표현/전송 helper의 비즈니스 로직 유입을 회귀로 본다.
• provider와 대용량 데이터 경로는 operation.code의 메모리-safe 룰을 따른다. eager cross-scan, full dataframe 기본 반환, baseline 증가를 새 코드에 만들지 않는다.

검증 규칙

• 테스트는 변경 범위에 맞게 좁게 시작하고, shared behavior나 계층 경계를 건드리면 architecture/audit gate까지 넓힌다.
• 긴 테스트나 pytest 직접 실행이 필요한 경우 scripts/dev/test-lock.sh를 우선 사용한다.
• Guard Index 관련 회귀 작업은 operation.testing, operation.code, operation.architecture의 절차를 함께 적용한다.
• 실패한 검증은 숨기지 않는다. 기존 실패인지, 이번 변경으로 생긴 실패인지 구분해 기록한다.

커밋 규칙

• 커밋은 한 논리 단위로 나눈다. 기능 변경과 생성 산출물 동기화가 분리 가능한 경우 별도 커밋으로 둔다.
• staging은 명시 경로만 사용한다. 예: git add README.md src/dartlab/skills/specs/operation/contributionWorkflow.md.
• 전체 staging 명령 (git add ., git add -A)은 사용하지 않는다.
• 커밋 메시지는 한국어로 작성하고, 변경 범주와 내용을 함께 담는다. 예: 문서: Skill OS 운영 안내 추가.
• 커밋 메시지와 공개 산출물에는 assistant identity, 모델명, vendor명, generated-by 표식을 남기지 않는다.
• push는 별도 요청이 있을 때만 수행한다.

공개 산출물 규칙

README, Skill OS, landing page, blog, JSON index는 사용자가 직접 읽는 공개 산출물이다. 표현은 주체 중립적으로 쓴다.

운영 실패나 폐기 이력은 필요한 경우에만 짧게 남긴다. 내부 사유, 방어적 문구, 도구 중심의 표현보다 현재 운영 원칙과 사용자가 따라야 할 절차를 먼저 적는다.