Releases: sol5288/commitgate
Release list
v0.29.1 — 0.29.0 문서 정합 + 구형 설치본 진단
Fixed
- 0.29.0 이 바꾼 규칙을 문서가 따라오지 못하던 것을 고쳤습니다 — 배포 뒤 문서를 전수 점검해 7군데를
정정·보완했습니다. 코드는 맞았고 설명이 틀렸습니다.- 🔴 가장 중요:
CHANGELOG조각 규약이 "REQ 는## Unreleased를 직접 고치지 않는다" 라고
무조건으로 적혀 있었습니다. 실제로는changelog.d/를 커밋한 프로젝트에서만 적용됩니다 —
규약을 쓰지 않는 독자에게는 "이 도구를 쓰면 내 CHANGELOG 를 못 고친다" 로 읽혔습니다. - 위임 원장을 아직 단일 파일로 설명하던 곳(설정 문서 한/영)을 샤드 경로 + legacy 읽기 전용
보존으로 고쳤습니다. - 병렬 REQ 운용 절차가 어디에도 없었습니다(0.29.0 의 핵심 기능인데 "가능해졌다"만 있고 방법이
없었습니다). 워크플로 문서 한/영에 절차 다섯 항목을 넣었습니다. - 보장 문서에 병렬의 한계(두 REQ 가 같은 파일을 고치면 합쳐진 결과를 아무도 검사하지 않는다)를
"보장하지 않는 것"으로 명시했습니다. - README 명령 표에
changelog collect가 빠져 있었고, 업그레이드 문서에0.28.x → 0.29.0절이
없었습니다(할 일이 없다는 사실도 안내입니다).
- 🔴 가장 중요:
Added
-
문서 축 가드(
docs-0290-axes) — 0.29 가 바꾼 규칙 7개를 각자의 정본 문서에 고정합니다.
한쪽 언어만 고쳐 다른 쪽이 거짓으로 남는 실수를 구조적으로 막습니다.확인할 파일:
docs/workflow.md·docs/guarantees.md·docs/upgrade.md·README.md(+ 영문)
Fixed
-
🔴 구형(vendored) 설치본이 옛 코드를 조용히 실행하던 것을 알려 줍니다 —
package.json의req:*가tsx scripts/req/*.ts형태이면 명령이 저장소에 복사된 사본을
실행합니다. 그런데 그 사본을 갱신하는 명령이 없고(sync --scripts는package.json의 누락 키만
넣습니다),req:doctor의 D19 는 두 형태가 섞였을 때만 알렸습니다. 결과적으로 패키지를 여러
릴리스 올려도 새 동작이 도달하지 않은 채 아무 신호가 없었습니다.- 이제 순수 Stage A 도 WARN 하고 전환 명령(
npx commitgate migrate --apply)을 함께 냅니다. ⚠️ 차단하지 않습니다. Stage A 는 결함이 아니라 지원되는 설치 형태입니다 — 바뀐 것은
"막지 않는다" 가 아니라 "말해 주지 않는다" 쪽입니다.- CommitGate 저장소 자신은 Stage A 형태이므로 개발 저장소에서는 이 경고가 나오지 않습니다.
- 이제 순수 Stage A 도 WARN 하고 전환 명령(
-
D-체크 정본 표가 "구현된 검사는 21개(D2~D27)"라고 적고 있었습니다 — 실제는 29개(D2~D35) 입니다.
D28~D35 를 추가한 8개 REQ 가 전부 이 문장을 지나쳤습니다. 표 자체는 맞았고 표를 설명하는 문장이
낡아 있었습니다.- 이제 이 수치를 등록부에서 파생해 대조합니다 — 문서와 코드 어느 쪽이 움직여도 검사가 실패합니다.
-
위 변경과 함께, "D19 는 mixed 만 WARN 한다" 는 폐기된 서술이 SSOT 7개 파일과 업그레이드 문서
한/영에 남아 있던 것을 전수로 걷어냈습니다. 같은 서술이 다시 들어오면 실패하는 가드를 넣었습니다.확인할 파일:
scripts/req/req-doctor.ts·docs/ssot-design/07-business-rules-and-state-machines.md
v0.29.0
v0.28.1 — 문서 정합 + 릴리스 절차 수정
0.28.0 을 배포하고 바로 점검해서 잡은 문서 결함입니다. 동작은 한 줄도 바뀌지 않았습니다.
무엇을 고쳤나
- README 양쪽이 아직
0.27.0을 설명하고 있었습니다. npm 페이지와 GitHub 첫 화면이 이전 판을
설명했고, 0.28.0 의 핵심(묶음 1회 정지)이 어디에도 없었습니다.
🔴 이것을 잡는 오라클이 이미 있었고,main은 red 인 채로 배포됐습니다. README.en.md용어표가 아직stopGate: merge전용이었습니다 — 0.28.0 이
"한쪽 언어만 고쳐서 다른 쪽이 거짓으로 남았다" 를 고치면서 같은 실수를 했습니다.0.27.x → 0.28.0업그레이드 절 신설(한글·영문).
🔴req:delegate --allow-push단독 위임이 이제 발급 시점에 거부됩니다 — 묶음과 무관한
전역 변경이라 별도 절로 적었습니다.--allow-bypass를 함께 주십시오.
근본 원인 — 릴리스 절차
필수 게이트는 bump 전에 돌리는데, 일부 오라클은 package.json 의 버전을 읽습니다.
bump 전에는 옛 버전 기준으로 통과하고, bump 후에는 아무도 다시 돌리지 않습니다 —
절차를 그대로 따라도 잡히지 않았습니다.
docs/RELEASING.md 의 bump 절에 bump 직후 npm test 재실행을 넣고, 왜 다시 도는지와
0.28.0 에서 실제로 그렇게 됐다는 사례를 함께 적었습니다. 순서가 뒤바뀌면 red 가 되도록 가드했습니다.
🔴 이번 릴리스는 그 새 절차로 진행했습니다 — bump 후 전체 스위트를 다시 돌려 green 을 확인했습니다.
업그레이드
0.28.0 에서 동작 변경은 없습니다. 문서만 바뀝니다.
npm i -D commitgate@0.28.1
npx commitgate sync --apply --scripts
npx commitgate quickstart --apply
npx commitgate check검증
로컬 게이트 전부 통과: typecheck · docs:lint · npm test(bump 전후 각 1회) · smoke ·
npm pack --dry-run · verify-range --strict(21커밋 · 미입증 0 · 손상 0).
🔴 GitHub CI 는 실행하지 않았습니다 — 이 프로젝트는 CI 를 배제했고 검증 축은 로컬 게이트입니다.
v0.28.0 — delivery 묶음 1회 정지 경로
여러 REQ를 하나로 묶어 main 병합 직전 한 번만 멈추는 경로를 실제로 통과할 수 있게 만든 판입니다.
그 경로는 0.27.1 에서 구조적으로 막혀 있었습니다 — 묶음을 만들 수는 있어도 main 에 올릴 수 없었습니다.
무엇이 달라지나
REQ N개짜리 요구사항을 stopGate: "auto" + delivery 묶음으로 진행할 때(전 member LOW 기준):
| 0.27.1 | 0.28.0 | |
|---|---|---|
| 사람이 멈추는 자리 | N회 (티켓마다 위임 발급) | 1회 (delivery approve 확인 하나) |
| 묶음 → main 경로 | 사용 불가 | 사용 가능 |
delivery approve 하나가 봉인·승인·통합 위임 발급을 함께 하고, 그 뒤 commitgate integrate 가
사람 확인 없이 병합합니다.
🔴 승인 증거가 사라지는 것이 아닙니다. 사람이 말한 확인 문구가 원장과 레코드에 남습니다.
줄어든 것은 같은 결정을 여러 번 확인받던 중복입니다.
🔴 auto 라도 위임 없이는 열리지 않습니다. 달라진 것은 사람이 req:delegate 를 따로 치지
않는다는 점뿐입니다.
주요 변경
- feat:
delivery/<slug>→ main 경로를 열었습니다 - fix:
delivery integrate의 병합 커밋이unproven으로 분류되던 것 — 병합과 레코드 갱신을
두 커밋으로 나눕니다. 🔴 판정을 완화하지 않았습니다(고친 것은 커밋 모양입니다) - feat:
delivery approve --allow-attested - fix:
commitgate attest가 만든 커밋을integrate가 판정하지 못하던 것 —
안내받은 예외 경로가 다음 관문을 막던 구조였습니다 - fix:
delivery reopen이 무효화한 승인의 통합 위임을 철회합니다 - fix:
req:delegate가--allow-push단독 위임을 발급 시점에 거부합니다 - docs: 묶음 정본을 코드 동작에 맞췄습니다(한글·영문)
전체 항목은 CHANGELOG 를 보세요.
업그레이드
0.27.x 에서 동작이 깨지는 변경은 없습니다. 기본 동작은 그대로이고, 묶음을 쓰지 않으면 달라지는 것이 없습니다.
npm i -D commitgate@0.28.0
npx commitgate sync --apply --scripts
npx commitgate quickstart --apply
npx commitgate check검증
로컬 게이트 전부 통과: typecheck · docs:lint · npm test · smoke(pack tarball 설치본) ·
npm pack --dry-run · verify-range --strict(149커밋 · 미입증 0 · 손상 0).
🔴 GitHub CI 는 실행하지 않았습니다 — 이 프로젝트는 CI 를 배제했고 검증 축은 로컬 게이트입니다.
v0.27.1
v0.27.0
v0.26.0
소비자 리포트(delivery 묶음을 쓰지 않는 저장소에서 integrate 가 통과 불가)에서 나온 결함과 그 후속입니다.
fix — integrate 가 판정 불가의 사유를 사실대로 말합니다
묶음(delivery)을 쓰지 않는 저장소에서 "묶음 레코드를 읽지 못해 …" 로 막히고, "없는 묶음의 레코드를 커밋하라" 는 실행 불가능한 안내를 냈습니다. 실제 사유는 범위에 들어 있던 attested 커밋이었습니다.
판정 불가에는 사유가 둘 있습니다 — 귀속 불가 커밋과 묶음 레코드 부재. 한 메시지로 뭉개져 있었고 그 메시지는 후자만 설명했습니다. 이제 귀속 불가로 막히면 막은 커밋의 SHA·범주·제목을 나열하고, delivery 라는 말은 실제로 묶음 레코드를 못 읽었을 때만 나옵니다.
🔴 거부 자체는 옳았습니다. attested 는 정식 리뷰 없이 사람이 예외 승인한 커밋이라 의도적으로 자율 통합 대상이 아닙니다. 바뀐 것은 판정이 아니라 해상도입니다.
참고: 같은 코드가 0.23.1 에도 있었습니다. 앞선 통합이 통과한 것은 버전 때문이 아니라 그 범위에 attested 커밋이 없었기 때문입니다.
feat — req:delegate --allow-attested
비대화형(에이전트·CI)에서 attested 커밋이 섞인 범위를 통합할 감사 가능한 경로입니다. 그전에는 대화형 y 뿐이었는데, 그 자리는 fail-closed 판정을 사람이 덮는 자리라 매번 누르면 게이트가 형식이 됩니다.
--allow-push·--allow-bypass·--high-risk와 같은 패턴 — 기본 불허 · 사람이 미리 명시 · 원장 기록 · 정확히 한 번 소비 · 만료.- 🔴
attested외에는 아무것도 열리지 않습니다.unproven·invalid-evidence·분류 미상이 하나라도 섞이면 이 플래그와 무관하게 막힙니다. - 🔴 면제를 쓰면 그 위임이 반드시 평가됩니다 — 만료·trunk 이동·source 불일치 위임으로는 열리지 않습니다(
stopGate값과 무관). - 통합 보고에 실제로 실린 attested 커밋의 SHA·제목이 남습니다.
- 옛 원장 행은 그대로 읽히고
false(불허)로 취급됩니다 — 업그레이드가 기존 위임을 손상으로 만들지 않습니다.
docs — 부기 트레일러는 도구만 붙입니다
사람이 손으로 CommitGate-Bookkeeping: true 를 붙인 커밋이 다른 파일을 바꾸면 "손상 증거"로 막히고 attest 로도 구제되지 않습니다. 게이트와 진단은 옳게 동작했지만 그 규칙이 어디에도 적혀 있지 않았습니다.
v0.25.2
0.22.0 설치본을 0.25.1 로 올리는 전 과정을 재현해, 문서를 그대로 따라가도 끝나지 않은 채로 끝난 줄 아는 지점들을 고쳤습니다.
docs — 업그레이드 절차를 한 구역으로
- 🔴 반복까지가 절차입니다. 폐기된 계약 서술(
contract-claims)은 한 문서의 여러 자리에 있을 수 있습니다. 실측에서AGENTS.md한 파일에 두 자리가 있었고, 첫 자리를 고친 뒤check를 다시 돌려서야 두 번째가 나왔습니다. - 🔴 인용된 문장을 그대로 검색하면 찾지 못할 수 있습니다 — 대조 전에 강조·코드 표시 문자를 제거하기 때문입니다.
- 🔴 끝났는지 판정하는 기준을 적었습니다:
C7의 조치 0. - 🔴 어느 진단에도 걸리지 않는 축(companion skills·
.cursor규칙)의 대조 경로와,diff가 정상인데도 내는 비대칭 둘.
README 의 업그레이드 진입점은 이제 고치는 명령이 아니라 진단(npx commitgate check)입니다. 무엇을 실행할지는 축마다 다르고, 그것을 아는 것은 도구입니다.
fix — 마지막 phase 리뷰가 막히던 스키마 안내 공백
이 릴리스를 만들다 실제로 걸렸습니다. REQ 의 마지막 phase 를 리뷰하면 리뷰어가 status="STEP_COMPLETE" 와 merge_ready="yes" 를 함께 내고, 도구가 그것을 모순으로 옳게 거부해 BLOCKED 됩니다.
원인은 판정이 아니라 안내였습니다 — 교차 규칙을 도구가 검사만 하고 리뷰어가 받는 스키마에는 적지 않았습니다. status·merge_ready 에 설명을 넣었고, 마지막 phase 여도 merge_ready="no" 라는 것을 명시합니다. 검증 규칙 자체는 그대로입니다.
스키마는 vendored 자산이라 소비 프로젝트는 npx commitgate sync --apply 로 받습니다.
v0.25.1
도그푸드 검증(0.22.0 → 0.25.0 실제 업그레이드 재현)에서 찾은 결함 두 건을 고쳤습니다.
fix — CommitGate 설치가 아닌 디렉터리에서 check 가 거짓 조치를 안내하던 것
package.json 도 workflow/ 도 없는 곳에서 C7 이 "persona 부재 → sync --apply --persona --persona-apply" 라고 말했습니다. CommitGate 프로젝트가 아닌 곳에 파일을 만들라는 안내였습니다.
이제 자산 축 다섯(req-scripts·vendored-schema·workflow-gitignore·managed-blocks·review-persona)은 설치 신호를 전제로 판정합니다. 신호가 하나도 없으면 조치도 정상도 아닌 판정 불가입니다. 판정에는 req:doctor D24 가 쓰는 술어를 그대로 씁니다.
feat — req:* verb 전부가 -h/--help 로 사용법을 냅니다
실측하면 12개 중 11개가 commitgate: 알 수 없는 옵션: --help 로 거부했습니다. 그 안에 req:confirm(HIGH 확인)·req:rebind·req:review-exception 같은 사람 전용 통제점 명령이 있었습니다.
- 사용법은 모든 게이트보다 앞입니다 — setup 이 끝나지 않은 디렉터리에서도 나옵니다.
- 적힌 옵션은 파서가 실제로 해석하는 것뿐이고, 가드가 각 플래그를 그 verb 의 파서에 넣어 고정합니다.
전체 내역: CHANGELOG
v0.25.0
-
feat:
commitgate check가 업그레이드 축 여덟 개를 집계해 보고합니다(C7) — 업그레이드 후
무엇을 확인하고 무엇을 실행할지가 한 명령으로 끝납니다. 여덟 축을 전부 세고, 정상이 아닌 축만
사유·조치와 함께 나열합니다(전부 정상이면 집계 한 줄).[WARN] C7: 업그레이드 축 8개 — 조치 1 · 정상 6 · 사람 확인 1 · 판정 불가 0 - caret-range : 진단 없음 — 설치 범위를 사람이 확인 - req-scripts : 없는 verb 2개: req:delegate · req:repolicy → npx commitgate sync --apply --scripts- 🔴 왜
check인가: 티켓 없이 돌릴 수 있는 유일한 명령입니다. 나머지 축을 보던req:doctor는
REQ id 를 요구해서 업그레이드 직후(티켓이 없을 수 있는 시점, 정확히 축을 봐야 할 때)에 쓸 수
없었습니다. 그때check는 8축 중 2축만 봤습니다. - WARN 상한이고 exit 계약은 그대로입니다 — 업그레이드가 안 끝났다는 이유로 CI·에이전트가 죽지
않습니다. 판정 불가·사람 확인은 조치로 세지 않습니다(모르는 것을 결함으로 말하지 않습니다). - 축은 REQ-2026-164 의 등록부에서 나옵니다 — 축을 늘리면 출력이 자동으로 따라오고, 판정기를 빠뜨리면
"판정기 미등록"으로 드러납니다. - 판정은 기존 술어(
missingReqScripts·classifyInstallMode·unprotectedRepoRootScratch·planSync)를
재사용합니다 —check가 자기 판정을 새로 쓰면doctor와 갈라집니다.
확인할 파일:
bin/check.ts(C7) ·scripts/req/lib/upgrade-status.ts(순수 판정) ·
scripts/req/lib/install-shape.ts(leaf 로 내린 설치 형태 술어) - 🔴 왜
-
fix: 업그레이드 절차가 문서마다 갈라지던 문제 — 조치가 필요한 축은 여덟 개인데(caret 범위 ·
req:*명령 표면 · vendored 스키마 ·workflow/.gitignore· 관리 블록 · review persona · 혼합 설치 ·
AGENTS.md계약 문구) 진단은checkC5·C6 와doctorD19~D33 에 흩어져 있고, id 가 아예 없는 축도
있습니다 — review persona 는npx commitgate sync --persona계획 출력으로만 드러나고, caret 범위는
진단 수단 자체가 없습니다. 조치는sync4축·quickstart·migrate·수동에 나뉩니다.
어느 문서도 이것을 한 자리에서 열거하지 않았습니다.- 실제로 0.24.0 직전까지 README 한/영이
sync --apply --gitignore를 안내했습니다 — 그 릴리스가
docs/upgrade.*만 고치고 README 를 빠뜨린 결과입니다. 축을 늘린 사람이 문서 네 곳을 기억해야 하는
구조라, 기억에 기대는 한 또 갈라집니다. - 이제 축 등록부가 코드에 있고(
lib/upgrade-axes.ts)docs/upgrade.md·.en.md의 축 표가 그것을
담는지 테스트가 검사합니다. 축을 늘리고 문서를 안 고치면 red 입니다. - README 는 절차를 복제하지 않고 요약 한 줄 + 정본 링크만 둡니다. 가드가 문구가 아니라 구조를
봅니다(요약 명령 그대로 · 정본 링크 · 표 없음 · 명령 하나 · 축 id 미나열). - 🔴 진단은 체크 id 만이 아닙니다. 등록부가 세 종류를 타입으로 구분합니다 — 체크 id(
C6·D20…) ·
명령 출력(review persona →npx commitgate sync --persona) · 없음(caret 범위 —^0.x는 소비자
package.json에서 패키지매니저가 강제해 도구가 감지할 수 없습니다). 없는 진단을 있다고 적지 않습니다. - 🔴 순수 Stage A 는 결함이 아닙니다 —
D19는 Stage A/B 가 섞였을 때만 경고합니다. 표의 축
이름을mixed-install로 두어 없는 진단을 안내하지 않습니다.
확인할 파일:
scripts/req/lib/upgrade-axes.ts·docs/upgrade.md(축 표) ·README.md(요약 구역) ·
tests/unit/upgrade-axes.test.ts - 실제로 0.24.0 직전까지 README 한/영이