axmap-cli 1.1.1 → 1.2.0

package/governance/GOVERNANCE.md

@@ -212,7 +212,7 @@ node axmap/governance/gate.mjs --source <소스브랜치> --target <타깃브랜
 
 | | | 안 지키면 |
 |---|---|---|
-| **G1** | **자기 표는 세지 않는다** — MR 소스 브랜치 커밋의 author 인 사람의 표는 무효 | 혼자 쓰고 혼자 승인한다 |
+| **G1** | **자기 표는 세지 않는다** — MR 소스 브랜치 커밋의 author 인 사람의 표는 무효 (예외 하나 — 바로 아래) | 혼자 쓰고 혼자 승인한다 |
 | **G2** | **정책은 언제나 타깃 브랜치**(**합쳐 받는 쪽 브랜치**)**에서 읽는다** | 정족수를 1 로 낮추는 MR 이 **자기 자신의 낮춘 규칙으로** 통과한다 |
 | **G3** | **표는 커밋(sha)에 묶인다** — 헤드가 바뀌면 효력을 잃는다 | 승인받은 뒤 내용을 갈아끼운다 |
 | **G4** | **한 사람은 한 표** — id 유일, email 유일 | 명단에 자기를 두 줄 적으면 두 표다 |
@@ -225,6 +225,58 @@ node axmap/governance/gate.mjs --source <소스브랜치> --target <타깃브랜
 **G2 만 순수 판정 밖에 있다.** 어느 브랜치에서 정책을 읽어오는가는 git 을 만지는
 일이라 게이트의 책임이다. `src/governance.mjs` 는 **읽어온 정책이 성립하는지**만 본다.
 
+### 🔴 G1 의 예외 하나 — 던질 수 있는 사람이 정족수보다 적을 때
+
+오래 쌓는 `<파트>/dev` 브랜치에서는 시간이 갈수록 커밋한 사람이 늘어
+**던질 수 있는 사람이 0 으로 수렴한다.** 실측 (팀 저장소 S15P21E201, 2026-09-07):
+
+| 브랜치 | 투표권자 | 그중 소스 브랜치의 author | 던질 수 있는 사람 | 정족수 |
+|---|---|---|---|---|
+| `front/main` ← `front/dev` | 4명 | **4명 전원** | **0명** | 2 |
+| `back/main` ← `back/dev` | 6명 | **6명 전원** | **0명** | 2 |
+
+이건 **"아직 표가 모자라다"(미달)가 아니다.** 표를 더 모아도 안 풀린다 — 던질 수
+있는 사람 자체가 없기 때문이다. 그 상태에 미달(종료 코드 2)을 내면 부르는 쪽에게
+*"사람에게 부탁하면 된다"* 고 거짓말을 하는 것이고, 사람은 시스템 밖에서
+탈출한다 (`hotfix/` 를 코드 안에 둔 것과 같은 이유다).
+
+그래서 **그 판정 하나에 한해** G1 을 푼다. 조건 셋을 **모두** 만족할 때만이다.
+
+| | |
+|---|---|
+| 1 | 이번 판정의 **정족수를 숫자로 알고 있다** (`judge` 가 `countVotes` 에 넘긴다) |
+| 2 | **G1 이 실제로 명단에서 누군가를 뺐다** — 안 뺐으면 G1 이 만든 교착이 아니다 |
+| 3 | 그러고 **남은 사람이 정족수보다 적다** |
+
+2번이 없으면 *"명단 자체가 정족수보다 작다"*(승계로도 못 채운 **막힌 저장소**)까지
+이 문으로 샌다. 그건 G1 을 풀어도 아무도 못 던지므로, 판정문에 거짓 사유만
+한 줄 남는다.
+
+**바뀌지 않는 것 — 이게 절반이다.**
+
+- **정족수 숫자.** `majorityThreshold` 는 그대로다. 문턱을 낮추면 *"최소 두 사람이
+  본다"* 는 팀의 뜻이 조용히 사라진다. 여기서 푸는 것은 **누가 던질 수 있는가** 하나다
+- **G3 · G4 · G5**, 브랜치 대조, committer(**표를 기록한 git 신원**) 대조,
+  `vote_note`, 미래 시각 — 전부 그대로 돈다
+- **fail-closed.** 소스 브랜치의 author 목록을 못 받으면 여전히 판정 불가다
+  (`authors-missing`). **"저자를 모를 때" 는 해제 조건이 아니다** — 거기로 새면
+  G1 은 켜고 끄는 스위치가 되고, 그건 성질이 아니라 설정이다
+
+🔴 **해제는 조용히 발동하지 않는다.** 승계와 같은 규칙이다 — 판정문이 찍는다.
+
+```
+🔴 G1(자기 표 배제)이 해제된 판정입니다 — 유효 투표권자 0명 < 정족수 2.
+   저자 본인의 표를 셌습니다.
+```
+
+해제 덕분에 세어진 사람의 이름까지 남는다. 기계가 읽을 표식은 `tally` 에 있다 —
+`g1Waived` · `eligibleCount` · `threshold` · `selfVoted`. `gate --json` 이 그대로 낸다.
+
+**`self_vote` 정책(아래)과는 다른 층이다.** `self_vote` 는 *"누구까지를 자기로
+보는가"* 를 **사람이 미리 정하는 것**이고, 이 예외는 *"그렇게 정했더니 아무도 못
+던지게 됐을 때"* **코드가 그 판정에서만 푸는 것**이다. `self_vote: "off"` 면
+배제할 사람이 없으므로 이 예외는 아예 안 걸린다.
+
 ---
 
 ## 종료 코드
@@ -496,7 +548,9 @@ git log --format=%B -1 <커밋> | git interpret-trailers --parse
 살아 있는 투표권자가 필요 표보다 적으면, 최근 90일 안에 커밋한 author 상위 3명이
 **임시 투표권**을 갖는다.
 
-- 승계로 들어온 사람도 **자기 표는 못 센다** (G1 은 예외가 없다)
+- 승계로 들어온 사람도 **자기 표는 못 센다** (G1). 예외는 하나 — 던질 수 있는
+  사람이 정족수보다 적어 G1 이 해제된 판정에서는 승계로 들어온 사람의 자기 표도
+  센다 (위 "G1 의 예외 하나")
 - 정책에 적힌 사람은 **살아 있지 않아도 투표권을 잃지 않는다.** 생사는 *승계를 켤지*만
   정한다. 두 달 자리를 비운 사람이 돌아와 던진 표가 안 세지면 그건 fail-closed 가
   아니라 그냥 틀린 판정이다

package/package.json

@@ -1,7 +1,7 @@
 {
   "//name": "🔴 npm 의 'axmap' 은 2022년부터 남이 쓰고 있는 다른 꾸러미다(leozin_ 의 Map 라이브러리, 1.1.2). 그래서 `npx axmap` 은 우리 것이 아니고, 누구에게도 그렇게 안내하면 안 된다. 2026-08-28 에 axmap-cli 로 정했다 — 스코프(@사용자/이름)를 쓰지 않는 이유는 스코프가 npm 계정 이름에 묶여서 나중에 팀이나 조직으로 옮길 때 이름이 통째로 바뀌기 때문이다. 사람이 치는 **명령** 이름은 그대로 axmap 이다 (아래 bin) — 꾸러미 이름과 명령 이름은 달라도 된다.",
   "name": "axmap-cli",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "//private": "🔴 여기 있던 \"private\": true 를 2026-08-28 에 지웠다. 그 줄이 있는 동안 npm publish 는 거부됐다. 되돌리려면 다시 넣으면 되지만, 이미 올라간 버전은 그래도 안 사라진다 — npm 은 같은 번호를 덮어쓰지 못하고 삭제도 72시간 안에만 된다. 즉 이 줄을 되살리는 것은 '앞으로 안 올린다' 는 뜻이지 '올린 것을 없앤다' 는 뜻이 아니다.",
   "//publishConfig": "axmap-cli 는 스코프가 없어서 기본이 이미 공개다. 즉 지금은 없어도 된다. 그래도 남겨 두는 이유: 나중에 @조직/axmap 처럼 스코프를 붙이는 날 이 줄이 없으면 publish 가 '유료 플랜이 필요하다'는 엉뚱한 말로 실패한다.",
   "publishConfig": {

package/src/governance.mjs

@@ -929,9 +929,15 @@ const FUTURE_TOLERANCE_MS = 24 * 60 * 60 * 1000
  * @param {string|null} [args.branch] 소스 브랜치 이름. 주면 표의 branch 와 대조한다
  * @param {string|null} [args.tipAuthorEmail] 맨 위 커밋의 author email.
  *        `self_vote: "tip"` 일 때만 쓰이고, 그때는 **없으면 판정 불가**다
- * @returns {{approvals:number, counted:Array, rejections:Array, invalid:Array}}
+ * @param {number|null} [args.threshold] 이번 판정의 정족수. **주면** 자기 표 배제가
+ *        판정을 불가능하게 만드는지 볼 수 있다 (아래 waiver). 안 주면 해제는
+ *        영영 안 걸린다 — 모르면 안 푸는 쪽이 fail-closed 다. `judge` 가 넣어 준다
+ * @returns {{approvals:number, counted:Array, rejections:Array, invalid:Array,
+ *            g1Waived:boolean, eligibleCount:number, threshold:number|null, selfVoted:Array}}
  */
-export function countVotes({ policy, votes, authorEmails, sha, now, voters = null, branch = null, tipAuthorEmail = null }) {
+export function countVotes({
+  policy, votes, authorEmails, sha, now, voters = null, branch = null, tipAuthorEmail = null, threshold = null,
+}) {
   const roster = voters ?? policy?.voters ?? null
   if (!Array.isArray(roster) || roster.length === 0) {
     throw new GovernanceError('투표권자 명단이 없습니다.', { exit: EXIT.POLICY_BROKEN, code: 'voters-missing' })
@@ -966,9 +972,41 @@ export function countVotes({ policy, votes, authorEmails, sha, now, voters = nul
   const authors = excludedAuthors(selfVote, authorEmails, tipAuthorEmail)
   const byEmail = new Map(roster.map((v) => [fold(v.email), v]))
 
+  // ── G1 해제(waiver) — 자기 표 배제가 **판정 자체를 불가능하게 만들 때만** ────
+  //
+  // 🔴 왜 필요한가 — 실측. 오래 쌓는 `<파트>/dev` 브랜치에서는 시간이 갈수록
+  //    커밋한 사람이 늘어 "던질 수 있는 사람" 이 0 으로 수렴한다. 팀 저장소의
+  //    `front/main` 은 투표권자 4명이 **전원 저자**였고(정족수 2), `back/dev` 는
+  //    명단 6명 전원이 저자였다. 이건 "아직 표가 모자라다"(미달, exit 2)가 아니라
+  //    **표를 더 모아도 영원히 안 풀리는 교착**이다. 재시도가 답이 아닌 상태에
+  //    미달 코드를 내는 것은 부르는 쪽에게 거짓말을 하는 것이다.
+  //
+  // 🔴 해제 조건을 좁게 잡는다. 셋을 **모두** 만족해야 한다.
+  //      1. 이번 판정의 정족수를 숫자로 알고 있다 (`threshold` 를 받았다)
+  //      2. G1 이 실제로 명단에서 누군가를 뺐다 (`excludedFromRoster > 0`)
+  //      3. 그러고 남은 사람이 정족수보다 적다 (`eligibleCount < threshold`)
+  //    2번이 없으면 "명단 자체가 정족수보다 작다"(승계로도 못 채운 막힌 저장소)
+  //    까지 이 문으로 새어 나온다. 그건 G1 이 만든 교착이 아니므로 G1 을 풀어도
+  //    아무도 못 던진다 — 판정문에 거짓 사유만 한 줄 남는다.
+  //
+  // 🔴 **정족수 숫자는 건드리지 않는다.** 문턱을 낮추면 "두 사람이 본다" 는 팀의
+  //    뜻이 조용히 사라진다. 여기서 바꾸는 것은 **누가 던질 수 있는가** 하나다.
+  //
+  // 🔴 fail-closed 는 그대로다. 저자 목록을 못 받으면 위에서 이미 던졌다
+  //    (`authors-missing`). "저자를 모를 때" 는 해제 조건이 **아니다** —
+  //    모르는 것과 셀 수 없는 것을 통과로 바꾸면 이 층이 없는 것과 같다.
+  const eligible = roster.filter((v) => !authors.has(fold(v?.email)))
+  const eligibleCount = eligible.length
+  const excludedFromRoster = roster.length - eligibleCount
+  const need = isInt(threshold) && threshold >= 1 ? threshold : null
+  const g1Waived = need !== null && excludedFromRoster > 0 && eligibleCount < need
+
   const counted = []
   const rejections = []
   const invalid = []
+  // 해제 덕분에 세어진 표. **판정문에 이름까지 남긴다** — 해제가 조용히 발동하면
+  // 그건 예외가 아니라 우회로다 (승계를 출력에 찍는 것과 같은 이유).
+  const selfVoted = []
   const seen = new Map() // fold(email) -> 이미 센 표
 
   for (const raw of votes) {
@@ -993,7 +1031,8 @@ export function countVotes({ policy, votes, authorEmails, sha, now, voters = nul
     if (!isStr(v.committerEmail)) { bad('committer-unknown'); continue }
     if (fold(v.committerEmail) !== email) { bad('committer-mismatch', v.committerEmail); continue }
 
-    if (authors.has(email)) { bad('self-vote'); continue } // G1
+    // G1 · 자기 표는 안 센다. 단 해제된 판정에서는 센다 (위 waiver 주석).
+    if (authors.has(email) && !g1Waived) { bad('self-vote'); continue }
     if (toMs(v.at, 'votes[].at') > nowMs + FUTURE_TOLERANCE_MS) { bad('future-dated', v.at); continue }
     // 🔴 이유 없는 표는 **찬성이든 반대든** 안 센다. 반대야말로 이유가 필요하다 —
     //    이유 없는 반대는 판정문에 "누군가 막고 있다" 만 남기고 무엇을 고쳐야
@@ -1004,13 +1043,28 @@ export function countVotes({ policy, votes, authorEmails, sha, now, voters = nul
     if (seen.has(email)) { bad('duplicate', `이미 센 표: ${seen.get(email).voter}`); continue } // G4
 
     seen.set(email, v)
+    // 해제가 없었으면 여기 못 왔을 표. 판정문이 이름을 찍는다.
+    if (g1Waived && authors.has(email)) selfVoted.push({ voter: v.voter, email: v.email, vote: v.vote })
     if (v.vote === 'approve') counted.push(v)
     // 반대는 정족수 계산에 들어가지 않는다. 이 층이 답하는 질문은 "찬성이 몇인가"
     // 하나뿐이고, 거부권은 다른 제도다 — 만들려면 SPEC 부터 고쳐야 한다.
     else rejections.push(v)
   }
 
-  return { approvals: counted.length, counted, rejections, invalid }
+  return {
+    approvals: counted.length,
+    counted,
+    rejections,
+    invalid,
+    // ── 기계가 읽는 해제 표식 ────────────────────────────────────────────
+    // `gate.mjs --json` 이 이 셋을 그대로 내보낸다. 판정문의 한 줄이 지워져도
+    // 이 표식은 남는다 — 나중에 "이 판정이 예외였나" 를 사람이 아니라 코드가
+    // 물어볼 수 있어야 한다.
+    g1Waived,
+    eligibleCount,
+    threshold: need,
+    selfVoted,
+  }
 }
 
 /**
@@ -1084,7 +1138,14 @@ export function judge({
       : null
     const need = rulesFor(changed, policy, { majority })
     const roster = deriveVoters({ policy, contributors, now, threshold: need.threshold })
-    const tally = countVotes({ policy, votes, authorEmails, sha, now, voters: roster.voters, branch, tipAuthorEmail })
+    // 🔴 정족수를 **분자 쪽에도** 넘긴다. `countVotes` 는 이 숫자가 있어야
+    //    "자기 표를 빼고 나면 던질 수 있는 사람이 정족수보다 적은가" 를 볼 수
+    //    있다. 문턱은 여기서 정해지므로(`rulesFor`) 그 값을 그대로 준다 —
+    //    분자가 다른 문턱을 보고 해제를 판단하면 판정만 조용히 틀린다.
+    const tally = countVotes({
+      policy, votes, authorEmails, sha, now, voters: roster.voters, branch, tipAuthorEmail,
+      threshold: need.threshold,
+    })
     const ok = tally.approvals >= need.threshold
     return {
       exit: ok ? EXIT.OK : EXIT.SHORT,
@@ -1141,6 +1202,22 @@ export function formatVerdict(verdict) {
   }
   L.push('')
 
+  // 🔴 자기 표 배제 해제는 **조용히 발동하지 않는다.** 이 줄을 지우면 해제가
+  //    예외가 아니라 우회로가 된다 — 승계 줄을 지울 수 없는 것과 같은 이유다.
+  //    나중에 이력을 보는 사람이 "이 판정은 예외였다" 를 여기서 알아야 한다.
+  if (tally?.g1Waived) {
+    L.push(`  🔴 G1(자기 표 배제)이 해제된 판정입니다 — 유효 투표권자 ${tally.eligibleCount}명 < 정족수 ${threshold}. 저자 본인의 표를 셌습니다.`)
+    L.push('     오래 쌓인 브랜치는 투표권자가 전부 저자가 되어 던질 수 있는 사람이 0 이 됩니다.')
+    L.push('     그건 표가 모자란 것이 아니라 표를 더 모아도 안 풀리는 교착이라, 이 판정에 한해서만 풉니다.')
+    L.push('     🔴 정족수 숫자는 그대로입니다. G3(표는 커밋에 묶인다)·G4(같은 사람의 두 번째 표)·')
+    L.push('        브랜치 대조·committer(표를 기록한 git 신원) 대조도 전부 그대로 돕니다.')
+    if (tally.selfVoted?.length) {
+      L.push('     해제 덕분에 센 표')
+      for (const s of tally.selfVoted) L.push(`       ! ${s.voter} <${s.email}>  ${s.vote}`)
+    }
+    L.push('')
+  }
+
   if (tally.counted.length) {
     L.push('  센 표')
     for (const c of tally.counted) L.push(`    o ${c.voter} <${c.email}>  ${c.at}`)
@@ -1173,7 +1250,10 @@ export function formatVerdict(verdict) {
     } else {
       L.push('     그런데 창 안에 기여자가 없습니다.')
     }
-    L.push('     승계로 들어온 사람도 자기 표는 세지 않습니다 (G1).')
+    // 해제된 판정에서는 이 줄이 거짓이 된다. 틀린 안내는 안 하는 것만 못하다.
+    L.push(tally?.g1Waived
+      ? '     이 판정은 자기 표 배제가 해제되어 있어 승계로 들어온 사람의 자기 표도 셉니다 (위 🔴).'
+      : '     승계로 들어온 사람도 자기 표는 세지 않습니다 (G1).')
     L.push('')
   }
   if (roster.short > 0) {