axmap-cli 0.0.1

package/src/invariants.mjs

@@ -0,0 +1,226 @@
+/**
+ * 불변식 검사기.
+ *
+ * docs/INVARIANTS.md 의 I1~I8 을 코드로 옮긴 것이다.
+ * 모델 검증기(test/model.test.mjs), 카오스 테스트(demo/chaos.sh),
+ * 사후 감사(axmap audit)가 **같은 검사기**를 쓴다.
+ * 도구마다 다른 판정을 하면 무엇이 맞는지 알 수 없게 된다.
+ *
+ * 여기도 순수하다. git 도 파일시스템도 없다.
+ */
+
+import {
+  DEFAULT_MERGE_POLICY,
+  activeClaims,
+  claimExpiresAt,
+  normalizePath,
+  pathsOverlap,
+} from './protocol.mjs'
+
+// ---------------------------------------------------------------------------
+// I1 · 상호배제 (상태 불변식)
+// 어느 시점에도, 서로 겹치는 경로를 유효하게 소유한 에이전트는 최대 1명이다.
+// ---------------------------------------------------------------------------
+
+export function mutualExclusionViolations(claims, now) {
+  const live = activeClaims(claims, now)
+  const out = []
+  for (let i = 0; i < live.length; i++) {
+    for (let j = i + 1; j < live.length; j++) {
+      const a = live[i]
+      const b = live[j]
+      if (a.agent === b.agent) continue
+      for (const pa of a.paths.map(normalizePath)) {
+        for (const pb of b.paths.map(normalizePath)) {
+          if (pathsOverlap(pa, pb)) {
+            out.push({
+              invariant: 'I1',
+              message: `${pa} 와 ${pb} 를 ${a.agent} 와 ${b.agent} 가 동시에 소유`,
+              agents: [a.agent, b.agent],
+              paths: [pa, pb],
+              windows: [
+                { agent: a.agent, since: a.since, until: new Date(claimExpiresAt(a)).toISOString() },
+                { agent: b.agent, since: b.since, until: new Date(claimExpiresAt(b)).toISOString() },
+              ],
+            })
+          }
+        }
+      }
+    }
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// I2 · 무손실 (전이 불변식)
+// claim 이 성공을 반환했으면, 요청한 경로는 반드시 내 레코드에 있다.
+// ---------------------------------------------------------------------------
+
+export function lossViolations({ requested, record }) {
+  const have = new Set(record.paths.map(normalizePath))
+  return requested
+    .map(normalizePath)
+    .filter((p) => !have.has(p))
+    .map((p) => ({
+      invariant: 'I2',
+      message: `claim 이 성공했는데 ${p} 가 레코드에 없다`,
+      agents: [record.agent],
+      paths: [p],
+    }))
+}
+
+// ---------------------------------------------------------------------------
+// I6 · 비부활 (전이 불변식)
+// 성공한 claim 의 경로는 (요청한 경로 ∪ 직전 "유효" claim 의 경로) 안에 있어야 한다.
+// 만료된 내 레코드에서 넘어온 경로는 관문 2 를 거치지 않았으므로 부활이다.
+// ---------------------------------------------------------------------------
+
+export function resurrectionViolations({ before, after, requested, me, now }) {
+  const prev = activeClaims(before, now).find((c) => c.agent === me)
+  const allowed = new Set([
+    ...requested.map(normalizePath),
+    ...(prev?.paths ?? []).map(normalizePath),
+  ])
+  const mine = after.find((c) => c.agent === me)
+  if (!mine) return []
+  return mine.paths
+    .map(normalizePath)
+    .filter((p) => !allowed.has(p))
+    .map((p) => ({
+      invariant: 'I6',
+      message: `${p} 가 만료된 레코드에서 검사 없이 부활했다`,
+      agents: [me],
+      paths: [p],
+    }))
+}
+
+// ---------------------------------------------------------------------------
+// I7 · 세션 이름 유일성 (상태 불변식)
+// 한 슬롯 레지스트리 안에서 동시에 살아있는 두 세션은 서로 다른 AXMAP_AGENT 를 갖는다.
+//
+// 🔴 "모든 에이전트의 이름이 다르다" 는 여기에 적을 수 없다. 사람이 두 셸에
+//    같은 AXMAP_AGENT 를 넣으면 시스템이 막을 방법이 없고, 검사할 수 없는 문장을
+//    불변식이라고 적어두면 그 목록 전체의 신뢰가 떨어진다.
+//    시스템이 **실제로 보장할 수 있는 것**은 자기가 띄운 세션들의 이름뿐이다.
+// ---------------------------------------------------------------------------
+
+export function sessionIdentityViolations(sessions) {
+  const out = []
+  const seen = new Map()
+  for (const s of sessions ?? []) {
+    const id = s?.id ?? null
+    const name = typeof s?.agent === 'string' ? s.agent.trim() : ''
+    /**
+     * 이름이 없는 것을 건너뛰지 않는다. 이름이 없는 세션은 자식이 서버의 환경을
+     * 그대로 물려받는다는 뜻이고, 그것이 이 불변식을 만든 버그 그 자체다.
+     * 여기서 조용히 넘기면 "위반 0" 이 "아무 문제 없음" 으로 읽힌다.
+     */
+    if (!name) {
+      out.push({
+        invariant: 'I7',
+        message: `세션 ${id} 에 이름이 없다 — 자식이 서버의 AXMAP_AGENT 를 그대로 물려받는다`,
+        agents: [],
+        sessions: [id],
+      })
+      continue
+    }
+    const prev = seen.get(name)
+    if (prev !== undefined && prev !== id) {
+      out.push({
+        invariant: 'I7',
+        message: `세션 ${prev} 와 ${id} 가 같은 이름 "${name}" 을 쓴다 — 서로를 겹침으로 보지 못한다`,
+        agents: [name],
+        sessions: [prev, id],
+      })
+      continue
+    }
+    seen.set(name, id)
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// I8 · 게이트 우선 (전이 불변식)
+// 게이트가 하나라도 빨갛거나 빠진 제안은 어떤 표 조합으로도 병합되지 않는다.
+//
+// I5(강제)와 같은 자리에 있다. I5 가 없으면 claim 이 권고 사항이 되듯,
+// I8 이 없으면 게이트가 권고 사항이 된다. 그리고 "작업 노드가 없어도 도는
+// 시스템" 의 실패 모드는 멈춤이 아니라 조용한 부패다 - 아무도 안 볼 때
+// 자동 워커가 빨간 것을 밀어 넣고, 그것을 아무도 모른다.
+//
+// checkMerge 를 부르지 않고 게이트만 다시 본다. 판정을 만든 함수로 그 판정을
+// 검사하면 검사 대상이 제품이 아니라 검사기가 된다 (모델 검증기의 oracle 원칙).
+// ---------------------------------------------------------------------------
+
+export function gatePrecedenceViolations({ merge, policy = DEFAULT_MERGE_POLICY }) {
+  const gates = merge.gates ?? {}
+  const out = []
+  for (const name of policy.requiredGates) {
+    const g = gates[name]
+    if (g && g.ok) continue
+    out.push({
+      invariant: 'I8',
+      message: g
+        ? `게이트 ${name} 가 빨간 채로 ${merge.id} 가 병합됐다`
+        : `게이트 ${name} 를 돌리지 않은 채 ${merge.id} 가 병합됐다`,
+      agents: merge.agent ? [merge.agent] : [],
+      paths: merge.paths ?? [],
+      gate: name,
+    })
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// 사후 감사
+//
+// 장부 브랜치는 모든 claim 변화를 커밋으로 기록한 완전한 감사 로그다.
+// 스냅샷을 순서대로 재생하면 상호배제가 깨진 적이 있는지 사후에 증명할 수 있다.
+// 구현을 믿을 필요가 없어진다는 것이 이 검사의 핵심이다.
+// ---------------------------------------------------------------------------
+
+/**
+ * 스냅샷의 논리 시각.
+ *
+ * 커밋 시각을 그대로 쓰지 않는 이유: 테스트가 AXMAP_NOW 로 시계를 옮기면
+ * 커밋 시각(실제 벽시계)과 레코드의 since(논리 시각)가 어긋난다.
+ * since 는 논리적으로 미래일 수 없으므로, 둘 중 늦은 쪽이 그 스냅샷의 시각이다.
+ * 실제 사용에서는 항상 since <= 커밋 시각이므로 커밋 시각과 같다.
+ */
+export function snapshotTime(snapshot) {
+  const sinces = snapshot.claims.map((c) => Date.parse(c.since)).filter((n) => !Number.isNaN(n))
+  return Math.max(snapshot.time, ...(sinces.length ? sinces : [snapshot.time]))
+}
+
+/**
+ * 시간이 흐르는 것만으로는 겹침이 생기지 않는다 (만료는 claim 을 없앨 뿐이다).
+ * 겹침은 오직 claim 이 추가될 때 생기고, claim 은 커밋으로만 추가된다.
+ * 따라서 각 커밋 시점만 검사하면 전체 구간을 덮는다.
+ */
+export function auditLedger(snapshots) {
+  const violations = []
+  for (const snap of snapshots) {
+    const t = snapshotTime(snap)
+    for (const v of mutualExclusionViolations(snap.claims, t)) {
+      violations.push({ ...v, commit: snap.commit, subject: snap.subject, at: new Date(t).toISOString() })
+    }
+  }
+  return { ok: violations.length === 0, checked: snapshots.length, violations }
+}
+
+export function formatAudit(report) {
+  if (report.ok) {
+    return (
+      `감사 통과 - 스냅샷 ${report.checked}개\n` +
+      '장부 이력 전체에서 상호배제(I1)가 깨진 시점이 없습니다.'
+    )
+  }
+  const lines = [`감사 실패 - 스냅샷 ${report.checked}개 중 위반 ${report.violations.length}건\n`]
+  for (const v of report.violations) {
+    lines.push(`  x [${v.invariant}] ${v.at}  commit ${v.commit.slice(0, 7)}  ${v.subject}`)
+    lines.push(`      ${v.message}`)
+    for (const w of v.windows ?? []) lines.push(`      ${w.agent}: ${w.since} ~ ${w.until}`)
+    lines.push('')
+  }
+  return lines.join('\n')
+}

package/src/mrtarget.mjs

@@ -0,0 +1,284 @@
+/**
+ * MR(**Merge Request** — 내 브랜치의 변경을 다른 브랜치로 합쳐 달라는 요청)이
+ * **한 칸씩만 올라가게** 하는 판정.
+ *
+ * 순수 로직만 둔다. git 호출도 환경변수도 여기 없다 (`tools/mr-target.mjs` 가 담당).
+ *
+ * ── 왜 설정이 아니라 코드인가 ────────────────────────────────────────────────
+ *
+ * 이 GitLab 은 Community Edition(무료판)이라 **"이 브랜치로는 MR 을 못 연다"
+ * 는 설정이 없다.** 대상 브랜치를 제한하는 기능 자체가 없고, 있는 것은
+ * 기본 대상 브랜치를 정해 두는 것뿐이다 — 사람이 드롭다운에서 바꾸면 그만이다.
+ *
+ * 그래서 잡(job — 파이프라인이 돌리는 작업 하나)으로 만든다. 루트 `CLAUDE.md`
+ * 3절이 말하는 그대로다: 권한은 사람의 목록이고 파이프라인은 코드의 조건이다.
+ *
+ * ── 왜 단계 판정을 새로 안 만드는가 ───────────────────────────────────────────
+ *
+ * 🔴 `levelOf` 를 `src/version.mjs` 에서 **가져다 쓴다.** 여기서 다시 만들면
+ *    한 저장소에 브랜치 단계 판정이 둘이 되고, 그러면 `back/main` 이 최상위인지
+ *    파트인지를 **버전 자동화와 MR 검사가 서로 다르게 답할 수 있다.**
+ *    거버넌스가 경로 매칭을 새로 안 만들고 `protocol.mjs` 의 `coversPath` 를
+ *    그대로 쓴 것과 같은 이유다.
+ */
+
+import { levelOf, partOf, isNonProductPart } from './version.mjs'
+
+// 🔴 `partOf` 는 `version.mjs` 로 옮겼다. 여기서 다시 내보내는 것은 이미 이 모듈에서
+//    가져다 쓰는 곳(`src/promote.mjs`, `test/mrtarget.test.mjs`)을 깨지 않기 위해서다.
+export { partOf }
+
+/**
+ * 종료 코드. 선점 프로토콜·거버넌스와 같은 관례다.
+ *
+ * 🔴 **2 와 1 을 가르는 것이 핵심이다.**
+ *    2 는 "대상 브랜치를 바꾸면 되는 일", 1 은 "내가 판정을 못 했다".
+ *    뭉치면 AI 에이전트가 고장을 **고치면 되는 일**로 읽고 엉뚱한 곳을 고친다.
+ */
+export const EXIT = {
+  OK: 0,
+  /** 규칙 위반 — 사람이 MR 대상을 바꾸면 풀린다 */
+  BLOCKED: 2,
+  /** 판정 불가 — 브랜치 이름을 못 받았다. 환경을 고쳐야 한다 */
+  UNDECIDABLE: 1,
+}
+
+/**
+ * MR 의 소스도 대상도 될 수 없는 브랜치.
+ *
+ * 장부(`axmap/claims`)와 표(`axmap/votes`)는 **코드와 이력을 공유하지 않는
+ * 고아 브랜치**(orphan branch — 부모 커밋이 없어 코드 브랜치와 아예 갈라져 있는
+ * 브랜치)다. 도구가 직접 쓰고 읽는 자리이지 사람이 합치는 자리가 아니다.
+ *
+ * 이름만 보면 `axmap/claims` 는 "axmap 파트의 claims 브랜치" 처럼 생겼다.
+ * 그래서 규칙에 안 걸리고 기능 브랜치로 취급돼 **`<파트>/dev` 로 올릴 수 있게
+ * 된다.** 명시적으로 막지 않으면 그 길이 열려 있다.
+ */
+const RESERVED = new Set(['axmap/claims', 'axmap/votes', 'axmap/bus'])
+
+/**
+ * 긴급 수정 브랜치인가 — `hotfix/…` 로 시작하는가.
+ *
+ * ── 🔴 이 판정은 사다리에 **구멍을 낸다.** 그 대가를 알고 낸 것이다 ──────────
+ *
+ * 사다리(기능 → `<파트>/dev` → `<파트>/main` → `main`)의 요점은 "아래 관문을
+ * 지난 것만 위로 간다" 이다. 여기만 그 규칙을 어긴다. 왜 어기는가.
+ *
+ * **고장 난 것이 `main` 자신일 때 사다리가 막다른 길이 되기 때문이다.**
+ * 2026-08-26 에 실제로 그랬다 — `main` 의 `.gitlab-ci.yml` 이 무효라 모든
+ * 파이프라인이 잡 0개로 죽었는데, 그것을 고치는 MR 이 `verify:mr-target` 에
+ * 걸려 `main` 으로 갈 수 없었다(S15P21E201-22). `Pipelines must succeed` 가
+ * 켜져 있었다면 **팀 전체가 CI 를 영영 못 고쳤을 것이다.**
+ *
+ * 탈출구가 없으면 사람은 시스템 밖에서 탈출한다 — 스위치를 잠깐 내리거나
+ * `main` 에 직접 push 한다. 둘 다 흔적이 안 남는다. **탈출구를 시스템 안에 두는
+ * 편이 낫다.** 보이고, 기록되고, 규칙으로 다듬을 수 있다.
+ *
+ * 남는 브레이크가 둘 있어서 이 구멍이 공짜 통과가 되지는 않는다.
+ *   · `main` 으로 가는 MR 은 `governance` 가 정족수를 요구한다 (표 없이는 못 간다)
+ *   · 브랜치 이름이 `hotfix/…` 라 diff 목록과 이력에 그대로 남는다
+ *
+ * 🔴 이름만 보고 판정한다 — 내용이 정말 긴급한지는 코드가 알 수 없다.
+ *    그 판단은 표를 던지는 사람의 몫이고, 여기서 하려 들면 못 하는 판정을
+ *    하는 척하게 된다.
+ *
+ * 규약에는 원래부터 있던 타입이다 — `docs/git-convention.md` 의
+ * *"`hotfix`: 운영 중인 `main`의 긴급 수정"*. 게이트만 그것을 몰랐다.
+ */
+function isHotfix(branch) {
+  return /^hotfix\//.test(branch)
+}
+
+/**
+ * 이 브랜치가 무엇인지 사람이 읽는 말로.
+ *
+ * `levelOf` 가 주는 `main`·`func`·`dev`·`null` 을 그대로 노출하지 않는 이유는
+ * `null` 이 "기능 브랜치" 라는 뜻인데 그 말이 어디에도 안 적혀 있어서다.
+ */
+export function describeBranch(branch) {
+  const name = String(branch ?? '').trim()
+  if (!name) return '이름 없음'
+  if (RESERVED.has(name)) return '도구 전용 브랜치'
+  switch (levelOf(name)) {
+    case 'main': return '최상위'
+    case 'func': return '파트 브랜치'
+    case 'dev': return '파트 개발 브랜치'
+    default: return '기능 브랜치'
+  }
+}
+
+/**
+ * 이 브랜치를 어디로 올릴 수 있나 — 사람이 읽는 한 줄.
+ *
+ * 목록이 아니라 문장인 이유: 기능 브랜치가 갈 수 있는 곳은 "존재하는 모든 파트의
+ * dev" 라 목록으로 적으려면 파트 목록을 알아야 하고, 그건 순수 판정이 알 수 없다.
+ */
+export function allowedTargetsOf(branch) {
+  const name = String(branch ?? '').trim()
+  if (RESERVED.has(name)) return '없다 — 도구가 직접 쓰는 브랜치라 MR 로 합치지 않는다'
+  switch (levelOf(name)) {
+    case 'main': return '없다 — 최상위가 종점이다'
+    case 'func':
+      return isNonProductPart(name)
+        ? '없다 — 이 파트에는 파트 브랜치 단계가 없다. `<파트>/dev` 에서 바로 올린다'
+        : '최상위 `main`'
+    case 'dev': {
+      // 제품이 아닌 파트는 파트 단계를 건너뛴다 — 갈 곳이 최상위뿐이다.
+      if (isNonProductPart(name)) return '최상위 `main` — 이 파트에는 파트 브랜치 단계가 없다'
+      const part = partOf(name)
+      return part ? `같은 파트의 \`${part}/main\` (= \`${part}/func\`)` : '같은 파트의 파트 브랜치'
+    }
+    default:
+      return isHotfix(name)
+        ? '`<파트>/dev`, 또는 `main` 이 그 자체로 고장 났다면 최상위 `main`'
+        : '`<파트>/dev` — 예: `front/dev` · `back/dev`'
+  }
+}
+
+/**
+ * 이 MR 이 한 칸씩 올라가는가.
+ *
+ * @param {string} source 합쳐 달라고 내미는 쪽 브랜치
+ * @param {string} target 합쳐 받는 쪽 브랜치
+ * @returns {{ok:boolean, exit:number, code:string, message:string, source?:string, target?:string}}
+ */
+export function checkTarget(source, target) {
+  const s = String(source ?? '').trim()
+  const t = String(target ?? '').trim()
+
+  // 🔴 이름을 못 받은 것은 통과가 아니다. 못 재면 막는다 — 락에서 최악은 조용한 통과다.
+  if (!s || !t) {
+    return {
+      ok: false,
+      exit: EXIT.UNDECIDABLE,
+      code: 'branch-unknown',
+      message:
+        '소스 또는 대상 브랜치 이름을 받지 못했습니다.\n' +
+        '  추측하지 않습니다 — 단계를 잘못 읽으면 막아야 할 MR 을 통과시킵니다.',
+    }
+  }
+
+  const bad = (code, message) => ({ ok: false, exit: EXIT.BLOCKED, code, message, source: s, target: t })
+  const good = (message) => ({ ok: true, exit: EXIT.OK, code: 'ok', message, source: s, target: t })
+
+  if (s === t) return bad('same-branch', '소스와 대상이 같은 브랜치입니다.')
+  if (RESERVED.has(s)) return bad('reserved-source', `\`${s}\` 는 도구가 직접 쓰는 브랜치라 MR 의 소스가 될 수 없습니다.`)
+  if (RESERVED.has(t)) return bad('reserved-target', `\`${t}\` 는 도구가 직접 쓰는 브랜치라 MR 의 대상이 될 수 없습니다.`)
+
+  const from = levelOf(s)
+  const to = levelOf(t)
+
+  // 기능 브랜치 → 파트 dev. 그리고 hotfix 만 최상위로도 갈 수 있다.
+  if (from === null) {
+    if (to === 'dev') return good('기능 브랜치 → 파트 개발 브랜치')
+    if (to === 'main' && isHotfix(s)) return good('긴급 수정 → 최상위 (사다리를 건너뛴다)')
+    return bad(
+      'feature-must-target-dev',
+      '기능 브랜치는 파트 개발 브랜치(`<파트>/dev`)로만 올립니다.\n' +
+        '  한 칸씩 올라가야 아래 관문을 지난 것만 위로 갑니다 — 건너뛰면 그 관문이 없는 것과 같습니다.\n' +
+        '  `main` 이 그 자체로 고장 났을 때만 `hotfix/…` 로 바로 올립니다.',
+    )
+  }
+
+  // 파트 dev → 같은 파트의 파트 브랜치.
+  if (from === 'dev') {
+    // 🔴 제품이 아닌 파트(`common` 등)에는 파트 브랜치 단계가 **없다.**
+    //
+    //    `<파트>/main` 의 뜻은 "이 파트의 릴리스 후보" 다. 릴리스할 제품이 없는
+    //    파트에는 그 자리가 비어 있고, 비어 있는 칸을 지나가라고 요구하면 사다리가
+    //    **막다른 길**이 된다 — 2026-08-27 에 실제로 그랬다. 팀 문서가 `common/dev`
+    //    까지 올라온 뒤, `common/main` 이 없어서 `main` 으로 갈 길이 사라졌다.
+    //    그래서 문서는 clone 하면 딸려오는 `main` 에 영영 못 들어갔다.
+    //
+    //    🔴 **통과가 늘어난다.** 그 대가를 알고 늘린다 — `main` 으로 가는 MR 은
+    //    `governance` 가 정족수를 요구하므로 표 없이는 여전히 못 간다.
+    //    사다리가 지키려던 것("아래 관문을 지난 것만 위로")은 그대로 있고,
+    //    없는 칸을 요구하지 않을 뿐이다.
+    if (isNonProductPart(s)) {
+      if (to === 'main') return good('제품이 아닌 파트의 개발 브랜치 → 최상위 (파트 단계가 없다)')
+      return bad(
+        'nonproduct-must-target-top',
+        `\`${partOf(s)}\` 는 제품 코드가 없는 파트라 **파트 브랜치 단계가 없습니다.**\n` +
+          '  문서·CI·공용 설정 자리이고, 버전도 갖지 않습니다.\n' +
+          '  최상위 `main` 으로 바로 올립니다.',
+      )
+    }
+    if (to !== 'func') {
+      return bad(
+        'dev-must-target-part',
+        `\`${s}\` 는 같은 파트의 파트 브랜치로만 올립니다.`,
+      )
+    }
+    const a = partOf(s)
+    const b = partOf(t)
+    // 🔴 파트를 대조하지 않으면 `front/dev → back/main` 이 통과한다.
+    //    프론트에서 검토된 적 없는 코드가 백엔드 파트의 릴리스 후보로 들어간다.
+    if (a === null || b === null || a !== b) {
+      return bad(
+        'part-mismatch',
+        `파트가 다릅니다 — \`${a ?? '?'}\` 에서 \`${b ?? '?'}\` 로 건너뛸 수 없습니다.`,
+      )
+    }
+    return good('파트 개발 브랜치 → 같은 파트의 파트 브랜치')
+  }
+
+  // 파트 브랜치 → 최상위.
+  if (from === 'func') {
+    // 🔴 제품이 아닌 파트에 파트 브랜치가 있다는 것 자체가 실수다. 막고 알린다 —
+    //    조용히 통과시키면 `common/main` 이 다시 생기고, 그 브랜치는 아무도
+    //    무엇에 쓰는지 모른 채 사다리 한 칸을 더 만든다.
+    if (isNonProductPart(s)) {
+      return bad(
+        'nonproduct-has-no-part-branch',
+        `\`${s}\` 는 만들지 않습니다 — \`${partOf(s)}\` 에는 파트 브랜치 단계가 없습니다.\n` +
+          '  `<파트>/dev` 에서 최상위 `main` 으로 바로 올립니다.',
+      )
+    }
+    if (to === 'main') return good('파트 브랜치 → 최상위')
+    return bad('part-must-target-main', `\`${s}\` 는 최상위 \`main\` 으로만 올립니다.`)
+  }
+
+  // 최상위에서 나가는 MR 은 없다.
+  return bad('top-is-terminal', '최상위 `main` 은 종점입니다. 여기서 나가는 MR 은 없습니다.')
+}
+
+/**
+ * 사람과 에이전트가 함께 읽는 출력.
+ *
+ * 메시지를 순수 로직에 두는 것은 이 저장소의 관례다 (`protocol.mjs` 의
+ * `formatBlocks`, `governance.mjs` 의 `formatVerdict`). 덕분에 **"거부당했을 때
+ * 어디로 가야 하는지가 출력에 있는가" 를 테스트로 고정할 수 있다.**
+ */
+export function formatCheck(result) {
+  const L = []
+  if (result.exit === EXIT.UNDECIDABLE) {
+    L.push('MR 대상 검사 불가 — 브랜치 이름을 읽지 못했습니다.')
+    L.push('')
+    L.push(`  ${result.message.split('\n').join('\n  ')}`)
+    L.push('')
+    L.push('환경 문제입니다. 대상 브랜치를 바꿔도 풀리지 않습니다.')
+    return L.join('\n')
+  }
+
+  const { source, target } = result
+  if (result.ok) {
+    L.push(`MR 대상 통과 — ${result.message}`)
+    L.push(`  ${source} → ${target}`)
+    return L.join('\n')
+  }
+
+  L.push('MR 대상 거부 — 한 칸씩만 올라갑니다.')
+  L.push('')
+  L.push(`  올린 곳   : ${source} (${describeBranch(source)})`)
+  L.push(`  올린 대상 : ${target} (${describeBranch(target)})`)
+  L.push('')
+  L.push(`  ${result.message.split('\n').join('\n  ')}`)
+  L.push('')
+  // 🔴 거부하면서 **갈 수 있는 곳을 함께 말한다.** 선점 프로토콜이 거부할 때
+  //    점유자·작업·남은 시간을 함께 주는 것과 같은 규칙이다 — 이유 없는 거부는
+  //    같은 요청을 다시 보내게 만든다.
+  L.push(`  \`${source}\` 가 갈 수 있는 곳: ${allowedTargetsOf(source)}`)
+  L.push('')
+  L.push('MR 의 대상 브랜치를 바꾸고 다시 여세요. 코드를 고칠 일이 아닙니다.')
+  return L.join('\n')
+}

package/src/promote.mjs

@@ -0,0 +1,177 @@
+/**
+ * 승격(**promotion** — 아래 단계 브랜치에 쌓인 것을 위 단계로 올리는 것) **계획**.
+ *
+ * 순수 판정만 둔다. git 도 네트워크도 시계도 여기 없다 (`tools/promote.mjs` 가 담당).
+ * 이 저장소가 `src/version.mjs` 와 `tools/version.mjs` 를 가른 것과 같은 이유다 —
+ * 하루를 기다리지 않고 "오늘 봇이 무엇을 올릴 것인가" 를 검증할 수 있어야 한다.
+ *
+ * 봇이 도는 주기는 둘이다.
+ *
+ *   dev-to-part   `<파트>/dev`  → `<파트>/main` (= `<파트>/func`)   하루 한 번
+ *   part-to-main  `<파트>/main` → 최상위 `main`                      주 한 번
+ *
+ * ── 왜 짝짓기 규칙을 여기서 새로 만들지 않는가 ────────────────────────────────
+ *
+ * 🔴 만든 짝은 **전부 `checkTarget`(src/mrtarget.mjs)을 지난다.** 여기서 "dev 는
+ *    같은 파트의 main 으로" 를 다시 적으면 한 저장소에 브랜치 규칙이 둘이 되고,
+ *    그러면 **사람이 연 MR 은 막히는데 봇이 연 MR 은 통과하는** 조합이 생긴다.
+ *    봇이 자기 규칙의 예외가 되는 순간 그 규칙은 규칙이 아니다.
+ *
+ *    같은 이유로 단계 판정도 `levelOf`(src/version.mjs) 를 가져다 쓴다.
+ *    `back/main` 이 최상위인지 파트인지를 버전 자동화와 봇이 서로 다르게 답하면
+ *    안 된다.
+ *
+ * 도구 전용 브랜치(`axmap/claims`·`axmap/votes`)를 여기서 따로 걸러내지 않는 것도
+ * 같은 맥락이다. `checkTarget` 이 이미 막는다 — 두 군데서 막으면 한쪽을 고칠 때
+ * 다른 쪽이 남아 "고쳤는데 안 바뀐다" 가 된다.
+ */
+
+import { levelOf } from './version.mjs'
+import { checkTarget, partOf } from './mrtarget.mjs'
+
+/** 봇이 도는 주기. 문자열을 코드 여기저기에 흩지 않는다. */
+export const STEPS = ['dev-to-part', 'part-to-main']
+
+/** 사람이 읽는 주기 이름. 로그의 첫 줄이 된다. */
+export function describeStep(step) {
+  switch (step) {
+    case 'dev-to-part': return '파트 개발 브랜치 → 파트 브랜치 (하루 한 번)'
+    case 'part-to-main': return '파트 브랜치 → 최상위 main (주 한 번)'
+    default: return '알 수 없는 주기'
+  }
+}
+
+/** 최상위 브랜치 이름은 저장소마다 다르다 (`main` · `master`). 목록에서 고른다. */
+function topBranchOf(list) {
+  if (list.includes('main')) return 'main'
+  if (list.includes('master')) return 'master'
+  return null
+}
+
+/**
+ * 브랜치 이름 목록을 다듬는다. 공백·중복·비문자열을 버린다.
+ *
+ * 버리는 것을 `skipped` 에 적지 않는 이유: 여기서 걸러지는 것은 "브랜치가 아닌 것"
+ * 이지 "승격 후보였는데 떨어진 것" 이 아니다. 둘을 한 목록에 담으면 사람이
+ * 건너뛴 이유를 읽으러 왔다가 잡음부터 읽게 된다.
+ */
+function cleanBranches(branches) {
+  const out = []
+  const seen = new Set()
+  for (const b of branches ?? []) {
+    if (typeof b !== 'string') continue
+    const name = b.trim()
+    if (!name || seen.has(name)) continue
+    seen.add(name)
+    out.push(name)
+  }
+  return out.sort()
+}
+
+/**
+ * 이번 주기에 올릴 짝을 만든다.
+ *
+ * @param {string[]} branches 저장소에 **실제로 있는** 브랜치 이름 목록
+ * @param {{step: string}} opts 주기
+ * @returns {{step:string, pairs:Array<{source:string,target:string,reason:string}>,
+ *            skipped:Array<{source:string,target:string|null,code:string,reason:string}>}}
+ *
+ * 🔴 `pairs` 만 보고 실행하면 안 되는 이유가 `skipped` 에 있다. "오늘 back 은 왜
+ *    안 올라갔나" 의 답이 거기 들어 있고, 그 답이 없으면 사람이 봇을 의심하는 대신
+ *    자기 브랜치를 의심한다.
+ */
+export function planPromotions(branches, { step } = {}) {
+  if (!STEPS.includes(step)) {
+    throw new Error(
+      `알 수 없는 승격 주기: ${step}\n`
+      + `  쓸 수 있는 것: ${STEPS.join(' | ')}`,
+    )
+  }
+
+  const list = cleanBranches(branches)
+  const pairs = []
+  const skipped = []
+  const exists = new Set(list)
+
+  const drop = (source, target, code, reason) => skipped.push({ source, target, code, reason })
+
+  /** 짝을 넣기 전에 반드시 여기를 지난다. 봇도 사람과 같은 문을 쓴다. */
+  const accept = (source, target, reason) => {
+    const verdict = checkTarget(source, target)
+    if (!verdict.ok) {
+      drop(source, target, `blocked:${verdict.code}`,
+        `브랜치 규칙이 막았습니다 — ${verdict.message.split('\n')[0]}`)
+      return
+    }
+    pairs.push({ source, target, reason })
+  }
+
+  if (step === 'dev-to-part') {
+    for (const source of list) {
+      if (levelOf(source) !== 'dev') continue
+      const part = partOf(source)
+      if (!part) {
+        drop(source, null, 'no-part',
+          '파트를 읽을 수 없습니다 — `<파트>/dev` 처럼 앞에 파트 이름이 있어야 합니다.')
+        continue
+      }
+      // 팀 컨벤션은 `<파트>/main` 이고 `<파트>/func` 도 같게 친다 (levelOf 가 둘 다
+      // func 으로 읽는다). 둘 다 있으면 main 쪽으로 올린다 — 컨벤션에 적힌 이름이
+      // 그쪽이고, 둘로 갈라 올리면 같은 코드가 두 릴리스 후보에 각각 들어간다.
+      const main = `${part}/main`
+      const func = `${part}/func`
+      const target = exists.has(main) ? main : (exists.has(func) ? func : null)
+      if (!target) {
+        drop(source, null, 'no-target',
+          `올릴 곳이 없습니다 — \`${main}\` 도 \`${func}\` 도 아직 없습니다.`)
+        continue
+      }
+      if (target === main && exists.has(func)) {
+        drop(source, func, 'duplicate-target',
+          `\`${main}\` 과 \`${func}\` 이 둘 다 있어 \`${main}\` 쪽으로만 올립니다.`)
+      }
+      accept(source, target, `${part} 파트의 하루치`)
+    }
+    return { step, pairs, skipped }
+  }
+
+  // part-to-main
+  const top = topBranchOf(list)
+  for (const source of list) {
+    if (levelOf(source) !== 'func') continue
+    if (!top) {
+      drop(source, null, 'no-top-main',
+        '최상위 `main` 이 목록에 없습니다 — 올릴 곳을 추측하지 않습니다.')
+      continue
+    }
+    accept(source, top, `${partOf(source) ?? source} 파트의 한 주치`)
+  }
+  return { step, pairs, skipped }
+}
+
+/**
+ * 사람과 에이전트가 함께 읽는 계획표.
+ *
+ * 메시지 생성을 순수 로직에 두는 것은 이 저장소의 관례다 (`formatCheck`,
+ * `formatVerdict`). 덕분에 **"건너뛴 이유가 출력에 남는가" 를 테스트로 고정할 수
+ * 있다** — 그 줄을 지우면 테스트가 빨개진다.
+ */
+export function formatPlan(plan) {
+  const L = []
+  L.push(`승격 계획 — ${describeStep(plan.step)}`)
+  L.push('')
+  if (plan.pairs.length === 0) {
+    L.push('  올릴 짝이 없습니다.')
+  } else {
+    for (const p of plan.pairs) L.push(`  o ${p.source} -> ${p.target}   (${p.reason})`)
+  }
+  if (plan.skipped.length) {
+    L.push('')
+    L.push('  건너뛴 것')
+    for (const s of plan.skipped) {
+      const where = s.target ? `${s.source} -> ${s.target}` : s.source
+      L.push(`    - ${where}  [${s.code}] ${s.reason}`)
+    }
+  }
+  return L.join('\n')
+}