axmap-cli 0.0.1

package/.claude/commands/ax-done.md

@@ -0,0 +1,10 @@
+---
+description: axMap — 작업을 마치고 반납한다
+---
+
+1. 지금 잡고 있는 것을 `ax_status` 로 확인
+2. 작업이 정말 끝났으면 `ax_release`
+3. 반납 결과를 확인한다 — **아무것도 반납되지 않았다고 나오면 그냥 넘어가지 마라.**
+   잡을 때와 이름이 다르다는 뜻이고, 그동안 다른 사람은 최대 TTL 만큼 헛되이 기다린다.
+
+아직 안 끝났고 시간이 더 필요하면 `ax_release` 대신 `ax_renew` 를 부른다.

package/.claude/commands/ax-setup.md

@@ -0,0 +1,31 @@
+---
+description: axMap — 이 저장소에 axMap 을 붙인다 (내 git 주소를 넣어 초기화)
+---
+
+이 저장소에서 axMap 선점을 쓸 수 있게 만들어줘.
+장부(누가 무엇을 잡고 있는지 적는 곳)를 둘 git 주소: $ARGUMENTS
+
+1. 지금 폴더가 git 저장소인지 먼저 본다. 아니면 **여기서 멈추고** 사람에게 알린다.
+   axMap 의 장부와 쪽지는 git 의 고아 브랜치로 오간다 — 저장소가 없으면 claim 이
+   아무에게도 안 가면서 조용히 성공한다.
+
+2. Bash 로 아래를 실행한다.
+
+       npx -y axmap-cli@latest setup --remote $ARGUMENTS
+
+   주소를 안 줬으면 `--remote` 째로 빼고 부른다. 그러면 이 저장소의 원격을
+   그대로 쓴다 (하나면 그것, `origin` 이 있으면 `origin`).
+
+   먼저 무엇이 바뀔지만 보고 싶으면 `--dry-run` 을 붙인다. 아무것도 쓰지 않는다.
+
+3. 종료 코드로 판정한다. **출력만 보고 됐다고 하지 마라.**
+   `0` 다 됐다 · `1` 시작조차 못 했다 · `2` 일부만 됐다 (`!!` 줄을 그대로 옮긴다)
+
+4. 끝나면 사람에게 이 두 줄을 전한다.
+   - AI CLI 를 **완전히 껐다가 다시 켜야** MCP 도구(`ax_*`)가 뜬다
+   - 그 뒤 `/ax-start` 로 시작하면 된다
+
+이미 붙어 있는 저장소라면 `setup` 을 다시 부르지 않고 `ax_status` 로 확인만 한다 —
+`setup` 은 몇 번 돌려도 안전하지만, 이미 되는 것을 다시 설치하는 것은 시간 낭비다.
+
+같은 주소를 넣은 사람끼리 서로의 선점이 보인다. 그게 이 명령이 하는 일의 전부다.

package/.claude/commands/ax-start.md

@@ -0,0 +1,15 @@
+---
+description: axMap — 이 저장소에서 일을 시작한다 (브리핑 → 장부 확인 → 선점)
+---
+
+이 순서로 해줘.
+
+1. `ax_brief` — 이 저장소가 무엇인지, 이미 내려진 결정이 무엇인지 읽는다
+2. `ax_inbox` — 나에게 온 쪽지가 있는지 본다
+3. `ax_status` — 지금 누가 무엇을 잡고 있는지 본다
+4. 내가 할 일: $ARGUMENTS
+   그 일에 필요한 경로를 **좁게** 골라 `ax_claim` 한다.
+   `intent` 에는 사람이 읽을 한 문장을 적는다 — 팀원이 화면에서 그걸 본다.
+
+장부가 없다고 하면 `ax_init` 을 먼저 부른다.
+claim 이 거부되면(겹침) 재시도하지 말고 겹치지 않는 다른 작업을 제안한다.

package/.claude/commands/ax-tell.md

@@ -0,0 +1,14 @@
+---
+description: axMap — 다른 에이전트/팀원에게 쪽지를 보낸다
+---
+
+`ax_send` 로 쪽지를 보내줘. 내용: $ARGUMENTS
+
+**상대가 알아야 결정이 달라지는 것**만 보낸다 — 레인 배정, 방향 전환,
+상대 코드에서 찾은 결함 같은 것. 진행 상황 중계는 보내지 않는다.
+
+쪽지는 고아 브랜치(`axmap/bus`)로 **바로 간다** — 커밋도 MR 도 필요 없고,
+상대는 아무 axMap 도구를 부르든 결과 끝에서 본다.
+
+지금 잡고 있는 것과 왜 잡았는지는 쪽지 말고 `ax_claim` 의 `intent` 에 적는다.
+그건 `ax_status` 로 언제든 보이고, 쪽지처럼 한 번 읽고 넘어가는 것이 아니다.

package/.claude/commands/ax-update.md

@@ -0,0 +1,19 @@
+---
+description: axMap — 새 버전이 나왔는지 보고, 받을지는 사람이 정한다
+---
+
+1. Bash 로 `npx -y axmap-cli@latest update` 를 실행한다.
+   지금 버전과 최신 버전을 나란히 찍는다. **이 명령은 아무것도 갈아치우지 않는다.**
+
+2. 새 버전이 있으면 사람에게 **묻고**, 받으라고 하면 그때 아래를 실행한다.
+
+       npx -y axmap-cli@latest setup
+
+   🔴 묻지 않고 실행하지 마라. 도구가 사람이 모르는 사이에 바뀌면 어제 되던 것이
+   오늘 안 되고, 바뀐 것이 자기 코드가 아니라서 원인을 찾을 실마리가 없다.
+
+3. 종료 코드가 `1` 이면 **확인 자체를 못 한 것**이다 (네트워크, 또는 아직 배포된
+   적이 없는 꾸러미). "최신입니다" 로 옮기지 마라 — 모르는 것과 최신인 것은 다르다.
+
+팀 저장소 안의 `ci/axmap/` 사본에서 이 명령을 부르면 "사본입니다" 라고 답한다.
+그건 정상이다. 사본은 npm 이 아니라 axMap 저장소의 `tools/vendor.mjs` 로 갱신한다.

package/.claude/commands/ax.md

@@ -0,0 +1,13 @@
+---
+description: axMap — 지금 누가 어디를 잡고 있는지 보고, 내가 건드릴 곳이 비었는지 확인한다
+---
+
+`ax_status` 를 불러 지금 장부에 무엇이 들어 있는지 보여줘.
+
+그 다음 이번 대화에서 내가 건드릴 것으로 보이는 경로에 대해 `ax_check` 를 불러
+겹치는 것이 있는지 확인하고, 결과를 한 문단으로 정리해줘.
+
+겹치는 것이 있으면 **재시도하지 말고** 비어 있는 다른 영역을 제안해.
+같은 요청은 몇 번을 보내도 같은 답이 온다.
+
+$ARGUMENTS

package/CLAUDE.md

@@ -0,0 +1,309 @@
+# axMap 작업 규칙 — `axmap/` 안에서 일할 때
+
+이 문서는 **axMap 자체를 고칠 때** 지키는 규칙이다.
+팀 프로젝트 전체의 규칙은 저장소 루트의 [CLAUDE.md](../CLAUDE.md) 에 있다.
+
+axMap 은 **AI Experience(ax) 의 지도**다 — 에이전트가 코드베이스에서 길을 찾고
+서로를 피해 가는 경험을 만든다. 이 팀에서는 여행 서비스를 만드는 **도구**로 쓰인다.
+
+> **산문에서는 `axMap`, 식별자·명령·경로·패키지 이름에서는 `axmap`.**
+> 다만 **MCP 도구 이름만 `ax_` 접두사**를 쓴다 (`ax_claim`, `ax_status` …).
+> 에이전트가 하루에 수십 번 부르는 이름이라 짧은 쪽이 낫고, 그 이름들은
+> 도구 목록에서 이미 `axmap` 서버 아래에 묶여 있어 헷갈릴 자리가 없다.
+> 환경변수 접두사는 `AXMAP_`, 장부 브랜치는 `axmap/claims` 다.
+
+---
+
+## 0. 먼저 — `axmap` 명령을 만든다
+
+이 저장소는 npm 에 올라가 있지 않다. **아래를 하기 전에는 `axmap` 이 없다.**
+
+```bash
+alias axmap='node "$(git rev-parse --show-toplevel)/axmap/bin/axmap.mjs"'   # bash/zsh
+```
+
+```powershell
+function axmap { node "$(git rev-parse --show-toplevel)\axmap\bin\axmap.mjs" @args }   # PowerShell
+```
+
+한 번만 쓸 거면 그냥 `node axmap/bin/axmap.mjs <명령>` 이라고 친다.
+아래 문서는 전부 `axmap` 으로 적혀 있고, 그건 위 별칭을 전제한다.
+
+## 0.5. 이 저장소가 처음이면 — 브리핑부터 받는다
+
+```
+ax_brief          # MCP 도구. 인자 없음
+```
+
+무엇을 만드는 프로젝트인지, **이미 내려진 결정이 무엇인지**, 어떤 파일이 무슨 일을
+하는지, 끝내기 전에 무엇을 통과해야 하는지를 한 번에 준다.
+
+MCP 를 못 쓰는 환경이면 같은 내용을 이 순서로 읽는다.
+
+| | |
+|---|---|
+| `axmap/docs/DECISIONS.md` | 제품 방향과 **버린 대안** |
+| `axmap/docs/THREADS.md` | **열려 있는 갈래** — 상태 · 다음 한 걸음 |
+| `axmap/docs/SPEC.md` | 규격. 코드보다 이쪽이 먼저다 |
+| `axmap/docs/INVARIANTS.md` | 지켜야 할 성질 |
+| `axmap/docs/BENCH.md` | 무엇을 재는가 — M3 도달 호출 번호가 주 지표다 |
+
+> 번호(`D1~D18` · `I1~I7`)를 이 표에 적지 않는다. 하나 늘릴 때마다 이 줄이 낡고,
+> 낡은 기준은 없는 기준보다 나쁘다. 실제로 I8 을 넣고 이 줄을 놓쳤다.
+
+`THREADS.md` 가 `DECISIONS.md` 의 **열린 쪽 짝**이다. 저쪽이 "이미 정한 것" 이라
+*"왜 아직 안 했나"* 와 *"다음 한 걸음"* 은 어디에도 안 남는데, 이어받는 사람이 제일
+먼저 묻는 것이 그것이다. 바로 아래 "지도를 따로 적지 않는다" 규칙과 부딪히지 않는다 —
+그 규칙이 막는 것은 **코드에서 다시 읽어낼 수 있는 것**을 베껴 적는 일이고,
+열려 있는 갈래는 코드 어디에도 없다.
+
+🔴 **브리핑의 내용은 이 문서들과 각 파일의 머리말 주석에서 그때그때 읽어온다.**
+어딘가에 지도를 따로 적어 두지 않는다. 손으로 적은 지도는 코드보다 먼저 낡고,
+낡은 지도는 없는 지도보다 나쁘다 — 새로 온 사람이 그것을 믿고 엉뚱한 곳을 고친다.
+
+그래서 아래 "주석은 왜를 쓴다" 규칙은 **취향이 아니라 인수인계 장치**다.
+파일 맨 위 블록 주석의 첫 문장이 그대로 코드 지도의 한 줄이 된다.
+새 모듈을 만들면 머리말을 반드시 쓰고, 필요하면 `axmap/mcp/server.mjs` 의 `MAP` 에 경로를 더한다.
+
+---
+
+## 1. 코드를 건드리기 전에 선점한다
+
+```bash
+export AXMAP_AGENT=<내-이름>        # 세션마다 고유하게
+
+axmap claim <경로...> --task <작업ID> --intent "<한 줄 설명>"
+```
+
+> 셸이 바뀌면 `AXMAP_AGENT` 도 사라진다. claim 과 커밋을 다른 셸에서 하면
+> 훅이 당신을 **다른 사람으로 보고 커밋을 막는다.** 커밋할 때도 같은 값을 준다:
+> `AXMAP_AGENT=<내-이름> git commit`
+
+**어떤 파일이든 수정하기 전에 claim 이 먼저다.** 읽기만 할 때는 필요 없다.
+
+작업 범위가 확실치 않으면 **넓게 잡지 말고 좁게 시작해서 추가로 claim** 한다.
+`claim` 은 누적되므로 나중에 경로를 더할 수 있다. 넓게 잡으면 남의 작업을 헛되이 막는다.
+
+## 2. 거부당하면 재시도하지 말고 방향을 바꾼다
+
+| 종료 코드 | 의미 | 할 일 |
+|---|---|---|
+| 2 | 경로가 겹침 | **다른 작업으로 전환.** 재시도해도 결과는 같다 |
+| 3 | claim 없이 커밋 시도 | 해당 경로를 claim 하거나 스테이징에서 뺀다 |
+| 1 | 환경 오류 / 경합 과다 | 메시지를 읽고 고친다 |
+| 5 | `release` 가 **아무것도 반납 못 함** | 잡을 때와 이름이 다르다. `AXMAP_AGENT` 를 확인한다 |
+
+**5 를 무시하지 않는다.** 반납했다고 믿는데 락이 남아 있다는 뜻이고,
+그동안 다른 에이전트는 최대 30분을 헛되이 기다린다.
+두 대로 협업하다 실제로 물렸다 — claim 은 `AXMAP_AGENT=X` 로 했는데
+release 를 그 변수가 없는 셸에서 불러 `git config user.name` 으로 떨어졌다.
+메시지가 **이름이 어디서 왔는지** 알려주므로 그것부터 읽는다.
+
+종료 코드 2 의 메시지에는 점유자, 작업 ID, 남은 TTL 이 들어 있다.
+그것을 읽고 **비어 있는 다른 영역**을 찾는다. `axmap status --json` 으로 전체를 볼 수 있다.
+
+사람의 판단이 필요하면 기다리지 말고 물어본다. TTL 만료를 기다리며 놀지 않는다.
+
+## 3. 오래 걸리면 갱신하고, 끝나면 반납한다
+
+```bash
+axmap renew      # 기본 TTL 30분. 넘어갈 것 같으면 미리
+axmap release    # 작업이 끝나면 즉시
+```
+
+반납하지 않아도 TTL 이 지나면 자동으로 풀린다. 그래도 **끝나면 바로 반납한다.**
+다른 에이전트가 30분을 헛되이 기다리게 하지 않기 위해서다.
+
+## 4. 훅을 설치한다
+
+```bash
+axmap hook install
+```
+
+claim 하지 않은 파일의 커밋을 막는다. 이것이 없으면 프로토콜은 권고 사항에 불과하다.
+
+---
+
+## 5. 일하는 방식 — 코드를 쓰기 전에 지키는 것
+
+> 🔴 **이 절은 원래 `~/.claude/CLAUDE.md`(그 PC 의 전역 설정)에만 있었다.**
+> 그래서 **다른 컴퓨터에서 이어받으면 조용히 사라졌다** — 없어도 에러가 안 나고,
+> 그냥 에이전트가 다르게 일한다. 저장소에 없는 것이 다른 곳에서 다르게 동작하는
+> 것은 이 프로젝트가 반복해서 겪은 사고 모양이라(`.env` · `data/` · 러너),
+> 여기로 옮긴다. 2026-08-27.
+>
+> 전역 파일에도 같은 내용이 남아 있다. **이 저장소에서는 이쪽이 기준이고**,
+> 둘이 갈라지면 이쪽을 따른다.
+
+### 5.1. 코딩 전에 먼저 생각한다
+
+- **가정하지 않는다.** 불확실한 부분은 숨기지 말고 표면으로 드러낸다
+- **해석이 여러 가지면** 각각을 명시하고 어느 쪽인지 확인한다
+- **혼란스러우면 묻는다.** 잘못된 가정으로 구현한 뒤 되돌리는 것보다 먼저 묻는 게 싸다
+- **더 나은 방법이 있으면 제안한다.** 요청이 최선이 아닐 때는 트레이드오프를 설명한다
+
+### 5.2. 단순함이 먼저다
+
+문제를 해결하는 **최소한의 코드**만 쓴다. 금지: 요청하지 않은 기능 · 미래를 위한
+추상화 · 발생 불가능한 에러 핸들링 · 불필요한 유연성.
+
+자가 점검은 한 문장이다 — *"시니어 엔지니어가 이걸 보고 과하다고 할까?"*
+
+### 5.3. 외과적으로 바꾼다
+
+**반드시 바꿔야 할 것만** 건드린다. 내가 만든 mess 만 정리하고, 주변 코드 스타일
+개선이나 고장나지 않은 코드의 리팩토링은 하지 않는다.
+**변경된 모든 줄은 사용자 요청으로 직접 추적 가능해야 한다.**
+
+> 이 규칙이 이 저장소에서 특히 중요한 이유가 있다. `checkOverlap` 주변을 "겸사겸사"
+> 정리하다 판정이 한 칸 넓어지면, 그 순간부터 **두 에이전트가 같은 파일을 잡고도
+> 아무 경고가 안 난다.** 락 시스템에서 조용한 통과가 최악인 것과 같은 이유다.
+
+### 5.4. 목표를 검증 가능한 것으로 바꾼다
+
+추상적인 태스크를 **검증 가능한 체크포인트**로 만든다.
+**성공 기준을 먼저 정의하고, 검증 방법 없이 구현하지 않는다.**
+
+이 저장소에서 그 기준은 언제나 **종료 코드**다. 개수도 문장도 아니다.
+
+### 5.5. 확인은 긴 글이 아니라 선택지로
+
+사용자는 **긴 프롬프트를 건너뛸 수 있다.** 확인·결정이 필요하면 장문 설명 대신
+**선택지(`AskUserQuestion`)** 로 제시한다.
+
+**새로 무언가를 만들어 남기기 전에는**(설계 문서 · 티켓 · 산출물) 무엇을 만들지
+선택지로 컨펌받고 진행한다. 설명이 꼭 필요하면 짧게, 결정 포인트는 항상 선택지로.
+
+### 5.6. 용어는 쓰기 전에 뜻을 붙인다
+
+**처음 쓰는 용어에는 괄호로 한 줄 뜻을 붙인다.**
+`claim(파일 예약 — 건드리기 전에 자리를 잡아두는 것)`
+
+사용자가 **"그게 뭐야" 를 묻게 만들면 실패다.** 직접 찾아보는 것이 대화로 듣는 것보다
+훨씬 힘들다. **설명 비용은 말하는 쪽이 낸다.**
+
+🔴 **저장소 문서(SPEC · DECISIONS · README)에 있는 용어라도 예외 없다.**
+문서에 적혀 있다는 것이 상대가 안다는 뜻이 아니다.
+뜻 없이 쓴 용어가 한 답변에 셋 이상이면 답변 끝에 용어 표를 붙인다.
+이미 사용자가 쓴 적 있는 단어는 그대로 쓴다 — 아는 말까지 설명하면 그것도 소음이다.
+
+> 이 규칙은 [docs/WORDS.md](docs/WORDS.md) 원칙 B(*"전문 용어는 지우지 말고 괄호로
+> 뒤에 붙인다 — 어휘를 뺏지 않고 가르친다"*)와 같은 것이다.
+> **제품 화면에 적용하기로 한 규칙을 대화에도 똑같이 적용한다.**
+> 팀 저장소는 이것을 자기 `CLAUDE.md` 0절로 가져갔다.
+
+---
+
+### 5.7. 한 번에 두 가지만 설명하고, 따라오는지 확인한다
+
+🔴 **한 답변에 설명은 최대 두 가지.** 셋째부터는 꺼내지 않는다.
+끝에 **"다음 것도 설명할까요?"** 를 붙인다. 선택지로 물어도 된다.
+
+**왜 이 규칙이 생겼나.** 길게 쓰면서 동시에 압축하려 하면 **둘 다 실패한다.**
+밀도만 올라가고 읽는 사람은 따라갈 수가 없다. 사용자의 말 그대로다 —
+*"요약을 엄청 길게 해주면서 어느 정도 축약을 하려고 하다 보니 이해하기가 더 힘들다."*
+
+**작업 보고에도 똑같이 적용한다.** 한 일이 열 개여도 **제일 중요한 둘**만 쓰고
+나머지는 물어본다. 다 적어야 성실한 것이 아니다 — 안 읽히면 안 적은 것과 같다.
+
+> 5.6(용어에 뜻을 붙인다)과 짝이다. 저쪽은 **모르는 단어**를 막고
+> 이쪽은 **한꺼번에 너무 많은 것**을 막는다. 둘 다 *"읽는 사람이 검색하러
+> 나가거나 포기하는 순간 그 글은 실패"* 라는 같은 판정 기준에서 나왔다.
+
+---
+
+## 코드 규칙
+
+### 의존성을 추가하지 않는다
+
+Node 20+ 와 git 만으로 돌아간다. 테스트도 `node:test` 내장 러너를 쓴다.
+새 의존성이 필요하다고 판단되면 **추가하기 전에 사람에게 묻는다.**
+
+`package.json` 은 claim 없이 건드리지 않는다. 모든 에이전트의 공유 경로다.
+
+### 순수 로직과 부수효과를 섞지 않는다
+
+| 파일 | 넣는 것 | 넣지 않는 것 |
+|---|---|---|
+| `axmap/src/protocol.mjs` | 판정, 계산, 메시지 생성 | git 호출, 파일 I/O, `Date.now()` |
+| `axmap/bin/axmap.mjs` | git, fs, 시계, 인자 파싱 | 판정 로직 |
+
+시각은 항상 인자로 받는다. `checkOverlap({..., now})` 처럼.
+그래야 TTL 동작을 30분 기다리지 않고 검증할 수 있다.
+
+### 애매하면 거부한다 (fail-closed)
+
+락 시스템에서 최악의 실패는 거부해야 할 것을 조용히 통과시키는 것이다.
+잘못 막으면 에이전트가 메시지를 읽고 방향을 틀면 그만이지만,
+못 막으면 두 에이전트가 같은 코드를 고치고 아무도 에러를 보지 못한다.
+
+- 장부 레코드를 파싱할 수 없으면 **건너뛰지 말고 전체를 중단**한다.
+- 이상한 입력을 **안전한 값으로 치환하지 말고 거부**한다.
+  치환은 서로 다른 두 입력을 같은 것으로 만들고, 그것이 곧 소유권 충돌이다.
+- 만료된 레코드를 **효력이 있는 것처럼 다루지 않는다.**
+  만료는 레코드가 사라지는 것이 아니라 효력만 잃는 것이다.
+
+`checkOverlap` 주변을 고칠 때는 "이 변경으로 통과가 늘어나는가"를 먼저 확인한다.
+늘어난다면 그것이 의도한 것인지 근거를 남긴다.
+
+### 프로토콜 로직을 바꾸면 테스트를 함께 바꾼다
+
+`axmap/test/protocol.test.mjs` 의 다음 테스트는 **설계 근거 자체**다. 이유 없이 지우지 않는다.
+
+> `Case 1 과 Case 2 는 반드시 같은 답이어야 한다`
+
+무관한 제3자의 데이터가 판정을 바꾸지 못하도록 고정하는 테스트다.
+git 의 텍스트 충돌 대신 파서를 고른 이유 전체가 여기 들어 있다.
+배경은 [docs/EXPERIMENT.md](docs/EXPERIMENT.md).
+
+### 명령을 추가하거나 claim 의미론을 바꾸면 SPEC 을 먼저 고친다
+
+[docs/SPEC.md](docs/SPEC.md) 가 규격이고 코드가 구현이다. 순서를 지킨다.
+여섯 명이 병렬로 붙는 상황에서 규격이 코드를 따라가면 아무도 진실을 모르게 된다.
+
+### 주석은 "왜"를 쓴다
+
+"무엇"은 코드가 이미 말한다. 주석에는 그 선택을 한 이유를 남긴다.
+특히 git 의 비직관적인 동작(worktree 별 `FETCH_HEAD`, 훅의 `GIT_*` 환경변수 등)은
+반드시 이유를 적는다. 다음 사람이 반드시 다시 밟는다.
+
+---
+
+## 검증
+
+작업을 끝내기 전에 전부 통과해야 한다.
+
+```bash
+npm --prefix axmap test               # 회귀 테스트 + 모델 검증기 - 전부 통과 (실패 0)
+npm --prefix axmap run demo           # 에이전트 9명 동시 작업 - 8개 섹션 전부 정상
+npm --prefix axmap run demo:compare   # git 판정 vs 파서 판정 - 파서가 3/3
+npm --prefix axmap run demo:chaos     # 카오스 테스트 - I1·I3·I4·I5 전부 통과, exit 0
+npm --prefix axmap run smoke          # 화면이 실제로 뜨는지 - 헤드리스 크롬, exit 0
+npm --prefix axmap run desktop:smoke  # 데스크톱 셸 - 창이 뜨고 정지 후 초당 그리기 25회 이하, exit 0
+```
+
+> 개수를 여기에 적지 않는다. 적어 두면 테스트를 늘릴 때마다 이 줄이 낡고,
+> 낡은 기준은 **없는 기준보다 나쁘다** — 다음 사람이 그것을 믿고 통과했다고 여긴다.
+> 판정은 언제나 종료 코드다.
+
+**`axmap/app/web/` 를 건드렸으면 `npm --prefix axmap run smoke` 를 반드시 돌린다.**
+`npm --prefix axmap test` 는 브라우저 코드를 실행하지 않으므로 **화면이 죽어도 초록이다.**
+하룻밤에 두 번 겪었다 — 주석 안의 `*/` 가 파일을 닫았고, `let` 선언이 첫
+사용처보다 아래에 있어 TDZ 참조 에러로 부트스트랩이 통째로 죽었다.
+둘 다 문법 검사와 단위 테스트를 전부 통과했다.
+
+데모는 실제 git 저장소를 만들어 돌린다. 통과 여부를 눈으로 확인한다.
+
+**데모가 초록이라고 안심하지 않는다.** 데모는 사람이 고른 순서로 각 기능이 한 번씩
+동작한다는 것만 보여준다. 실제로 발견된 버그는 전부 데모가 초록인 상태에서 살아 있었다.
+프로토콜 로직을 바꿨으면 `npm --prefix axmap test`(무작위 순서)와 `npm --prefix axmap run demo:chaos`(진짜 경합)를
+반드시 함께 돌린다.
+
+### 불변식을 건드리면
+
+[docs/INVARIANTS.md](docs/INVARIANTS.md) 의 I1~I7 이 이 프로젝트가 지키기로 한 성질이다.
+`axmap/src/invariants.mjs` 는 모델 검증기·카오스 테스트·`axmap audit` 이 **공유하는** 검사기다.
+여기를 고치면 세 도구의 판정이 한꺼번에 바뀐다.
+
+불변식을 추가할 때는 **그 검사가 실제로 실패하는 케이스**를 함께 넣는다.
+한 번도 실패하지 않는 검사기는 검사기가 아니다.

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 janghyojoon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# axMap
+
+**여러 AI 에이전트가 한 저장소에서 동시에 일할 때,
+사람이 그 작업을 이해하고 통제할 수 있게 하는 도구.**
+
+이름 그대로 **AI Experience(ax) 의 지도**다 — 에이전트가 코드베이스에서 길을 찾고
+서로를 피해 가는 경험을 만들고, 동시에 개발 환경의 **AI Transformation**,
+즉 사람 혼자 쓰던 저장소를 여러 에이전트가 함께 쓰는 곳으로 바꾸는 일을 함의한다.
+
+의존성 0. Node 20+ 와 git 만 있으면 돈다.
+
+> 산문에서는 `axMap`, 명령·경로·패키지 이름에서는 `axmap` 을 쓴다.
+
+---
+
+## 무엇을 푸는가
+
+AI 에게 코드를 시키면 두 가지가 동시에 어려워진다.
+
+| | 공포 | 언제 |
+|---|---|---|
+| **F1** | 내가 이해 못 하는 코드가 계속 쌓인다 | 작업 **전** |
+| **F2** | AI 가 뭘 망가뜨렸는지 모른다 | 작업 **후** |
+| **F3** | 내가 잘 하고 있는지 모른다 | 계속 |
+
+axMap 은 셋에 각각 답한다 — 처음 보는 코드베이스를 따라갈 **순서**,
+변경이 어디까지 번졌는지 보는 **PR 화면**, 그리고 수천 개 저장소에서 학습한 **기준**.
+
+그리고 그 밑에, 여러 에이전트가 같은 코드를 동시에 고치지 않게 하는
+**git 위의 선점 프로토콜**이 있다.
+
+---
+
+## 5분 안에 써보기
+
+```bash
+git clone <이 저장소> && cd axmap
+
+# 아무 저장소나 열어본다 — git 주소를 그대로 줘도 된다
+node app/server.mjs https://github.com/pallets/flask 7777
+```
+
+`http://127.0.0.1:7777` 을 열면 다섯 걸음이 나온다.
+
+```
+① 이 저장소는 무엇을 하는 물건인가
+② 실행은 어디서 시작하나
+③ 그 다음에 무엇이 불리나
+④ 어디가 활발하고 위험한가
+⑤ 이제 당신 차례
+```
+
+**팀으로 쓰려면** → [docs/ONBOARD-TEAM.md](docs/ONBOARD-TEAM.md) (3줄이면 붙는다)
+
+---
+
+## 두 개의 층
+
+### 1. 지도 — 코드가 실제로 어떻게 엮여 있나
+
+정적 `import` 그래프와 **git 공변경**(함께 바뀐 이력)을 겹쳐 본다.
+겹치지 않는 부분이 사고가 나는 자리다.
+
+```
+둘 다          import 있고 함께 바뀜        예상대로
+숨은 결합      import 없는데 함께 바뀜      🔴 코드를 읽어서는 못 찾는다
+안정된 경계    import 하지만 따로 바뀜
+판정 보류      히스토리가 부족하다
+```
+
+**엣지마다 출처가 붙는다.** 어떻게 알아냈는지 모르는 선은 긋지 않는다.
+
+### 2. 장부 — 지금 누가 어디를 잡고 있나
+
+```bash
+export AXMAP_AGENT=<자기이름>
+node bin/axmap.mjs hook install
+
+node bin/axmap.mjs claim src/auth --task T-12 --intent "토큰 만료 처리"
+node bin/axmap.mjs status      # 누가 무엇을
+node bin/axmap.mjs release     # 끝나면 즉시
+```
+
+git 은 **같은 줄**을 고쳐야 충돌을 안다. 그런데 더 위험한 것은
+같은 기능을 앞에서부터·뒤에서부터 만드는 두 사람이다 — 경로가 안 겹쳐도 어긋난다.
+장부는 그것을 코드를 쓰기 **전에** 터뜨린다.
+
+두 개의 관문으로 지킨다 — git ref 의 원자적 갱신(CAS)과 순수 함수 판정.
+불변식은 [docs/INVARIANTS.md](docs/INVARIANTS.md) 에 있고,
+모델 검증기·카오스 테스트·`axmap audit` 이 **같은 검사기**를 공유한다.
+
+---
+
+## 🔴 이 저장소가 지키는 규칙
+
+이게 이 프로젝트의 성격을 가장 잘 말한다.
+
+### 없는 것과 못 읽은 것을 같은 값으로 말하지 않는다
+
+```
+claims: []      ← "아무도 안 잡고 있다" 로 읽힌다
+claims: null    ← "모른다" 다
+```
+
+맥락 없는 신입 에이전트에게 도구만 주고 저장소를 이해시키는 실험을 반복하는데,
+**발견된 버그가 거의 전부 이 한 가지 모양이었다.** 코드는 대개 맞았고
+*말하지 않은 것*이 문제였다. 한 신입은 `[]` 를 읽고 "부딪힐 사람 없음" 이라고
+확신 있게 틀렸다.
+
+### 애매하면 거부한다 (fail-closed)
+
+같은 꼬리를 가진 파일이 둘이면 잇지 않는다. 표본이 모자라면 기준을 내지 않는다.
+**틀리게 잇는 것보다 안 잇는 것이 낫다.**
+
+### 지침에는 적용 조건이 붙는다
+
+```
+❌  함수는 20줄을 넘기지 마세요
+✅  커밋 1,500~6,000 · Python 저장소 34개에서 관찰 (스냅샷 v418)
+```
+
+적용 조건 없는 지침은 점성술이다.
+
+### 주석은 "왜" 를 쓴다
+
+무엇은 코드가 이미 말한다. 이 저장소의 주석 대부분은 **그렇게 하지 않았을 때
+실제로 무엇이 깨졌는지**를 적고 있다.
+
+---
+
+## 기준 (SSOT) — 우리 숫자에 근거를 붙인다
+
+도구의 임계값이 전부 사람이 눈으로 고른 상수였다. 그래서 공개 저장소를
+돌면서 그 상수를 **분포**로 바꾼다.
+
+🔴 **"인기 있는 걸 따라해라" 가 아니다.** 별 개수는 품질의 증거가 아니고,
+저장소 7,107개로 실제로 확인했다 —
+
+| 별 | 재수정률 |
+|---|---|
+| 0~2,000 | 0.081 |
+| 2,000~6,000 | 0.150 |
+| 6,000~20,000 | 0.103 |
+| 20,000~ | 0.149 |
+
+단조 관계가 없다. 그래서 인기 대신 **결과**를 센다 — *그 파일이 나중에
+얼마나 고쳐졌나*. 그리고 관계가 없으면 **지침을 내지 않는다.**
+
+자세히 → [docs/WHY-CORPUS.md](docs/WHY-CORPUS.md)
+
+---
+
+## 검증
+
+```bash
+npm test              # 순수 로직 + 모델 검증기
+npm run demo          # 에이전트 9명 동시 작업
+npm run demo:compare  # git 텍스트 충돌 vs 파서 판정
+npm run demo:chaos    # 진짜 경합 (무작위 순서)
+npm run smoke         # 🔴 화면이 실제로 뜨는지 헤드리스 크롬으로
+```
+
+`smoke` 가 따로 있는 이유 — 문법이 멀쩡하고 테스트가 전부 초록인데
+브라우저에서는 아무것도 안 뜬 적이 두 번 있었다.
+**되는 길만 보면 안 되는 길은 영원히 안 보인다.**
+
+---
+
+## 문서
+
+| | |
+|---|---|
+| [CLAUDE.md](CLAUDE.md) | 작업 규칙 (사람에게도 AI 에게도 같다) |
+| [docs/ONBOARD-TEAM.md](docs/ONBOARD-TEAM.md) | 팀원용 5분 안내 |
+| [docs/DECISIONS.md](docs/DECISIONS.md) | 제품 결정 D1~D15 와 **아직 못 정한 것들** |
+| [docs/WHY-CORPUS.md](docs/WHY-CORPUS.md) | 코퍼스가 왜 필요한가 |
+| [docs/PERSONA-LOOP.md](docs/PERSONA-LOOP.md) | 시각화가 실제로 일하는지 재는 법과 결과 |
+| [docs/SPEC.md](docs/SPEC.md) | 프로토콜 규격 |
+| [docs/INVARIANTS.md](docs/INVARIANTS.md) | 지키기로 한 성질 |
+
+---
+
+## 아직 안 된 것 (숨기지 않는다)
+
+- **시각화 형식이 미정이다.** 두 번의 벤치마크가 "지금 그래프는 값을 못 한다" 로
+  나왔다 — 신입들이 그림이 아니라 옆에 적힌 글을 읽고 답했다. 2차원 트리·활동 지도
+  같은 후보를 같은 방식으로 재서 정할 것이다.
+- **파서가 14개 언어를 읽는다** — 5개에서 늘렸다. 어느 언어를 먼저 할지는
+  코퍼스가 정했다(커버리지 4~12% 인 것부터). 마지막이 swift 였고, 그것이
+  새 구멍을 하나 드러냈다 — **모듈이 상한보다 크면 선을 안 그린다.**
+  안 그리는 것은 맞지만 안 그렸다고 **말하지 않으면** 화면이 "결합 없음" 으로
+  읽힌다. 지금은 말한다. 같은 구멍이 다른 언어에도 있는지는 아직 안 봤다.
+- **기준을 떼어놓고 검증(held-out)** 한 적이 없다. 그게 있어야 "관찰" 이
+  "검증된 지침" 이 된다.
+- **상관이지 인과가 아니다.** *"긴 파일이 버그를 만든다"* 가 아니라
+  *"긴 파일이 더 자주 고쳐졌다"* 다.
+
+---
+
+## 라이선스
+
+MIT. 마음대로 쓰고 고치고 팔아도 된다 — 저작권 표시만 남기면 된다.
+[LICENSE](LICENSE)
+
+---
+
+<sub>SSAFY 프로젝트로 시작했다. 한국어로 쓰고 한국어로 생각한다.</sub>