v0.3.0 — 규칙의 우선순위와 사람 커밋 반영 도구

요약

실사용 첫날 드러난 문제를 고친 버전입니다. 첫 task 승인 뒤 세 문서(원칙, 일반 규칙, 세션 시작 절차)가 서로 다른 말을 해서, 에이전트가 판단으로 메워야 했다. 이번 버전은 규칙의 우선순위를 정하고, 기계적으로 할 수 있는 일은 도구로 옮겨, 에이전트가 문서와 도구만으로 같은 결과를 내게 한다. 연구 프로젝트(ssm-latent-reasoning)에 적용해 확인했다.

주요 내용

규칙의 층과 우선순위 (생성되는 AGENTS.md)

• 0절 우선순위: 규칙은 사람만 고친다(spec 커밋). 적용할 때는 구체적인 것이 먼저다: task 카드 "범위 › 포함" → 절차의 특별 규칙 → 일반 규칙. 불변 원칙(P1–P6)은 예외가 없다.
• 불변 원칙 P1–P6: 커밋이 사실의 원본이며 반영은 에이전트의 책임, 사람 신원으로 커밋하지 않기, 사람 전용 타입, 이력 재작성 금지, 사람의 변경 폐기 금지, 지어낸 판정·수치 금지.
• 일반 규칙 G1–G10: 괄호 예외를 모두 걷어 냈다.
• 절차의 특별 규칙: 각 절차 문서에 "특별 규칙" 절을 둔다. 판단이 필요한 세 곳에만 남았다: commit-prep(G2), gate-conversation(G5), gate-apply(G4).
• 근거: 모든 작업을 주체·도구·바꾸는 대상으로 정리한 docs/operations.md.

코드 우선: 새 도구 scripts/apply-human-commits

• 사람 커밋(plan의 Approve, gate, respond, decide)이 정한 상태 전이를 카드·다음 카드·마일스톤·결정·결정 목록에 반영하고, review를 닫고, 게이트 이력을 남긴다. 커밋은 에이전트가 하며 Applies: <해시>로 기록한다.
• 전이를 모두 계산한 뒤, 하나라도 할 수 없으면 아무것도 바꾸지 않는다. 이미 반영된 상태(v0.2 방식)는 건너뛰고 기록만 남긴다.
• 대화로 판정하든 문서로 판정하든 같은 반영 경로를 쓴다(gate-conversation은 상태를 직접 바꾸지 않는다).

scripts/session-check 확장

• 반영되지 않은 사람 커밋을 알린다. session-start는 카드 상태를 판단하기 전에 이를 처리한다(첫날 문제의 직접 수정).
• git commit -F로 이미 확정된 초안, 커밋된 반영 기록을 정리한다.
• 반영한 뒤 커밋 전에 세션이 끝난 경우를 알아보고, 그 변경을 사람의 변경으로 잘못 분류하지 않는다.

문서

• 명령 설명서 docs/cli/: lg init, lg commit, lg draft, 프로젝트 스크립트. 옵션·종료 코드·hook의 타입과 trailer 표가 코드와 같은지 테스트한다.
• 사용자 작업 설명서 docs/guide/: 설치, 하루 작업, task 승인, 게이트 판정, 에스컬레이션 응답, 직접 수정, 계획 변경, 실수 바로잡기, 업데이트. 사람에서 에이전트로 넘어가는 지점(H1–H7)을 정리했다.
• 설계 문서 v3.0 (§16 규칙의 층, §16.4 사양 버전 갱신, §17.2, §21).

호환성

• spec_version 3. lg commit·lg draft는 spec_version 2와 3을 모두 지원한다(커밋 규약이 같다).
• v0.2 프로젝트의 규칙 갱신은 수동이다(docs/guide/upgrade.md): 새 규칙·도구 파일 복사 + 모든 문서의 spec_version 일괄 갱신, 사람의 spec 커밋 하나. 연구 내용은 그대로다.
• commit-msg hook에 Applies trailer 검사가 추가됐다.
• 생성 파일 수: Claude Code를 쓰면 60 + 6N, 쓰지 않으면 52 + 6N.

실사용 확인 (ssm-latent-reasoning, spec_version 2 → 3)

• 갱신 뒤 세션 시작 hook이 반영되지 않은 승인 커밋 70ea21b를 알렸고, 에이전트가 판단 없이 gate-apply로 가서 도구가 "이미 반영됨"으로 건너뛰었다. Applies: 70ea21b만 남긴 빈 반영 커밋(285bfed)을 남기고 작업으로 돌아갔다.
• 여기서 나온 개선 두 가지를 같은 릴리즈에 넣었다: 빈 반영 커밋의 이유를 출력에 적기, 반영 기록 정리와 커밋 전 중단 감지.
• 연구 문서의 frontmatter spec_version 처리가 갱신 절차에 빠져 있던 것을 찾아, 일괄 갱신 규칙과 명령(검증함)을 넣었다.

테스트

• 341개 (0.2.1 대비 54개 추가).
• Python 3.10–3.14 × 최신·최소 의존성. 생성되는 hook과 스크립트는 Python 3.9로도 검사한다. 이 검사가 Path.write_text(newline=)가 3.9에 없는 문제를 잡았다.

설치·업데이트

pipx install --force git+https://github.com/qazcdesnu/labgate.git@v0.3.0
lg --version

v0.2 프로젝트의 규칙 갱신 방법은 docs/guide/upgrade.md에 있습니다.

변경 PR: #3 · 이전 릴리즈: v0.2.1